@xingwangzhe/stalux 1.25.14 → 1.26.0

package/src/schemas/collections.ts

@@ -16,11 +16,27 @@
  */
 
 import { defineCollection } from "astro:content";
-import { glob } from "astro/loaders";
+import { glob, type Loader } from "astro/loaders";
 import { z } from "astro/zod";
 
 import { configSchema } from "./config";
 
+/** Preserve glob's name, watch behavior and incremental store; only trace the load boundary. */
+function tracedLoader(loader: Loader): Loader {
+    return {
+        ...loader,
+        async load(context) {
+            const logger = context.logger.fork(`stalux/content/${context.collection}`);
+            const started = performance.now();
+            logger.debug("load started");
+            await loader.load(context);
+            logger.debug(
+                `load completed; entries=${context.store.entries().length}; elapsed=${(performance.now() - started).toFixed(1)}ms`,
+            );
+        },
+    };
+}
+
 // ---------------------------------------------------------------------------
 // 集合配置选项
 // ---------------------------------------------------------------------------
@@ -71,31 +87,37 @@ export function defineCollections(paths: CollectionPaths = {}) {
     const root = paths.contentDir ?? "stalux";
 
     const posts = defineCollection({
-        loader: glob({
-            pattern: ["*.{md,mdx}"],
-            base: `${root}/posts/`,
-            generateId: ({ data }) => String((data as Record<string, unknown>).abbrlink ?? ""),
-            retainBody: true,
-            deferRender: true,
-        }),
+        loader: tracedLoader(
+            glob({
+                pattern: ["*.{md,mdx}"],
+                base: `${root}/posts/`,
+                generateId: ({ data }) => String((data as Record<string, unknown>).abbrlink ?? ""),
+                retainBody: true,
+                deferRender: true,
+            }),
+        ),
         schema: postSchema,
     });
 
     const config = defineCollection({
-        loader: glob({
-            pattern: ["*.yml"],
-            base: `${root}/config/`,
-            generateId: ({ data }) => String((data as Record<string, unknown>).id ?? ""),
-        }),
+        loader: tracedLoader(
+            glob({
+                pattern: ["*.yml"],
+                base: `${root}/config/`,
+                generateId: ({ data }) => String((data as Record<string, unknown>).id ?? ""),
+            }),
+        ),
         schema: configSchema,
     });
 
     const about = defineCollection({
-        loader: glob({
-            base: `${root}/about`,
-            pattern: "**/*.{md,mdx}",
-            retainBody: true,
-        }),
+        loader: tracedLoader(
+            glob({
+                base: `${root}/about`,
+                pattern: "**/*.{md,mdx}",
+                retainBody: true,
+            }),
+        ),
         schema: z.object({
             title: z.string().min(1, "about.title is required"),
             description: z.string().min(1, "about.description is required"),
@@ -103,12 +125,14 @@ export function defineCollections(paths: CollectionPaths = {}) {
     });
 
     const words = defineCollection({
-        loader: glob({
-            pattern: ["*.md"],
-            base: `${root}/words/`,
-            retainBody: true,
-            deferRender: true,
-        }),
+        loader: tracedLoader(
+            glob({
+                pattern: ["*.md"],
+                base: `${root}/words/`,
+                retainBody: true,
+                deferRender: true,
+            }),
+        ),
         schema: z.object({
             source: z.string().optional(),
             link: z.url("words.link must be a valid URL").optional(),

package/src/scripts/background.ts

@@ -12,7 +12,9 @@
  *   window load（首访）与 swap 完成后、过渡动画期间（软导航）触发，
  *   此时设置背景，过渡动画中旧图淡出、新图淡入，自然 crossfade 无跳变。
  */
-export {};
+import { createClientLogger } from "./logger";
+
+const logger = createClientLogger("background");
 
 declare global {
     interface Window {
@@ -63,7 +65,11 @@ function crossfadeBackground(): void {
     const previousIndex = Number(document.body.dataset.staluxBgIndex ?? -1);
     const index = pickBackgroundIndex(previousIndex);
     const next = getLayerEl(nextLayer);
-    if (!next || !backgroundImages[index]) return;
+    if (!next || !backgroundImages[index]) {
+        logger.debug("background layer unavailable; skipped");
+        return;
+    }
+    logger.debug(`crossfade layer=${nextLayer}; index=${index}`);
 
     next.style.backgroundImage = `url('${backgroundImages[index]}')`;
     setLayerOpacity(nextLayer, 1);

package/src/scripts/clarity.ts

@@ -1,3 +1,7 @@
+import { createClientLogger } from "./logger";
+
+const logger = createClientLogger("clarity");
+
 declare global {
     interface Window {
         clarity?: ((...args: unknown[]) => void) & { q?: unknown[][] };
@@ -18,6 +22,13 @@ function load() {
     script.id = "stalux-clarity-script";
     script.async = true;
     script.src = `https://www.clarity.ms/tag/${encodeURIComponent(id)}`;
+    script.addEventListener("load", () => logger.debug("external script loaded"), { once: true });
+    script.addEventListener(
+        "error",
+        () => logger.warn("external script failed to load (network or content blocker)"),
+        { once: true },
+    );
+    logger.debug("loading external script");
     document.head.appendChild(script);
 }
 
@@ -28,5 +39,3 @@ if (!window.__staluxClarityPageLoadListener) {
 if (document.readyState === "loading")
     document.addEventListener("DOMContentLoaded", load, { once: true });
 else load();
-
-export {};

package/src/scripts/google-analytics.ts

@@ -1,3 +1,7 @@
+import { createClientLogger } from "./logger";
+
+const logger = createClientLogger("google-analytics");
+
 declare global {
     interface Window {
         dataLayer?: unknown[];
@@ -19,6 +23,15 @@ function load() {
         script.async = true;
         script.dataset.staluxGoogle = "true";
         script.src = `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(gaID)}`;
+        script.addEventListener("load", () => logger.debug("external script loaded"), {
+            once: true,
+        });
+        script.addEventListener(
+            "error",
+            () => logger.warn("external script failed to load (network or content blocker)"),
+            { once: true },
+        );
+        logger.debug("loading external script");
         document.head.appendChild(script);
     }
     if (!window.__staluxAnalyticsLoaded) {
@@ -44,5 +57,3 @@ if (!window.__staluxAnalyticsPageLoadListener) {
 if (document.readyState === "loading")
     document.addEventListener("DOMContentLoaded", load, { once: true });
 else load();
-
-export {};

package/src/scripts/logger.ts

@@ -0,0 +1,36 @@
+import { describeError } from "../utils/diagnostics";
+
+declare const __STALUX_DEBUG__: boolean;
+
+/** Browser-only sink; not an Astro runtime logger and never forwarded to a server. */
+interface ClientLogEnvironment {
+    dev: boolean;
+    detailed: boolean;
+    sink: Pick<Console, "debug" | "warn" | "error">;
+}
+
+export function createClientLogger(
+    scope: string,
+    environment: ClientLogEnvironment = {
+        dev: import.meta.env.DEV,
+        get detailed() {
+            return typeof __STALUX_DEBUG__ !== "undefined" && __STALUX_DEBUG__;
+        },
+        sink: console,
+    },
+) {
+    const prefix = `[stalux/${scope}]`;
+    return {
+        debug(message: string) {
+            if (environment.dev && environment.detailed) {
+                environment.sink.debug(`${prefix} ${message}`);
+            }
+        },
+        warn(message: string) {
+            environment.sink.warn(`${prefix} ${message}`);
+        },
+        error(message: string, error: unknown) {
+            environment.sink.error(`${prefix} ${message}: ${describeError(error)}`);
+        },
+    };
+}

package/src/scripts/navigation.ts

@@ -1,12 +1,17 @@
+import { createClientLogger } from "./logger";
+
 import { registerPageLifecycle } from "./page-runtime";
 import { upgradeAndOpenSearchDialog } from "./search-dialog";
 
+const logger = createClientLogger("navigation");
+
 interface SearchDialog extends HTMLElement {
     open?: () => void;
     close?: () => void;
 }
 
 async function openSearchDialog(): Promise<void> {
+    logger.debug("loading search UI");
     await import("@pagefind/component-ui");
     const dialog = document.querySelector<SearchDialog>("pagefind-modal#search");
     await upgradeAndOpenSearchDialog(
@@ -78,7 +83,13 @@ registerPageLifecycle("navigation", () => {
         async (event) => {
             event.preventDefault();
             closeNav();
-            await openSearchDialog();
+            try {
+                await openSearchDialog();
+                logger.debug("search dialog opened");
+            } catch (error) {
+                logger.error("search dialog failed to open; next click can retry", error);
+                throw error;
+            }
         },
         listenerOptions,
     );

package/src/scripts/page-runtime.ts

@@ -1,3 +1,5 @@
+import { createClientLogger } from "./logger";
+
 export type PageDisposer = () => void;
 export type PageMount = () => PageDisposer | undefined;
 
@@ -40,12 +42,17 @@ export function registerPageLifecycle(
     environment = getBrowserEnvironment(),
 ): PageDisposer {
     if (!environment) return () => undefined;
+    const logger = createClientLogger(key);
 
     const { host, target, queueTask } = environment;
     const registry = host.__staluxPageRuntime ?? new Map<string, RuntimeRegistration>();
     host.__staluxPageRuntime = registry;
     const existing = registry.get(key);
-    if (existing) return existing.unregister;
+    if (existing) {
+        logger.debug("registration reused");
+        return existing.unregister;
+    }
+    logger.debug("lifecycle registered");
 
     let active = true;
     const registration: RuntimeRegistration = {
@@ -53,13 +60,30 @@ export function registerPageLifecycle(
     };
 
     const disposePage = () => {
-        registration.disposePage?.();
-        registration.disposePage = undefined;
+        try {
+            if (registration.disposePage) logger.debug("disposing page");
+            registration.disposePage?.();
+        } catch (error) {
+            logger.error("page disposal failed", error);
+            throw error;
+        } finally {
+            registration.disposePage = undefined;
+        }
     };
     const mountPage = () => {
         if (!active) return;
         disposePage();
-        registration.disposePage = mount() || undefined;
+        const started = performance.now();
+        logger.debug("mount started");
+        try {
+            registration.disposePage = mount() || undefined;
+            logger.debug(
+                `mount completed in ${(performance.now() - started).toFixed(1)}ms; cleanup=${Boolean(registration.disposePage)}`,
+            );
+        } catch (error) {
+            logger.error("page mount failed", error);
+            throw error;
+        }
     };
     const handlePageLoad = () => mountPage();
     const handleBeforeSwap = () => disposePage();

package/src/scripts/photoswipe.ts

@@ -1,6 +1,10 @@
+import { createClientLogger } from "./logger";
+
 import { registerPageLifecycle } from "./page-runtime";
 import { createRetryableInitializer } from "./retryable-initializer";
 
+const logger = createClientLogger("photoswipe");
+
 const GALLERY_SELECTOR = "a.pswp-gallery-item";
 
 async function enrichPhotoSwipeData(container: Element): Promise<void> {
@@ -20,6 +24,7 @@ async function enrichPhotoSwipeData(container: Element): Promise<void> {
         try {
             await temporaryImage.decode();
         } catch {
+            logger.debug("image dimensions unavailable; skipping enrichment");
             continue;
         }
         link.dataset.pswpWidth = String(temporaryImage.naturalWidth);
@@ -38,6 +43,7 @@ registerPageLifecycle("photoswipe", () => {
     let initialized = false;
 
     const initialize = async () => {
+        logger.debug("loading lightbox modules");
         const [{ default: PhotoSwipeLightbox }, { default: PhotoSwipe }] = await Promise.all([
             import("photoswipe/lightbox"),
             import("photoswipe"),
@@ -50,7 +56,11 @@ registerPageLifecycle("photoswipe", () => {
             pswpModule: PhotoSwipe,
             initialZoomLevel: "fill",
         });
+        lightbox.on("openingAnimationEnd", () => logger.debug("opening animation completed"));
+        lightbox.on("close", () => logger.debug("lightbox closing"));
+        lightbox.on("destroy", () => logger.debug("lightbox destroyed"));
         lightbox.init();
+        logger.debug("lightbox initialized");
     };
 
     const ensureInitialized = createRetryableInitializer(initialize);
@@ -68,10 +78,11 @@ registerPageLifecycle("photoswipe", () => {
         void ensureInitialized()
             .then(() => {
                 initialized = true;
+                logger.debug(`opening image index=${clickedIndex}`);
                 lightbox?.loadAndOpen(clickedIndex, undefined, initialPoint);
             })
             .catch((error: unknown) => {
-                console.error("[stalux photoswipe] 初始化失败", error);
+                logger.error("initialization failed; next click can retry", error);
             });
     };
 

package/src/scripts/random-posts.ts

@@ -1,5 +1,8 @@
+import { createClientLogger } from "./logger";
 import { registerPageLifecycle } from "./page-runtime";
 
+const logger = createClientLogger("random-posts");
+
 const sleep = (ms: number, signal: AbortSignal) =>
     new Promise<void>((resolve) => {
         const timer = window.setTimeout(resolve, ms);
@@ -49,16 +52,19 @@ async function refresh(container: HTMLElement, fallback: string, signal: AbortSi
     await sleep(300, signal);
     if (signal.aborted) return;
     try {
+        logger.debug("refresh started");
         const posts = shuffle(await fetchPosts(signal)).slice(
             0,
             Number(container.dataset.count ?? 5),
         );
         if (signal.aborted) return;
+        logger.debug(`refresh completed; posts=${posts.length}`);
         list.innerHTML = posts.length
             ? render(posts)
             : `<li class="no-posts">${container.dataset.noPosts ?? fallback}</li>`;
-    } catch {
+    } catch (error) {
         if (signal.aborted) return;
+        logger.error("refresh failed; showing fallback", error);
         list.innerHTML = `<li class="error">${container.dataset.loadFailed ?? fallback}</li>`;
     } finally {
         if (!signal.aborted) list.style.opacity = "1";

package/src/scripts/tags-cloud.ts

@@ -1,7 +1,10 @@
 import { TagCloud } from "@xingwangzhe/tags-cloud";
+import { createClientLogger } from "./logger";
 
 import { registerPageLifecycle } from "./page-runtime";
 
+const logger = createClientLogger("tags-cloud");
+
 interface LinkTag {
     type: "link";
     text: string;
@@ -11,7 +14,10 @@ interface LinkTag {
 function parseTags(value: string | undefined): LinkTag[] {
     try {
         const parsed: unknown = JSON.parse(value ?? "[]");
-        if (!Array.isArray(parsed)) return [];
+        if (!Array.isArray(parsed)) {
+            logger.warn("tag data is not an array; using empty list");
+            return [];
+        }
         return parsed.filter(
             (tag): tag is LinkTag =>
                 typeof tag === "object" &&
@@ -24,13 +30,17 @@ function parseTags(value: string | undefined): LinkTag[] {
                 typeof tag.url === "string",
         );
     } catch {
+        logger.warn("tag data decoding failed; using empty list");
         return [];
     }
 }
 
 registerPageLifecycle("tags-cloud", () => {
     const mobile = window.matchMedia("(max-width: 768px)").matches;
-    if (mobile) return;
+    if (mobile) {
+        logger.debug("mobile layout; cloud skipped");
+        return;
+    }
 
     const container = document.getElementById("tags-canvas");
     if (!container) return;
@@ -55,5 +65,6 @@ registerPageLifecycle("tags-cloud", () => {
         color: "#ffffff",
         fontFamily: "system-ui, -apple-system, sans-serif",
     });
+    logger.debug(`cloud initialized; tags=${tags.length}`);
     return () => cloud.destroy();
 });

package/src/scripts/vercount.ts

@@ -1,3 +1,7 @@
+import { createClientLogger } from "./logger";
+
+const logger = createClientLogger("vercount");
+
 declare global {
     interface Window {
         __staluxVerCountLoaded?: boolean;
@@ -11,6 +15,13 @@ function load() {
     script.defer = true;
     script.dataset.staluxVercount = "true";
     script.src = "https://events.vercount.one/js";
+    script.addEventListener("load", () => logger.debug("external script loaded"), { once: true });
+    script.addEventListener(
+        "error",
+        () => logger.warn("external script failed to load (network or content blocker)"),
+        { once: true },
+    );
+    logger.debug("loading external script");
     document.head.appendChild(script);
 }
 
@@ -18,5 +29,3 @@ document.addEventListener("astro:page-load", load);
 if (document.readyState === "loading")
     document.addEventListener("DOMContentLoaded", load, { once: true });
 else load();
-
-export {};

package/src/scripts/view-transitions.ts

@@ -1,4 +1,7 @@
 import { getRouteKind } from "@utils/view-transitions";
+import { createClientLogger } from "./logger";
+
+const logger = createClientLogger("view-transitions");
 
 interface TransitionWindow extends Window {
     __STALUX_VT_LISTENER__?: boolean;
@@ -7,6 +10,7 @@ interface TransitionWindow extends Window {
 function setRouteState(pathname: string): void {
     const html = document.documentElement;
     const route = getRouteKind(pathname);
+    logger.debug(`route state=${route}`);
     html.dataset.staluxRoute = route;
     document.querySelector("main.stalux-main")?.setAttribute("data-stalux-route", route);
 }

package/src/scripts/waline.ts

@@ -1,7 +1,10 @@
 import { init, type WalineInitOptions } from "@waline/client";
+import { createClientLogger } from "./logger";
 
 import { registerPageLifecycle } from "./page-runtime";
 
+const logger = createClientLogger("waline");
+
 function isRecord(value: unknown): value is Record<string, unknown> {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -18,11 +21,13 @@ registerPageLifecycle("waline", () => {
         );
         decoded = JSON.parse(new TextDecoder().decode(bytes));
     } catch (error) {
-        console.error("Failed to decode Waline config:", error);
+        logger.warn(
+            `config decoding failed (${error instanceof Error ? error.name : "unknown error"})`,
+        );
         return;
     }
     if (!isRecord(decoded) || typeof decoded.serverURL !== "string") {
-        console.warn("Waline serverURL not configured");
+        logger.warn("serverURL not configured");
         return;
     }
 
@@ -33,6 +38,7 @@ registerPageLifecycle("waline", () => {
         path: typeof decoded.path === "string" ? decoded.path : window.location.pathname,
     } as WalineInitOptions;
     const instance = init(options);
+    logger.debug("comment widget initialized");
 
     return () => instance?.destroy();
 });

package/src/scripts/webmcp.ts

@@ -1,3 +1,5 @@
+import { createClientLogger } from "./logger";
+
 /**
  * Stalux WebMCP 工具注册（纯前端，零后端）
  *
@@ -20,6 +22,8 @@
 // 放在模块顶部 import，保证其副作用在下方注册逻辑执行前完成。
 import "@mcp-b/webmcp-polyfill";
 
+const logger = createClientLogger("webmcp");
+
 declare global {
     interface Window {
         __STALUX_SITE_INFO__?: {
@@ -78,18 +82,23 @@ function err(
     message: string,
     extra?: Record<string, unknown>,
 ): { ok: false; code: string; message: string } & Record<string, unknown> {
+    logger.debug(`tool result error=${code}`);
     return { ok: false, code, message, ...extra };
 }
 
 async function fetchJSON(url: string): Promise<unknown> {
     const r = await fetch(url, { headers: { Accept: "application/json" } });
-    if (!r.ok) return null;
+    if (!r.ok) {
+        logger.debug(`JSON request failed; status=${r.status}`);
+        return null;
+    }
     return r.json();
 }
 
 /** 动态加载 Pagefind 全文索引（仅首次调用，结果跨调用缓存） */
 let pagefindLoadPromise: Promise<{ search: (q: string) => Promise<unknown> } | null> | null = null;
 async function loadPagefind(): Promise<{ search: (q: string) => Promise<unknown> } | null> {
+    logger.debug(pagefindLoadPromise ? "Pagefind module cache hit" : "loading Pagefind module");
     if (!pagefindLoadPromise) {
         pagefindLoadPromise = (async () => {
             try {
@@ -99,6 +108,7 @@ async function loadPagefind(): Promise<{ search: (q: string) => Promise<unknown>
                 const mod = await import(/* @vite-ignore */ url);
                 return mod.default ?? mod;
             } catch {
+                logger.warn("Pagefind index unavailable; search requires a production index");
                 return null;
             }
         })();
@@ -422,6 +432,7 @@ function searchPostsTool(): WebMCPTool {
                             excerpt: (data?.excerpt ?? "").slice(0, 240),
                         };
                     } catch {
+                        logger.warn("search result data unavailable; skipping result");
                         return null;
                     }
                 }),
@@ -537,6 +548,7 @@ async function registerTools(): Promise<{ registered: string[]; reason?: string
     const doc = document as DocumentWithModelContext;
     const ctx = doc.modelContext;
     if (!ctx || typeof ctx.registerTool !== "function") {
+        logger.debug("modelContext unavailable; registration skipped");
         return { registered: [], reason: "unsupported" };
     }
 
@@ -545,7 +557,7 @@ async function registerTools(): Promise<{ registered: string[]; reason?: string
         try {
             activeController.abort();
         } catch {
-            /* 忽略注销异常 */
+            logger.debug("previous registration cleanup unavailable");
         }
     }
     const controller = new AbortController();
@@ -559,7 +571,7 @@ async function registerTools(): Promise<{ registered: string[]; reason?: string
             await ctx.registerTool(tool, { signal: controller.signal });
             registered.push(tool.name);
         } catch (e) {
-            console.warn(`[stalux/webmcp] 注册失败: ${tool.name}`, e);
+            logger.error(`tool registration failed: ${tool.name}`, e);
         }
     }
     return { registered };
@@ -572,16 +584,15 @@ async function registerTools(): Promise<{ registered: string[]; reason?: string
 if (typeof document !== "undefined") {
     // 首屏加载 + View Transitions 软导航都执行（soft navigation 时页面状态会重建）
     document.addEventListener("astro:page-load", () => {
-        void registerTools().then((r) => {
-            if (r.reason === "unsupported") return; // 无 WebMCP 环境，静默跳过
-            if (r.registered.length) {
-                console.info(
-                    "[stalux/webmcp] 已注册 " +
-                        r.registered.length +
-                        " 个工具: " +
-                        r.registered.join(", "),
-                );
-            }
-        });
+        void registerTools()
+            .then((r) => {
+                if (r.reason === "unsupported") return; // 无 WebMCP 环境，静默跳过
+                if (r.registered.length) {
+                    logger.debug(
+                        `已注册 ${r.registered.length} 个工具: ${r.registered.join(", ")}`,
+                    );
+                }
+            })
+            .catch((error: unknown) => logger.error("registration batch failed", error));
     });
 }