@xingwangzhe/stalux 1.46.2 → 1.47.0

package/src/scripts/search-engine-entry.ts

@@ -0,0 +1,48 @@
+import { sitePath } from "../utils/site-path";
+import { createEnhancedSearch, type NativeSearch } from "./search-engine";
+
+const base = import.meta.env.BASE_URL;
+interface PagefindModule {
+    createInstance: (options: Record<string, unknown>) => NativeSearch;
+}
+const moduleUrl = sitePath("pagefind/pagefind.js", base);
+let modulePromise: Promise<PagefindModule> | undefined;
+function loadNative(): Promise<PagefindModule> {
+    if (!modulePromise) {
+        modulePromise = import(/* @vite-ignore */ moduleUrl);
+        void modulePromise?.catch(() => {
+            modulePromise = undefined;
+        });
+    }
+    return modulePromise as Promise<PagefindModule>;
+}
+
+/** Public Component UI bundle contract; no private instance fields or hooks are patched. */
+export function createInstance(options: Record<string, unknown> = {}) {
+    let native: Promise<NativeSearch> | undefined;
+    const load = () => {
+        if (!native) {
+            native = loadNative().then((module) =>
+                module.createInstance({
+                    ranking: { pageLength: 0.4, termFrequency: 0.8 },
+                    ...options,
+                }),
+            );
+            void native.catch(() => {
+                native = undefined;
+            });
+        }
+        return native;
+    };
+    return createEnhancedSearch(load, base);
+}
+let instance: ReturnType<typeof createInstance> | undefined;
+const shared = () => {
+    instance ??= createInstance();
+    return instance;
+};
+export const search = (...args: Parameters<NativeSearch["search"]>) => shared().search(...args);
+export const options = (...args: Parameters<NativeSearch["options"]>) => shared().options(...args);
+export const filters = () => shared().filters();
+export const mergeIndex = (...args: Parameters<NativeSearch["mergeIndex"]>) =>
+    shared().mergeIndex(...args);

package/src/scripts/search-engine.ts

@@ -0,0 +1,219 @@
+import {
+    CJK,
+    type CjkDocument,
+    type CjkManifest,
+    cjkGrams,
+    gramShard,
+    normalizeSearch,
+} from "../utils/cjk-search";
+import { sitePath } from "../utils/site-path";
+import { createClientLogger } from "./logger";
+
+export interface SearchData {
+    url: string;
+    meta?: Record<string, string>;
+    content?: string;
+    excerpt?: string;
+    plain_excerpt?: string;
+    filters?: Record<string, string[]>;
+}
+export interface SearchResult {
+    id: string;
+    data: () => Promise<SearchData>;
+}
+export interface SearchResponse {
+    results: SearchResult[];
+    filters?: Record<string, Record<string, number>>;
+    totalFilters?: Record<string, Record<string, number>>;
+    unfilteredTotalCount?: number;
+}
+export interface SearchOptions {
+    filters?: Record<string, string | string[]>;
+}
+export interface NativeSearch {
+    search: (query: string | null, options?: SearchOptions) => Promise<SearchResponse>;
+    options: (options: Record<string, unknown>) => Promise<void>;
+    filters: () => Promise<Record<string, Record<string, number>>>;
+    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, "\\$&"))
+        .sort((a, b) => b.length - a.length)
+        .join("|");
+    const regex = new RegExp(pattern, "giu");
+    let end = 0;
+    let highlighted = "";
+    for (const match of plain.matchAll(regex)) {
+        highlighted +=
+            escapeHtml(plain.slice(end, match.index)) + `<mark>${escapeHtml(match[0])}</mark>`;
+        end = match.index + match[0].length;
+    }
+    return { plain_excerpt: plain, excerpt: highlighted + escapeHtml(plain.slice(end)) };
+}
+
+export function createEnhancedSearch(
+    native: Promise<NativeSearch> | (() => Promise<NativeSearch>),
+    base = import.meta.env.BASE_URL,
+    request: typeof fetch = fetch,
+    language = () => document.documentElement.lang,
+) {
+    const getNative = () => (typeof native === "function" ? native() : native);
+    const directory = sitePath("pagefind/cjk/", base);
+    const cache = new Map<string, Promise<unknown>>();
+    function json<T>(file: string): Promise<T> {
+        let pending = cache.get(file);
+        if (!pending) {
+            pending = request(directory + file).then((response) => {
+                if (!response.ok) throw new Error(`CJK index HTTP ${response.status}`);
+                return response.json();
+            });
+            cache.set(file, pending);
+            void pending.catch(() => cache.delete(file));
+        }
+        return pending as Promise<T>;
+    }
+    const ids = new Map<string, Promise<string | undefined>>();
+    async function nativeId(api: NativeSearch, record: CjkDocument, original: SearchResult[]) {
+        const post = record.filters.post?.[0];
+        if (post) {
+            let pending = ids.get(record.url);
+            if (!pending) {
+                pending = api
+                    .search(null, { filters: { post } })
+                    .then((result) => result.results[0]?.id);
+                ids.set(record.url, pending);
+                void pending.catch(() => ids.delete(record.url));
+            }
+            return pending;
+        }
+        // Non-post pages are uncommon; resolve existing hits only to avoid duplicate URLs.
+        for (const result of original) {
+            if ((await result.data()).url.replace(/\/$/u, "") === record.url.replace(/\/$/u, ""))
+                return result.id;
+        }
+    }
+    async function search(query: string | null, options?: SearchOptions): Promise<SearchResponse> {
+        const api = await getNative();
+        if (query === null || !query.trim()) return api.search(query, options);
+        const normalized = normalizeSearch(query);
+        let original = await api.search(query, options);
+        // Keep Pagefind's quoted phrase semantics and compound filter semantics intact.
+        if (
+            /["“”]/u.test(query) ||
+            Object.values(options?.filters ?? {}).some((value) => value.length)
+        )
+            return original;
+        if (normalized !== query) {
+            const variant = await api.search(normalized, options);
+            const originalIds = new Set(original.results.map((result) => result.id));
+            const results = [
+                ...original.results,
+                ...variant.results.filter((result) => !originalIds.has(result.id)),
+            ];
+            original = { ...original, results, unfilteredTotalCount: results.length };
+        }
+        if (!CJK.test(normalized)) return original;
+        try {
+            const manifest = await json<CjkManifest>("manifest.json");
+            const grams = cjkGrams(normalized);
+            const shardKeys = [...new Set(grams.map(gramShard))];
+            const shards = new Map(
+                await Promise.all(
+                    shardKeys.map(
+                        async (key) =>
+                            [
+                                key,
+                                manifest.shards[key]
+                                    ? await json<Record<string, number[]>>(
+                                          manifest.shards[key] as string,
+                                      )
+                                    : {},
+                            ] as const,
+                    ),
+                ),
+            );
+            const lists = grams
+                .map((gram) => shards.get(gramShard(gram))?.[gram] ?? [])
+                .sort((a, b) => a.length - b.length);
+            let candidates = new Set(lists[0] ?? []);
+            for (const list of lists.slice(1)) {
+                const allowed = new Set(list);
+                candidates = new Set([...candidates].filter((id) => allowed.has(id)));
+            }
+            const terms = normalized.split(" ").filter(Boolean);
+            const matches: Array<{ record: CjkDocument; content: string; score: number }> = [];
+            // Bound text downloads independently of result count. Text is fetched only for n-gram candidates.
+            const pending = [...candidates];
+            let cursor = 0;
+            await Promise.all(
+                Array.from({ length: Math.min(6, pending.length) }, async () => {
+                    while (cursor < pending.length) {
+                        const record = manifest.documents[pending[cursor++] as number];
+                        if (!record || record.language.toLowerCase() !== language().toLowerCase())
+                            continue;
+                        const { content } = await json<{ content: string }>(record.file);
+                        const normalizedContent = normalizeSearch(content);
+                        if (!terms.every((term) => normalizedContent.includes(term))) continue;
+                        const title = normalizeSearch(record.title);
+                        const description = normalizeSearch(record.description);
+                        const score =
+                            title === normalized
+                                ? 100
+                                : title.includes(normalized)
+                                  ? 80
+                                  : terms.every((term) => title.includes(term))
+                                    ? 60
+                                    : terms.every((term) => description.includes(term))
+                                      ? 40
+                                      : 20;
+                        matches.push({ record, content, score });
+                    }
+                }),
+            );
+            matches.sort((a, b) => b.score - a.score || a.record.url.localeCompare(b.record.url));
+            const supplemental: SearchResult[] = [];
+            for (const { record, content } of matches) {
+                const id = await nativeId(api, record, original.results);
+                supplemental.push({
+                    id: id ?? `cjk:${record.url}`,
+                    data: () =>
+                        Promise.resolve({
+                            url: record.url,
+                            meta: { title: record.title },
+                            content,
+                            filters: record.filters,
+                            ...excerpt(content, terms),
+                        }),
+                });
+            }
+            const seen = new Set(supplemental.map((result) => result.id));
+            const results = [
+                ...supplemental,
+                ...original.results.filter((result) => !seen.has(result.id)),
+            ];
+            return { ...original, results, unfilteredTotalCount: results.length };
+        } catch {
+            logger.warn("CJK substring index unavailable; using Pagefind");
+            return original;
+        }
+    }
+    return {
+        search,
+        options: async (options: Record<string, unknown>) => (await getNative()).options(options),
+        filters: async () => (await getNative()).filters(),
+        mergeIndex: async (url: string, options?: Record<string, unknown>) =>
+            (await getNative()).mergeIndex(url, options),
+    };
+}

package/src/scripts/shell-hydration.ts

@@ -0,0 +1,60 @@
+/**
+ * Keep a shell's frame, refresh only the parts that describe the page.
+ *
+ * A `data-swup-persist` node is kept whole by Swup: that is what makes the
+ * sidebars, the header and the footer survive a visit. For a container whose
+ * *frame* is stable but whose *contents* belong to the page (the article's TOC,
+ * tag list and category list), keeping the node whole would show the previous
+ * article's headings. Marking it `data-stalux-shell-slot` says: keep this node,
+ * take the children from the page we are navigating to.
+ *
+ * Doing it here, synchronously after the swap and before `astro:after-swap`, means
+ * every page module that mounts later sees the refreshed lists and nothing has to
+ * be measured or re-rendered a second time.
+ */
+const SLOT = "[data-stalux-shell-slot]";
+
+/** Persist nodes that existed before this swap; only their slots need refilling. */
+const retained = new WeakSet<Element>();
+
+/** Call before the content is replaced, while the old document is still live. */
+export function markRetainedShells(): void {
+    for (const element of document.querySelectorAll("[data-swup-persist]")) retained.add(element);
+}
+
+export function hydrateShells(next: Document | undefined): number {
+    if (!next || typeof next.querySelector !== "function") return 0;
+    let hydrated = 0;
+    for (const live of document.querySelectorAll<HTMLElement>(SLOT)) {
+        const slot = live.getAttribute?.("data-stalux-shell-slot");
+        if (!slot) continue;
+        // A slot that arrived with the incoming document already holds the right
+        // children; replacing them again would dirty layout for nothing.
+        const shell = live.closest("[data-swup-persist]");
+        if (!(shell && retained.has(shell))) continue;
+        const incoming = next.querySelector<HTMLElement>(`[data-stalux-shell-slot="${slot}"]`);
+        if (!incoming) continue;
+        // Two articles often share the same tags or the same category. Writing
+        // identical children back would dirty layout for a subtree that is
+        // already correct.
+        if (live.innerHTML === incoming.innerHTML) continue;
+        // The incoming nodes belong to another document; importNode adopts them.
+        const fresh = document.importNode(incoming, true);
+        live.replaceChildren(...fresh.childNodes);
+        // These lists are new content even though their frame is old, so the
+        // unroll cue still applies to them.
+        for (const group of live.querySelectorAll<HTMLElement>("[data-stalux-reveal]"))
+            group.setAttribute("data-stalux-shell-fresh", "");
+        hydrated++;
+    }
+    // A shell that is itself new (first visit to an article, or any move between
+    // page types) brings fresh lists with it: they are content, not a kept frame.
+    for (const group of document.querySelectorAll<HTMLElement>(
+        "[data-swup-persist] [data-stalux-reveal]",
+    )) {
+        const shell = group.closest("[data-swup-persist]");
+        if (shell && !retained.has(shell) && !group.hasAttribute("data-stalux-shell-fresh"))
+            group.setAttribute("data-stalux-shell-fresh", "");
+    }
+    return hydrated;
+}

package/src/scripts/smooth-scroll.ts

@@ -12,9 +12,9 @@ export interface PageGlide {
 }
 
 /** Bound the pre-swap return-to-top so a 6000px article does not add a second. */
-const GLIDE_MIN_MS = 160;
-const GLIDE_MAX_MS = 360;
-const GLIDE_SAFETY_MS = 760;
+const GLIDE_MIN_MS = 80;
+const GLIDE_MAX_MS = 180;
+const GLIDE_SAFETY_MS = 380;
 
 /**
  * Walk the current document back to the top before the container is replaced.
@@ -42,7 +42,7 @@ export function glideToTop(): PageGlide {
 
     // Longer documents take proportionally longer, but the ceiling keeps the
     // whole cue inside the same budget as the content fade.
-    const duration = Math.min(GLIDE_MAX_MS, GLIDE_MIN_MS + startTop / 10);
+    const duration = Math.min(GLIDE_MAX_MS, GLIDE_MIN_MS + startTop / 20);
     let frame: number | undefined;
     let settled = false;
     const release = () => {

package/src/scripts/swup-internals.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Type restoration for swup members we depend on but the package omits.
+ *
+ * `Visit.abort()` exists in swup 4.10.0's source (`src/modules/Visit.ts`) and is
+ * marked `/** @internal *\/`, so it is stripped from the published
+ * `dist/types/modules/Visit.d.ts`. The router genuinely needs it: superseding a
+ * visit mid-navigation means marking the old one aborted, and no public API does
+ * that.
+ *
+ * Declaring it here is the honest alternative to casting at the call site: the
+ * compiler now checks the name and the signature everywhere, and there is exactly
+ * one place to revisit when swup changes. Callers still guard with
+ * `typeof visit.abort === "function"` so a future removal degrades to a no-op
+ * instead of throwing in the middle of a navigation.
+ *
+ * Recheck on every swup upgrade:
+ *   grep -n "@internal" node_modules/swup/src/modules/Visit.ts
+ *   grep -n "abort" node_modules/swup/dist/types/modules/Visit.d.ts
+ */
+
+export {};
+
+declare module "swup" {
+    interface Visit {
+        /**
+         * Mark this visit aborted. Internal in 4.10.0; see the note above.
+         * Not a public API: do not call it outside the router adapter.
+         */
+        abort(): void;
+    }
+}

package/src/scripts/swup-router.ts

@@ -12,6 +12,7 @@ import "./navigation-client";
 import { prepareNavigationScripts } from "./navigation-scripts";
 import { prepareRouteMotion, type RouteMotion } from "./route-motion";
 import { animateRouteOut } from "./route-out";
+import { hydrateShells, markRetainedShells } from "./shell-hydration";
 import { cancelPageScroll, glideToTop, type PageGlide, scrollPage } from "./smooth-scroll";
 
 interface NavigationContext {
@@ -35,9 +36,11 @@ type Position = { top: number; left: number; focus?: string };
 const MAIN = "main[data-stalux-route]";
 
 function abortObsoleteVisit(visit: Visit): void {
-    // Swup 4.10 ships abort() but strips @internal members from its .d.ts.
-    // Pin core to that audited version; recheck this adapter when upgrading it.
-    (visit as Visit & { abort: () => void }).abort();
+    // `abort()` is @internal in swup 4.10.0 and stripped from the published
+    // types; swup-internals.d.ts restores the declaration, so this is checked
+    // like any other member. The guard keeps a future removal from throwing in
+    // the middle of a navigation: every caller returns right after this anyway.
+    if (typeof visit.abort === "function") visit.abort();
 }
 
 function dispatchNavigation(name: string, context: NavigationContext, nextDocument?: Document) {
@@ -88,9 +91,9 @@ export function installSwupRouter(): Swup {
     window.addEventListener(
         "popstate",
         (event) => {
-            browserMotion =
-                (event as PopStateEvent & { hasUAVisualTransition?: boolean })
-                    .hasUAVisualTransition === true;
+            // hasUAVisualTransition is part of the DOM lib's PopStateEvent, so
+            // this reads the event directly; the listener is typed for popstate.
+            browserMotion = event.hasUAVisualTransition === true;
         },
         { capture: true },
     );
@@ -181,8 +184,10 @@ export function installSwupRouter(): Swup {
             left: window.scrollX,
             focus,
         });
-        if (historyPositions.size > 64)
-            historyPositions.delete(historyPositions.keys().next().value as number);
+        if (historyPositions.size > 64) {
+            const oldest = historyPositions.keys().next();
+            if (!oldest.done) historyPositions.delete(oldest.value);
+        }
         const from = new URL(visit.from.url + (visit.from.hash ?? ""), window.location.origin);
         const to = new URL(visit.to.url + (visit.to.hash ?? ""), window.location.origin);
         const navigationType = visit.history.popstate ? "traverse" : visit.history.action;
@@ -261,7 +266,7 @@ export function installSwupRouter(): Swup {
         // missing document on an aborted visit is not a failed navigation.
         if (context?.controller.signal.aborted || visit.done || visit !== swup.visit) return;
         const next = visit.to.document;
-        if (!context || !next || !replace) throw new Error("Missing Swup document");
+        if (!(context && next && replace)) throw new Error("Missing Swup document");
         if (context.controller.signal.aborted) return;
         // Two cues overlap on the outgoing document: the content stage leaving,
         // and the page walking back to the top. Persisted sidebars, the header
@@ -283,6 +288,9 @@ export function installSwupRouter(): Swup {
         html.dataset.staluxVtPreset = context.preset;
         context.motion = prepareRouteMotion(dispatchNavigation("astro:before-swap", context, next));
         if (context.controller.signal.aborted) return;
+        // Remember which shells exist now: after the swap only those slots need
+        // refilling, because only those nodes came from the previous document.
+        markRetainedShells();
         await replace(visit, args);
         // The stage node survives the swap, so the filled exit effect still holds
         // the incoming document at zero opacity. It is released inside
@@ -306,6 +314,10 @@ export function installSwupRouter(): Swup {
         }
         html.dataset.staluxRoute = getRouteKind(context.to.pathname);
         visibleHistoryIndex = Number(window.history.state?.index ?? visibleHistoryIndex);
+        // Kept shells whose contents belong to the page (the article sidebars'
+        // lists) take their children from the incoming document now, before any
+        // page module mounts, so nothing needs to re-render or re-measure later.
+        hydrateShells(next);
         dispatchNavigation("astro:after-swap", context, next);
         // The entry cue has to own the first painted frame of the new document.
         // content:scroll is an await and a rAF away, and running the incoming
@@ -419,8 +431,11 @@ export function installSwupRouter(): Swup {
         }
     });
     swup.hooks.on("cache:set", () => {
-        while (swup.cache.size > 32)
-            swup.cache.delete(swup.cache.all.keys().next().value as string);
+        while (swup.cache.size > 32) {
+            const oldest = swup.cache.all.keys().next();
+            if (oldest.done) break;
+            swup.cache.delete(oldest.value);
+        }
     });
     // Parsed DOM, not window.load: slow third-party resources cannot hold the
     // first page's interactions hostage. Page-runtime dedupes the early mount.

package/src/scripts/waline.ts

@@ -10,7 +10,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 registerPageLifecycle("waline", () => {
     const container = document.querySelector<HTMLElement>("#waline-container");
     const commentElement = document.querySelector<HTMLElement>("#waline-comment");
-    if (!container || !commentElement) return;
+    if (!(container && commentElement)) return;
 
     let decoded: unknown;
     try {