@nu-appdev/northwestern-starlight-theme 1.6.1 → 1.6.3

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.3] - 2026-08-27
+
+### Fixed
+
+- **A CDN blip fetching an OG font no longer fails the whole build.** The fonts for OG images are fetched from the Northwestern CDN at build time, because their licenses do not allow shipping them inside the package. Each font was fetched once, with no timeout, and any failure threw: one refused connection took down a docs build, and with it the deploy behind it.
+
+  Font requests now time out after 10 seconds and retry twice with exponential backoff. Network errors, timeouts, and 5xx responses are retried; a 4xx is a wrong URL rather than a blip, so it is reported immediately. A font that still will not load is logged as a warning and the image renders in whichever font did load, since an OG image in the wrong typeface beats a failed build. Only an empty font list still throws, because satori has nothing to draw text with. Results are cached per URL, failures included, so an outage costs one retry sequence for the build instead of one per page.
+
+## [1.6.2] - 2026-08-20
+
+### Fixed
+
+- OG image text no longer unescapes twice. Entities were decoded in sequence with `&amp;` first, so a title containing the escaped text `&amp;lt;` came out as `<`. Decoding is now a single pass, and escaped text stays escaped.
+- The meta-refresh patterns used to rewrite legacy `.html` redirect pages are bounded. The previous patterns scanned the rest of the page from every start position, so time grew with the square of the page size: a 200 KB page of near-matches took over half a second. A tag longer than the bound is left alone, which skips hash forwarding for that page but keeps the redirect.
+
 ## [1.6.1] - 2026-08-20
 
 ### Fixed
@@ -203,7 +218,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - OpenAPI plugin compatibility with method badge preservation
 - Reduced motion support for transitions
 
-[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.6.1...HEAD
+[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.6.3...HEAD
+[1.6.3]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.6.2...v1.6.3
+[1.6.2]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.6.1...v1.6.2
 [1.6.1]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.6.0...v1.6.1
 [1.6.0]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.5.1...v1.6.0
 [1.5.1]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.5.0...v1.5.1

package/dist/legacy-html-redirects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"legacy-html-redirects.d.ts","sourceRoot":"","sources":["../legacy-html-redirects.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAG9C;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAUD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqB5G;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,8BAA8B,IAAI,gBAAgB,CASjE;AAED,0CAA0C;AAC1C,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7D;AAuCD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWxD"}
+{"version":3,"file":"legacy-html-redirects.d.ts","sourceRoot":"","sources":["../legacy-html-redirects.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAG9C;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAUD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqB5G;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,8BAA8B,IAAI,gBAAgB,CASjE;AAED,0CAA0C;AAC1C,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7D;AA4CD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWxD"}

package/legacy-html-redirects.ts

@@ -142,8 +142,13 @@ function flattenOne(root: string, rel: string): void {
     renameSync(tmpPath, dirPath);
 }
 
-const META_REFRESH_TAG = /<meta\s+http-equiv="refresh"[^>]*>/i;
-const META_REFRESH_URL = /url=([^"]+)"/i;
+// Every quantifier below is bounded. An unbounded one makes matching quadratic
+// on a page full of near-matches, because each failed start position rescans the
+// rest of the document (CodeQL `js/polynomial-redos`). The bounds are far above
+// any tag Astro emits; a page that exceeds them is left alone, which only costs
+// hash forwarding, not the redirect itself.
+const META_REFRESH_TAG = /<meta\s{1,32}http-equiv="refresh"[^>]{0,1024}>/i;
+const META_REFRESH_URL = /url=([^"]{1,2048})"/i;
 const HASH_FORWARD_SCRIPT = /<script>location\.replace\(/;
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nu-appdev/northwestern-starlight-theme",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "description": "A Northwestern-branded theme for Astro Starlight",
   "license": "MIT",
   "author": "Danny Foster <danny@northwestern.edu>",
@@ -90,7 +90,11 @@
     }
   },
   "devDependencies": {
+    "@astrojs/starlight": "^0.41.7",
     "@types/hast": "^3.0.5",
+    "astro": "^7.2.4",
+    "astro-mermaid": "^2.1.0",
+    "mermaid": "^11.17.0",
     "typescript": "^7.0.2"
   },
   "scripts": {

package/src/og/render.ts

@@ -53,55 +53,136 @@ function toFontWeight(weight: string): number {
     return fontWeightMap[weight] ?? 400;
 }
 
-function decodeText(text: string) {
-    return text
-        .replaceAll("&", "&")
-        .replaceAll("&lt;", "<")
-        .replaceAll("&gt;", ">")
-        .replaceAll("&quot;", '"')
-        .replaceAll("&#39;", "'");
+const HTML_ENTITIES: Record<string, string> = {
+    "&amp;": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&#39;": "'",
+};
+
+/**
+ * Decode the HTML entities Starlight escapes into page titles and descriptions.
+ *
+ * One pass, because decoding `&amp;` before the others would unescape twice:
+ * `&amp;lt;` is the text `&lt;`, not `<`.
+ *
+ * @internal — exposed for unit tests.
+ */
+export function decodeText(text: string) {
+    return text.replace(/&(?:amp|lt|gt|quot|#39);/g, (entity) => HTML_ENTITIES[entity] ?? entity);
 }
 
 function rgbToCSS(rgb: RGBColor): string {
     return `rgb(${rgb[0]}, ${rgb[1]}, ${rgb[2]})`;
 }
 
-const fontCache = new Map<string, ArrayBuffer>();
+const FONT_FETCH_ATTEMPTS = 3;
+const FONT_FETCH_TIMEOUT_MS = 10_000;
+const FONT_RETRY_BASE_DELAY_MS = 500;
+
+function errorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Fetch a font and its body, retrying transient failures with exponential backoff.
+ *
+ * The body is read inside the attempt because `fetch()` resolves as soon as the
+ * headers arrive: a connection truncated mid-download, or the timeout firing on a
+ * slow body, has to fail here to be retried at all.
+ *
+ * Network errors, timeouts, and 5xx responses are retried: a CDN blip should not
+ * decide whether a docs build succeeds. A 4xx is a wrong URL, not a blip, so it
+ * is reported on the first attempt.
+ */
+async function fetchFontBuffer(url: string): Promise<ArrayBuffer> {
+    let lastError: unknown;
+    for (let attempt = 1; attempt <= FONT_FETCH_ATTEMPTS; attempt++) {
+        try {
+            const response = await fetch(url, { signal: AbortSignal.timeout(FONT_FETCH_TIMEOUT_MS) });
+            if (response.ok) return await response.arrayBuffer();
+            const statusText = response.statusText ? ` ${response.statusText}` : "";
+            lastError = new Error(`HTTP ${response.status}${statusText}`);
+            if (response.status < 500) break;
+        } catch (error) {
+            lastError = error;
+        }
+        if (attempt < FONT_FETCH_ATTEMPTS) {
+            await new Promise((resolve) => setTimeout(resolve, FONT_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1)));
+        }
+    }
+    throw new Error(`[northwestern-starlight-theme] Failed to fetch OG font from ${url}: ${errorMessage(lastError)}`, {
+        cause: lastError,
+    });
+}
+
+async function readFontFile(path: string): Promise<ArrayBuffer> {
+    const file = await fs.readFile(path);
+    return file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength);
+}
+
+/**
+ * Cached per URL, failures included. A static build renders one OG image per
+ * page, so a font the CDN is down for would otherwise be re-fetched — and
+ * re-retried — once per page. The retries above already cover a blip.
+ */
+const fontCache = new Map<string, Promise<ArrayBuffer>>();
 
 /**
  * Load a font from disk or a remote URL for OG image rendering.
  *
  * @internal
  */
-export async function loadFont(url: string): Promise<ArrayBuffer> {
+export function loadFont(url: string): Promise<ArrayBuffer> {
     const cached = fontCache.get(url);
     if (cached) return cached;
-    let buffer: ArrayBuffer;
-    if (/^https?:\/\//.test(url)) {
-        let response: Response;
-        try {
-            response = await fetch(url);
-        } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`[northwestern-starlight-theme] Failed to fetch OG font from ${url}: ${message}`, {
-                cause: error,
-            });
-        }
+    const pending = /^https?:\/\//.test(url) ? fetchFontBuffer(url) : readFontFile(url);
+    fontCache.set(url, pending);
+    return pending;
+}
 
-        if (!response.ok) {
-            const statusText = response.statusText ? ` ${response.statusText}` : "";
-            throw new Error(
-                `[northwestern-starlight-theme] Failed to fetch OG font from ${url}: HTTP ${response.status}${statusText}`,
+function fontFamilyName(url: string): string {
+    return url.includes("Poppins") ? "Poppins" : url.includes("Akkurat") ? "Akkurat Pro" : "Noto Sans";
+}
+
+const warnedFontUrls = new Set<string>();
+
+/**
+ * Load the fonts satori renders with, dropping any that failed.
+ *
+ * OG images are a nice-to-have; a font the CDN would not serve degrades the
+ * image (satori falls back to a font that did load) instead of failing the
+ * consumer's build. Satori needs at least one font, so an empty list still
+ * throws.
+ *
+ * @internal — exposed for unit tests.
+ */
+export async function loadSatoriFonts(fontUrls: string[]) {
+    const settled = await Promise.allSettled(fontUrls.map((url) => loadFont(url)));
+
+    const fonts = settled.flatMap((result, index) => {
+        const url = fontUrls[index];
+        if (result.status === "fulfilled") {
+            return [{ name: fontFamilyName(url), data: result.value, weight: 400 as const }];
+        }
+        if (!warnedFontUrls.has(url)) {
+            warnedFontUrls.add(url);
+            console.warn(
+                `[northwestern-starlight-theme] OG font unavailable, rendering without it: ${errorMessage(result.reason)}`,
             );
         }
+        return [];
+    });
 
-        buffer = await response.arrayBuffer();
-    } else {
-        const file = await fs.readFile(url);
-        buffer = file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength);
+    if (fonts.length === 0) {
+        throw new Error(
+            "[northwestern-starlight-theme] No OG fonts could be loaded, so OG images cannot be rendered. " +
+                "Check network access to the configured font URLs.",
+        );
     }
-    fontCache.set(url, buffer);
-    return buffer;
+
+    return fonts;
 }
 
 const logoCache = new Map<string, string>();
@@ -150,11 +231,7 @@ export async function renderOGImage({
         color: fontConfig.description?.color ?? ([255, 255, 255] as RGBColor),
     };
 
-    const fontData = await Promise.all(fontUrls.map(loadFont));
-    const satoriFont = fontUrls.map((url, i) => {
-        const name = url.includes("Poppins") ? "Poppins" : url.includes("Akkurat") ? "Akkurat Pro" : "Noto Sans";
-        return { name, data: fontData[i], weight: 400 as const };
-    });
+    const satoriFont = await loadSatoriFonts(fontUrls);
 
     const logoDataURL = logo ? await loadLogoDataURL(logo.path) : undefined;
     const logoW = logo?.size?.[0] ?? 60;