@xingwangzhe/stalux 1.35.11 → 1.35.13

package/src/internal/font-slices.ts

@@ -20,7 +20,13 @@ import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { FontSubsetter } from "@xingwangzhe/cjk-font-split-native";
 import type { AstroIntegrationLogger } from "astro";
-import { type DefaultTreeAdapterMap, parse } from "parse5";
+import {
+    type DefaultTreeAdapterMap,
+    defaultTreeAdapter,
+    html as htmlNamespaces,
+    parse,
+    serialize,
+} from "parse5";
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -209,22 +215,31 @@ function findBody(node: HtmlNode): HtmlNode | undefined {
 }
 
 function isHiddenElement(attrs: Array<{ name: string; value: string }>): boolean {
-    const attributes = new Map(attrs.map(({ name, value }) => [name, value]));
-    if (attributes.has("hidden") || attributes.has("inert")) return true;
-
-    const classes = (attributes.get("class") ?? "").split(/\s+/u);
+    let className = "";
+    let style = "";
+    for (const attr of attrs) {
+        if (attr.name === "hidden" || attr.name === "inert") return true;
+        if (attr.name === "class") className = attr.value;
+        if (attr.name === "style") style = attr.value;
+    }
+    const classes = className.split(/\s+/u);
     if (classes.some((name) => VISUALLY_HIDDEN_CLASSES.has(name))) return true;
 
-    const style = attributes.get("style") ?? "";
     return /(?:^|;)\s*(?:display\s*:\s*none|visibility\s*:\s*hidden|content-visibility\s*:\s*hidden)\s*(?:;|$)/iu.test(
         style,
     );
 }
 
 /** Collect renderable body text nodes, including content inside collapsed controls. */
-function collectBodyText(node: HtmlNode, output: string[]): void {
+const CONTROL_CHARACTER = /\p{C}/u;
+function addGlyphs(text: string, output: Set<string>): void {
+    for (const char of text)
+        if (!output.has(char) && !CONTROL_CHARACTER.test(char)) output.add(char);
+}
+
+function collectBodyText(node: HtmlNode, output: Set<string>): void {
     if (node.nodeName === "#text" && "value" in node) {
-        output.push(node.value);
+        addGlyphs(node.value, output);
         return;
     }
 
@@ -240,9 +255,10 @@ function collectBodyText(node: HtmlNode, output: string[]): void {
 }
 
 function formatUnicodeRange(chars: string[]): string {
-    const points = chars.map((char) => char.codePointAt(0) as number).sort((a, b) => a - b);
     const ranges: Array<[number, number]> = [];
-    for (const point of points) {
+    // preparePageFont already sorts the unique glyphs by code point.
+    for (const char of chars) {
+        const point = char.codePointAt(0) as number;
         const last = ranges.at(-1);
         if (last && point === last[1] + 1) last[1] = point;
         else ranges.push([point, point]);
@@ -263,14 +279,15 @@ export function writePageFontSubset(
     extraChars = "",
     document = parse(html),
 ): PageFontSubset | undefined {
-    const input = preparePageFont(html, fontBuffer, linkedStylesheetText, extraChars, document);
+    const input = preparePageFont(fontBuffer, linkedStylesheetText, extraChars, document);
     if (!input) return undefined;
-    return renderPageFont(
-        html,
+    const result = renderPageFont(
+        document,
         publicUrlPrefix,
         input.chars,
         input.prepared.subset(input.chars.join(""), cacheDir),
     );
+    return { ...result, html: serialize(document) };
 }
 
 export async function writePageFontSubsetAsync(
@@ -282,14 +299,16 @@ export async function writePageFontSubsetAsync(
     extraChars = "",
     document = parse(html),
 ): Promise<PageFontSubset | undefined> {
-    const input = preparePageFont(html, fontBuffer, linkedStylesheetText, extraChars, document);
+    const input = preparePageFont(fontBuffer, linkedStylesheetText, extraChars, document);
     if (!input) return undefined;
     const result = await input.prepared.subsetAsync(input.chars.join(""), cacheDir);
-    return renderPageFont(html, publicUrlPrefix, input.chars, result);
+    return {
+        ...renderPageFont(document, publicUrlPrefix, input.chars, result),
+        html: serialize(document),
+    };
 }
 
 function preparePageFont(
-    html: string,
     fontBuffer: Buffer,
     linkedStylesheetText: string,
     extraChars: string,
@@ -298,15 +317,14 @@ function preparePageFont(
     const body = findBody(document);
     if (!body) return undefined;
 
-    const bodyText: string[] = [
-        ...[...html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)].map(([, css]) =>
-            cssGeneratedText(css ?? ""),
-        ),
-        linkedStylesheetText,
-    ];
-    collectBodyText(body, bodyText);
-    const glyphSource = `${RESERVED_GLYPHS}${extraChars}${bodyText.join("")}`;
-    const chars = [...new Set([...glyphSource].filter((char) => !/\p{C}/u.test(char)))].sort(
+    const glyphs = new Set<string>();
+    addGlyphs(RESERVED_GLYPHS, glyphs);
+    addGlyphs(extraChars, glyphs);
+    addGlyphs(linkedStylesheetText, glyphs);
+    for (const style of collectInlineStyles(document))
+        addGlyphs(cssGeneratedText(styleText(style)), glyphs);
+    collectBodyText(body, glyphs);
+    const chars = [...glyphs].sort(
         (a, b) => (a.codePointAt(0) as number) - (b.codePointAt(0) as number),
     );
     if (chars.length === 0) return undefined;
@@ -320,44 +338,129 @@ function preparePageFont(
 }
 
 function renderPageFont(
-    html: string,
+    document: DefaultTreeAdapterMap["document"],
     publicUrlPrefix: string,
     chars: string[],
     result: { hash: string; path: string; cacheHit: boolean },
-): PageFontSubset {
+): Omit<PageFontSubset, "html"> {
     const filename = `page-${result.hash}.woff2`;
 
     const rel = `${publicUrlPrefix}${filename}`;
     // Keep Astro's broad unicode-range font out of the fallback stack; otherwise
     // a character outside this page's subset would download multiple 300 KB slices.
-    const originalFontStack = html.match(/--font-body:\s*([^;}]+)/u)?.[1]?.trim();
+    const styles = collectInlineStyles(document);
+    const originalFontStack = styles
+        .map(styleText)
+        .map((css) => css.match(/--font-body:\s*([^;}]+)/u)?.[1]?.trim())
+        .find(Boolean);
     const fallbackStack =
         originalFontStack || '"Noto Sans SC","Noto Sans CJK SC",system-ui,sans-serif';
-    const originalCodeStack = html.match(/--font-code:\s*([^;}]+)/u)?.[1]?.trim();
+    const originalCodeStack = styles
+        .map(styleText)
+        .map((css) => css.match(/--font-code:\s*([^;}]+)/u)?.[1]?.trim())
+        .find(Boolean);
     const codeStack = originalCodeStack
         ? `${originalCodeStack},"LXGW WenKai-Page Subset"`
         : `"LXGW WenKai-Page Subset",${fallbackStack}`;
     // The source font is regular; advertise a weight range so browsers synthesize
     // bold weights from these same glyphs instead of falling back to system CJK.
     const css = `@font-face{font-family:"LXGW WenKai-Page Subset";src:url("${rel}") format("woff2");font-style:normal;font-weight:100 900;font-display:swap;unicode-range:${formatUnicodeRange(chars)}}:root{--font-body:"LXGW WenKai-Page Subset",${fallbackStack};--font-code:${codeStack}}body{font-family:var(--font-body),${fallbackStack}}`;
-    const withoutBroadBodyFonts = html.replace(
-        /@font-face\{[^}]*font-family:"LXGW WenKai-[^"]+"[^}]*\}/g,
-        (face) => {
-            const unicodeRange = face.match(/unicode-range:([^;}]+)/i)?.[1] ?? "";
-            const hasCjkRange = unicodeRange.split(",").some((range) => {
-                const start = range.match(/U\+([\da-f]+)/i)?.[1];
-                if (!start) return false;
-                const codePoint = Number.parseInt(start, 16);
-                return codePoint >= 0x4e00 && codePoint <= 0x9fff;
-            });
-            return hasCjkRange ? "" : face;
-        },
-    );
-    const outputHtml = withoutBroadBodyFonts.replace(
-        /<\/head\s*>/i,
-        `<style data-stalux-page-font>${css}</style></head>`,
-    );
-    return { html: outputHtml, filename, sourcePath: result.path, cacheHit: result.cacheHit };
+    for (const style of styles) {
+        for (const node of style.childNodes) {
+            if (node.nodeName !== "#text" || !("value" in node)) continue;
+            node.value = node.value.replace(
+                /@font-face\{[^}]*font-family:"LXGW WenKai-[^"]+"[^}]*\}/g,
+                (face) => {
+                    const unicodeRange = face.match(/unicode-range:([^;}]+)/i)?.[1] ?? "";
+                    const hasCjkRange = unicodeRange.split(",").some((range) => {
+                        const start = range.match(/U\+([\da-f]+)/i)?.[1];
+                        if (!start) return false;
+                        const point = Number.parseInt(start, 16);
+                        return point >= 0x4e00 && point <= 0x9fff;
+                    });
+                    return hasCjkRange ? "" : face;
+                },
+            );
+        }
+    }
+    const head = document.childNodes
+        .flatMap((node) => ("childNodes" in node ? node.childNodes : []))
+        .find((node) => "tagName" in node && node.tagName === "head");
+    if (head && "childNodes" in head) {
+        const style = defaultTreeAdapter.createElement("style", htmlNamespaces.NS.HTML, [
+            { name: "data-stalux-page-font", value: "" },
+        ]);
+        const preload = defaultTreeAdapter.createElement("link", htmlNamespaces.NS.HTML, [
+            { name: "rel", value: "preload" },
+            { name: "as", value: "font" },
+            { name: "type", value: "font/woff2" },
+            { name: "crossorigin", value: "anonymous" },
+            { name: "href", value: rel },
+            { name: "data-stalux-page-font-preload", value: "" },
+        ]);
+        defaultTreeAdapter.appendChild(head, preload);
+        defaultTreeAdapter.insertText(style, css);
+        defaultTreeAdapter.appendChild(head, style);
+    }
+    return { filename, sourcePath: result.path, cacheHit: result.cacheHit };
+}
+
+/** Styles are selected structurally, so examples in scripts/comments/templates are untouched. */
+function collectInlineStyles(document: HtmlNode): DefaultTreeAdapterMap["element"][] {
+    const styles: DefaultTreeAdapterMap["element"][] = [];
+    function visit(node: HtmlNode) {
+        if ("tagName" in node) {
+            if (node.tagName === "template") return;
+            if (node.tagName === "style") styles.push(node);
+        }
+        if ("childNodes" in node) for (const child of node.childNodes) visit(child);
+    }
+    visit(document);
+    return styles;
+}
+
+function styleText(style: DefaultTreeAdapterMap["element"]): string {
+    return style.childNodes.map((node) => ("value" in node ? node.value : "")).join("");
+}
+
+/** Remove previously generated styles by AST identity, never by matching HTML strings. */
+export function removePageFontStyles(document: DefaultTreeAdapterMap["document"]): void {
+    function removePreloads(node: HtmlNode): void {
+        if ("tagName" in node && node.tagName === "template") return;
+        if (
+            "tagName" in node &&
+            node.tagName === "link" &&
+            node.attrs.some((attr) => attr.name === "data-stalux-page-font-preload")
+        ) {
+            defaultTreeAdapter.detachNode(node);
+            return;
+        }
+        if ("childNodes" in node) for (const child of [...node.childNodes]) removePreloads(child);
+    }
+    removePreloads(document);
+    for (const style of collectInlineStyles(document)) {
+        if (style.attrs.some((attribute) => attribute.name === "data-stalux-page-font"))
+            defaultTreeAdapter.detachNode(style);
+    }
+}
+
+/** Subset and inject into the caller's AST without serializing an intermediate page. */
+export async function writePageFontSubsetIntoDocumentAsync(
+    document: DefaultTreeAdapterMap["document"],
+    fontBuffer: Buffer,
+    cacheDir: string,
+    publicUrlPrefix = "/_astro/fonts/",
+    linkedStylesheetText = "",
+): Promise<Omit<PageFontSubset, "html"> | undefined> {
+    const input = preparePageFont(fontBuffer, linkedStylesheetText, "", document);
+    if (!input) return undefined;
+    const result = await input.prepared.subsetAsync(input.chars.join(""), cacheDir);
+    const rendered = renderPageFont(document, publicUrlPrefix, input.chars, result);
+    return {
+        filename: rendered.filename,
+        sourcePath: rendered.sourcePath,
+        cacheHit: rendered.cacheHit,
+    };
 }
 
 /** Remove stale page subsets so deploy artifacts only contain the current build's referenced files. */

package/src/internal/html-images.ts

@@ -1,6 +1,7 @@
 import { type DefaultTreeAdapterMap, parse } from "parse5";
 
 export interface HtmlImage {
+    node: DefaultTreeAdapterMap["element"];
     start: number;
     end: number;
     tag: string;
@@ -27,6 +28,7 @@ export function findHtmlImages(
             if (node.tagName === "img" && location?.startTag) {
                 const { startOffset: start, endOffset: end } = location.startTag;
                 images.push({
+                    node,
                     start,
                     end,
                     tag: html.slice(start, end),

package/src/internal/html-output.ts

@@ -0,0 +1,98 @@
+import { type DefaultTreeAdapterMap, serialize, serializeOuter } from "parse5";
+
+type Element = DefaultTreeAdapterMap["element"];
+
+/**
+ * Serialize AST mutations to image/style nodes without reserializing untouched page subtrees.
+ * Source locations belong to the original parse; edits are emitted together after all mutations.
+ */
+export function createHtmlMutationEmitter(
+    source: string,
+    document: DefaultTreeAdapterMap["document"],
+) {
+    const snapshots: Array<{
+        node: Element;
+        start: number;
+        end: number;
+        attrs: Element["attrs"];
+        text: string[];
+    }> = [];
+    let head: Element | undefined;
+    function visit(node: DefaultTreeAdapterMap["node"]) {
+        if ("tagName" in node) {
+            if (node.tagName === "template") return;
+            if (node.tagName === "head") head = node;
+            const location = node.sourceCodeLocation;
+            if (
+                (node.tagName === "img" || node.tagName === "style" || node.tagName === "link") &&
+                location
+            ) {
+                snapshots.push({
+                    node,
+                    start: location.startOffset,
+                    end: location.endOffset,
+                    attrs: node.attrs.map((attribute) => ({ ...attribute })),
+                    text: node.childNodes.map((child) => ("value" in child ? child.value : "")),
+                });
+            }
+        }
+        if ("childNodes" in node) for (const child of node.childNodes) visit(child);
+    }
+    visit(document);
+
+    return () => {
+        const edits: Array<{ start: number; end: number; value: string }> = [];
+        for (const snapshot of snapshots) {
+            const { node, start, end, attrs, text } = snapshot;
+            if (!node.parentNode) {
+                edits.push({ start, end, value: "" });
+                continue;
+            }
+            const changed =
+                node.attrs.length !== attrs.length ||
+                attrs.some((attribute, index) => {
+                    const current = node.attrs[index];
+                    return (
+                        !current ||
+                        attribute.name !== current.name ||
+                        attribute.value !== current.value ||
+                        attribute.namespace !== current.namespace ||
+                        attribute.prefix !== current.prefix
+                    );
+                }) ||
+                node.childNodes.length !== text.length ||
+                text.some((value, index) => {
+                    const child = node.childNodes[index];
+                    return !child || ("value" in child ? child.value : "") !== value;
+                });
+            if (changed) edits.push({ start, end, value: serializeOuter(node) });
+        }
+        const inserted = head?.childNodes.filter(
+            (node) =>
+                "tagName" in node &&
+                (node.tagName === "style" || node.tagName === "link") &&
+                !node.sourceCodeLocation,
+        );
+        if (inserted?.length) {
+            const position = head?.sourceCodeLocation?.endTag?.startOffset;
+            // Documents with an implicit head have no insertion range; use the standard serializer.
+            if (position === undefined) return serialize(document);
+            edits.push({
+                start: position,
+                end: position,
+                value: inserted.map((node) => serializeOuter(node)).join(""),
+            });
+        }
+        if (!edits.length) return source;
+        edits.sort((left, right) => left.start - right.start || left.end - right.end);
+        const parts: string[] = [];
+        let offset = 0;
+        for (const edit of edits) {
+            if (edit.start < offset) return serialize(document);
+            parts.push(source.slice(offset, edit.start), edit.value);
+            offset = edit.end;
+        }
+        parts.push(source.slice(offset));
+        return parts.join("");
+    };
+}

package/src/internal/image-dimensions.ts

@@ -1,93 +1,91 @@
-import { readFile } from "node:fs/promises";
+import { open } from "node:fs/promises";
 import path from "node:path";
+import { imageSize } from "image-size";
+import { imageSizeFromFile } from "image-size/fromFile";
 import { findHtmlImages, type HtmlImage, imageLoadingUpdates, updateImageTag } from "./html-images";
 
 export type ImageDimensions = { width: number; height: number };
 
-/** Read intrinsic dimensions for common public image formats without loading an image library. */
-export function readImageDimensions(data: Buffer): ImageDimensions | undefined {
-    if (data.length >= 24 && data.toString("hex", 0, 8) === "89504e470d0a1a0a") {
-        return { width: data.readUInt32BE(16), height: data.readUInt32BE(20) };
+/** Preserve JPEG layouts the library cannot recognize, including a leading SOF marker. */
+function readJpegDimensions(data: Buffer): ImageDimensions | undefined {
+    if (data.length < 4 || data[0] !== 0xff || data[1] !== 0xd8) return undefined;
+    let offset = 2;
+    while (offset + 4 <= data.length) {
+        if (data[offset] !== 0xff) return undefined;
+        const marker = data[offset + 1] ?? 0;
+        const size = data.readUInt16BE(offset + 2);
+        if (size < 2 || offset + 2 + size > data.length) return undefined;
+        if (
+            [0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf].includes(
+                marker,
+            )
+        ) {
+            if (size < 7) return undefined;
+            return validDimensions({
+                width: data.readUInt16BE(offset + 7),
+                height: data.readUInt16BE(offset + 5),
+            });
+        }
+        offset += size + 2;
     }
+    return undefined;
+}
 
-    if (
-        data.length >= 10 &&
-        (data.toString("ascii", 0, 6) === "GIF87a" || data.toString("ascii", 0, 6) === "GIF89a")
-    ) {
-        return { width: data.readUInt16LE(6), height: data.readUInt16LE(8) };
-    }
+function validDimensions(size: ImageDimensions): ImageDimensions | undefined {
+    return Number.isFinite(size.width) &&
+        Number.isFinite(size.height) &&
+        size.width > 0 &&
+        size.height > 0
+        ? { width: size.width, height: size.height }
+        : undefined;
+}
 
-    if (
-        data.length >= 30 &&
-        data.toString("ascii", 0, 4) === "RIFF" &&
-        data.toString("ascii", 8, 12) === "WEBP"
-    ) {
-        const chunk = data.toString("ascii", 12, 16);
-        if (chunk === "VP8X") {
-            return {
-                width: 1 + data.readUIntLE(24, 3),
-                height: 1 + data.readUIntLE(27, 3),
-            };
-        }
-        if (chunk === "VP8 " && data[23] === 0x9d && data[24] === 0x01 && data[25] === 0x2a) {
-            return {
-                width: data.readUInt16LE(26) & 0x3fff,
-                height: data.readUInt16LE(28) & 0x3fff,
-            };
-        }
-        if (chunk === "VP8L" && data[20] === 0x2f) {
-            const b1 = data[21] ?? 0;
-            const b2 = data[22] ?? 0;
-            const b3 = data[23] ?? 0;
-            const b4 = data[24] ?? 0;
-            return {
-                width: 1 + b1 + ((b2 & 0x3f) << 8),
-                height: 1 + (b2 >> 6) + (b3 << 2) + ((b4 & 0x0f) << 10),
-            };
-        }
+/** Unsupported or malformed images leave the original HTML untouched. */
+export function readImageDimensions(data: Buffer): ImageDimensions | undefined {
+    try {
+        return validDimensions(imageSize(data));
+    } catch {
+        return readJpegDimensions(data);
     }
+}
 
-    if (data.length >= 4 && data[0] === 0xff && data[1] === 0xd8) {
-        let offset = 2;
-        while (offset + 4 <= data.length) {
-            if (data[offset] !== 0xff) break;
-            const marker = data[offset + 1] ?? 0;
-            const size = data.readUInt16BE(offset + 2);
-            if (size < 7 || offset + 2 + size > data.length) break;
-            if (
-                [
-                    0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
-                ].includes(marker)
-            ) {
-                return {
-                    width: data.readUInt16BE(offset + 7),
-                    height: data.readUInt16BE(offset + 5),
-                };
-            }
-            offset += size + 2;
+async function readLocalImageDimensions(filename: string): Promise<ImageDimensions | undefined> {
+    try {
+        // image-size reads at most 512 KiB; the caller retains the four-page work queue.
+        return validDimensions(await imageSizeFromFile(filename));
+    } catch {
+        // Preserve previously supported JPEGs whose SOF is first or beyond the header window.
+        // Only this compatibility path reads a whole image, never an unknown or remote format.
+        const file = await open(filename, "r").catch(() => undefined);
+        if (!file) return undefined;
+        try {
+            const signature = Buffer.alloc(2);
+            await file.read(signature, 0, 2, 0);
+            if (signature[0] !== 0xff || signature[1] !== 0xd8) return undefined;
+            return readImageDimensions(await file.readFile());
+        } catch {
+            return undefined;
+        } finally {
+            await file.close();
         }
     }
-
-    return undefined;
 }
 
 /** Add width/height to same-origin emitted images so their space is reserved before download. */
-export async function addLocalImageDimensions(
-    html: string,
+async function resolveImageUpdates(
+    images: HtmlImage[],
     outputDir: string,
     options: {
-        images?: HtmlImage[];
         cache?: Map<string, Promise<ImageDimensions | undefined>>;
         loadingPolicy?: boolean;
         dependencies?: Set<string>;
     } = {},
-): Promise<string> {
+): Promise<Map<HtmlImage, Record<string, string>>> {
     const dimensionsCache =
         options.cache ?? new Map<string, Promise<ImageDimensions | undefined>>();
     const root = path.resolve(outputDir);
-    const images = options.images ?? findHtmlImages(html);
     const loading = options.loadingPolicy ? imageLoadingUpdates(images) : new Map();
-    const replacements: Array<{ start: number; end: number; tag: string }> = [];
+    const changes = new Map<HtmlImage, Record<string, string>>();
     for (const image of images) {
         const updates: Record<string, string> = { ...loading.get(image) };
         const src = image.attributes.get("src");
@@ -107,9 +105,7 @@ export async function addLocalImageDimensions(
                 options.dependencies?.add(filePath);
                 let dimensions = dimensionsCache.get(filePath);
                 if (!dimensions) {
-                    dimensions = readFile(filePath)
-                        .then(readImageDimensions)
-                        .catch(() => undefined);
+                    dimensions = readLocalImageDimensions(filePath).catch(() => undefined);
                     dimensionsCache.set(filePath, dimensions);
                 }
                 const size = await dimensions;
@@ -119,14 +115,43 @@ export async function addLocalImageDimensions(
                 }
             }
         }
-        if (Object.keys(updates).length) {
-            replacements.push({
-                start: image.start,
-                end: image.end,
-                tag: updateImageTag(image, updates),
-            });
+        if (Object.keys(updates).length) changes.set(image, updates);
+    }
+    return changes;
+}
+
+/** Mutate image attributes in the shared build AST; the caller serializes once. */
+export async function updateLocalImageDimensions(
+    images: HtmlImage[],
+    outputDir: string,
+    options: Parameters<typeof resolveImageUpdates>[2] = {},
+): Promise<void> {
+    const changes = await resolveImageUpdates(images, outputDir, options);
+    for (const [image, updates] of changes) {
+        for (const [name, value] of Object.entries(updates)) {
+            const attribute = image.node.attrs.find((attribute) => attribute.name === name);
+            if (attribute) attribute.value = value;
+            else image.node.attrs.push({ name, value });
         }
     }
+}
+
+/** Compatibility string API; the production pipeline uses AST mutations above. */
+export async function addLocalImageDimensions(
+    html: string,
+    outputDir: string,
+    options: Parameters<typeof resolveImageUpdates>[2] & { images?: HtmlImage[] } = {},
+): Promise<string> {
+    const changes = await resolveImageUpdates(
+        options.images ?? findHtmlImages(html),
+        outputDir,
+        options,
+    );
+    const replacements = [...changes].map(([image, updates]) => ({
+        start: image.start,
+        end: image.end,
+        tag: updateImageTag(image, updates),
+    }));
     if (!replacements.length) return html;
     const parts: string[] = [];
     let offset = 0;