@xingwangzhe/stalux 1.35.1 → 1.35.3

package/src/internal/html-images.ts

@@ -10,7 +10,10 @@ export interface HtmlImage {
 }
 
 /** Source ranges preserve scripts and code-copy attributes byte-for-byte. */
-export function findHtmlImages(html: string): HtmlImage[] {
+export function findHtmlImages(
+    html: string,
+    document = parse(html, { sourceCodeLocationInfo: true }),
+): HtmlImage[] {
     const images: HtmlImage[] = [];
     function visit(node: DefaultTreeAdapterMap["node"], body?: number) {
         if ("tagName" in node) {
@@ -35,10 +38,28 @@ export function findHtmlImages(html: string): HtmlImage[] {
         }
         if ("childNodes" in node) for (const child of node.childNodes) visit(child, body);
     }
-    visit(parse(html, { sourceCodeLocationInfo: true }));
+    visit(document);
     return images.sort((left, right) => left.start - right.start);
 }
 
+export function imageLoadingUpdates(images: HtmlImage[]): Map<HtmlImage, Record<string, string>> {
+    const firstSeen = new Set<number>();
+    const changes = new Map<HtmlImage, Record<string, string>>();
+    for (const image of images) {
+        if (image.body === undefined) continue;
+        const first = !firstSeen.has(image.body);
+        firstSeen.add(image.body);
+        const updates: Record<string, string> = {
+            decoding: image.attributes.get("decoding") || "async",
+            loading: first ? "eager" : "lazy",
+        };
+        if (first) updates.fetchpriority = "high";
+        else if (image.attributes.get("fetchpriority") === "high") updates.fetchpriority = "auto";
+        changes.set(image, updates);
+    }
+    return changes;
+}
+
 export function updateImageTag(image: HtmlImage, updates: Record<string, string>): string {
     let tag = image.tag;
     const edits: Array<{ start: number; end: number; value: string }> = [];

package/src/internal/image-dimensions.ts

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { findHtmlImages, updateImageTag } from "./html-images";
+import { findHtmlImages, type HtmlImage, imageLoadingUpdates, updateImageTag } from "./html-images";
 
 export type ImageDimensions = { width: number; height: number };
 
@@ -72,41 +72,68 @@ export function readImageDimensions(data: Buffer): ImageDimensions | undefined {
 }
 
 /** Add width/height to same-origin emitted images so their space is reserved before download. */
-export async function addLocalImageDimensions(html: string, outputDir: string): Promise<string> {
-    const dimensionsCache = new Map<string, Promise<ImageDimensions | undefined>>();
+export async function addLocalImageDimensions(
+    html: string,
+    outputDir: string,
+    options: {
+        images?: HtmlImage[];
+        cache?: Map<string, Promise<ImageDimensions | undefined>>;
+        loadingPolicy?: boolean;
+        dependencies?: Set<string>;
+    } = {},
+): Promise<string> {
+    const dimensionsCache =
+        options.cache ?? new Map<string, Promise<ImageDimensions | undefined>>();
     const root = path.resolve(outputDir);
-    const tags = findHtmlImages(html);
-
-    for (const image of tags.reverse()) {
-        if (image.attributes.has("width") && image.attributes.has("height")) continue;
+    const images = options.images ?? findHtmlImages(html);
+    const loading = options.loadingPolicy ? imageLoadingUpdates(images) : new Map();
+    const replacements: Array<{ start: number; end: number; tag: string }> = [];
+    for (const image of images) {
+        const updates: Record<string, string> = { ...loading.get(image) };
         const src = image.attributes.get("src");
-        if (!src) continue;
-
-        let filePath: string;
-        try {
-            const url = new URL(src, "https://stalux.invalid");
-            if (url.origin !== "https://stalux.invalid") continue;
-            filePath = path.resolve(root, `.${decodeURIComponent(url.pathname)}`);
-        } catch {
-            continue;
+        if (src && !(image.attributes.has("width") && image.attributes.has("height"))) {
+            let filePath: string | undefined;
+            try {
+                const url = new URL(src, "https://stalux.invalid");
+                if (url.origin === "https://stalux.invalid") {
+                    const candidate = path.resolve(root, `.${decodeURIComponent(url.pathname)}`);
+                    if (candidate === root || candidate.startsWith(`${root}${path.sep}`))
+                        filePath = candidate;
+                }
+            } catch {
+                // Invalid image URLs still receive the loading policy.
+            }
+            if (filePath) {
+                options.dependencies?.add(filePath);
+                let dimensions = dimensionsCache.get(filePath);
+                if (!dimensions) {
+                    dimensions = readFile(filePath)
+                        .then(readImageDimensions)
+                        .catch(() => undefined);
+                    dimensionsCache.set(filePath, dimensions);
+                }
+                const size = await dimensions;
+                if (size && size.width > 0 && size.height > 0) {
+                    if (!image.attributes.has("width")) updates.width = String(size.width);
+                    if (!image.attributes.has("height")) updates.height = String(size.height);
+                }
+            }
         }
-        if (filePath !== root && !filePath.startsWith(`${root}${path.sep}`)) continue;
-
-        let dimensions = dimensionsCache.get(filePath);
-        if (!dimensions) {
-            dimensions = readFile(filePath)
-                .then(readImageDimensions)
-                .catch(() => undefined);
-            dimensionsCache.set(filePath, dimensions);
+        if (Object.keys(updates).length) {
+            replacements.push({
+                start: image.start,
+                end: image.end,
+                tag: updateImageTag(image, updates),
+            });
         }
-        const size = await dimensions;
-        if (!size || size.width <= 0 || size.height <= 0) continue;
-
-        const updates: Record<string, string> = {};
-        if (!image.attributes.has("width")) updates.width = String(size.width);
-        if (!image.attributes.has("height")) updates.height = String(size.height);
-        const updated = updateImageTag(image, updates);
-        html = html.slice(0, image.start) + updated + html.slice(image.end);
     }
-    return html;
+    if (!replacements.length) return html;
+    const parts: string[] = [];
+    let offset = 0;
+    for (const replacement of replacements) {
+        parts.push(html.slice(offset, replacement.start), replacement.tag);
+        offset = replacement.end;
+    }
+    parts.push(html.slice(offset));
+    return parts.join("");
 }

package/src/internal/page-output-cache.ts

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+export interface CachedPageOutput {
+    html: string;
+    font?: { filename: string; sourcePath: string };
+}
+
+const digest = (value: string | Buffer) => createHash("sha256").update(value).digest("hex");
+
+/** Content hashes include dependencies even when their public URL has not changed. */
+export async function createPageOutputCache(
+    directory: string,
+    dependencies: readonly string[],
+    font?: Buffer,
+    assets: readonly string[] = [],
+) {
+    const hash = createHash("sha256").update("stalux-page-output-v1\0");
+    if (font) hash.update(font);
+    for (const dependency of [...dependencies].sort()) {
+        hash.update(dependency).update("\0");
+        hash.update(await fs.readFile(dependency)).update("\0");
+    }
+    const namespace = path.join(directory, hash.digest("hex"));
+    await fs.mkdir(namespace, { recursive: true });
+    const assetDigests = new Map<string, string>();
+    for (const asset of assets) assetDigests.set(asset, digest(await fs.readFile(asset)));
+    const key = (entry: string, html: string) => digest(`${entry}\0${html}`);
+    return {
+        async get(entry: string, html: string): Promise<CachedPageOutput | undefined> {
+            try {
+                const record = JSON.parse(
+                    await fs.readFile(path.join(namespace, `${key(entry, html)}.json`), "utf8"),
+                );
+                if (typeof record.html !== "string" || digest(record.html) !== record.digest)
+                    return undefined;
+                if (!Array.isArray(record.assets)) return undefined;
+                for (const [asset, expected] of record.assets) {
+                    if ((assetDigests.get(asset) ?? null) !== expected) return undefined;
+                }
+                if (record.font) {
+                    if (
+                        !/^page-[a-f\d]+\.woff2$/u.test(record.font.filename) ||
+                        typeof record.font.sourcePath !== "string" ||
+                        !(await fs.stat(record.font.sourcePath)).isFile()
+                    )
+                        return undefined;
+                }
+                return { html: record.html, font: record.font };
+            } catch {
+                // Missing, truncated, or invalid cache entries are rebuilt from source.
+                return undefined;
+            }
+        },
+        async set(
+            entry: string,
+            html: string,
+            output: CachedPageOutput,
+            referencedAssets: readonly string[] = [],
+        ): Promise<void> {
+            const target = path.join(namespace, `${key(entry, html)}.json`);
+            const temporary = `${target}.${process.pid}.tmp`;
+            await fs.writeFile(
+                temporary,
+                JSON.stringify({
+                    ...output,
+                    digest: digest(output.html),
+                    assets: referencedAssets.map((asset) => [
+                        asset,
+                        assetDigests.get(asset) ?? null,
+                    ]),
+                }),
+            );
+            await fs.rename(temporary, target);
+        },
+    };
+}

package/src/layouts/PostLayout.astro

@@ -60,7 +60,9 @@ const walineConfig = walineSection?.serverURL
         <PostContent
             title={props.title}
             description={props.description}
-            titleTransitionName={props.postId === undefined ? undefined : getPostTitleTransitionName(props.postId)}
+            titleTransitionName={props.postId === undefined
+                ? undefined
+                : getPostTitleTransitionName(props.postId)}
             date={props.date}
             updated={props.updated}
             readingMinutes={props.readingMinutes}
@@ -71,12 +73,12 @@ const walineConfig = walineSection?.serverURL
             <PostCC title={props.title} author={author} url={Astro.url.href} cc={props.cc} />
             <PostNavigation prev={props.prev} next={props.next} />
             {commentEnabled && walineConfig?.serverURL && (
-    <WalineComment
-        {...buildWalineProps(walineConfig)}
-        path={Astro.url.pathname}
-        title={props.title}
-    />
-)}
+                <WalineComment
+                    {...buildWalineProps(walineConfig)}
+                    path={Astro.url.pathname}
+                    title={props.title}
+                />
+            )}
         </PostContent>
 
         <!-- Right Sidebar -->

package/src/layouts/Stalux.astro

@@ -83,10 +83,10 @@ const routeAnimation = getRouteAnimation(routeKind);
         data-stalux-umami-url={headConfig?.umami?.url}
     >
         {llmPromote && (
-    <section class="stalux-ai-prompt" data-stalux-ai-prompt aria-label="AI site context">
-        <p>{llmPromote}</p>
-    </section>
-)}
+            <section class="stalux-ai-prompt" data-stalux-ai-prompt aria-label="AI site context">
+                <p>{llmPromote}</p>
+            </section>
+        )}
         <div
             class="bg-layer bg-a"
             data-stalux-background="a"

package/src/pages/about.astro

@@ -47,12 +47,12 @@ const author = authorConfig.name;
                 cc="CC-BY-NC-SA-4.0"
             />
             {commentEnabled && walineConfig?.serverURL && (
-    <WalineComment
-        {...buildWalineProps(walineConfig)}
-        path={Astro.url.pathname}
-        title={aboutPage.data.title}
-    />
-)}
+                <WalineComment
+                    {...buildWalineProps(walineConfig)}
+                    path={Astro.url.pathname}
+                    title={aboutPage.data.title}
+                />
+            )}
         </PostContent>
     </div>
 </Stalux>

package/src/pages/categories/[category].astro

@@ -28,10 +28,10 @@ const props = Astro.props as Props;
 <Stalux
     title={`${t("taxonomy.category")}: ${props.category} | ${siteConfig.title}`}
     description={t("taxonomy.browseCategory", {
-    title: siteConfig.title,
-    category: props.category,
-    count: props.count,
-})}
+        title: siteConfig.title,
+        category: props.category,
+        count: props.count,
+    })}
 >
     <div style="height: 3em;"></div>
     <Navs />

package/src/pages/tags/[tag].astro

@@ -28,7 +28,11 @@ const props = Astro.props as Props;
 
 <Stalux
     title={`${t("taxonomy.tag")}: ${props.tag} | ${siteConfig.title}`}
-    description={t("taxonomy.browseTag", { title: siteConfig.title, tag: props.tag, count: props.count })}
+    description={t("taxonomy.browseTag", {
+        title: siteConfig.title,
+        tag: props.tag,
+        count: props.count,
+    })}
     noindex={props.count < 3}
 >
     <div style="height: 3em;"></div>

package/src/plugins/feature-flags.ts

@@ -16,7 +16,7 @@ import type { HastVisitorContext, MdastNode, MdastVisitorContext } from "satteri
  * - 数学公式由 satteri-temml 插件直接输出 MathML，无需额外标记
  */
 import { defineHastPlugin, defineMdastPlugin } from "satteri";
-import { findHtmlImages, updateImageTag } from "../internal/html-images";
+import { findHtmlImages, imageLoadingUpdates, updateImageTag } from "../internal/html-images";
 import { logDetail } from "../utils/diagnostics";
 
 declare module "satteri" {
@@ -247,22 +247,10 @@ export function applyImageLoadingPolicy(
 }
 
 export function applyHtmlImageLoadingPolicy(html: string): string {
-    const firstSeen = new Set<number>();
-    const changes = findHtmlImages(html)
-        .filter((image) => image.body !== undefined)
-        .map((image) => {
-            const body = image.body as number;
-            const first = !firstSeen.has(body);
-            firstSeen.add(body);
-            const updates: Record<string, string> = {
-                decoding: image.attributes.get("decoding") || "async",
-                loading: first ? "eager" : "lazy",
-            };
-            if (first) updates.fetchpriority = "high";
-            else if (image.attributes.get("fetchpriority") === "high")
-                updates.fetchpriority = "auto";
-            return { image, tag: updateImageTag(image, updates) };
-        });
+    const changes = [...imageLoadingUpdates(findHtmlImages(html))].map(([image, updates]) => ({
+        image,
+        tag: updateImageTag(image, updates),
+    }));
     for (const { image, tag } of changes.reverse())
         html = html.slice(0, image.start) + tag + html.slice(image.end);
     return html;