@jxsuite/compiler 0.19.0 → 0.20.0

package/src/site/content-loader.js

@@ -20,10 +20,10 @@ import { globSync } from "glob";
  * with commas and newlines.
  *
  * @param {string} csv - Raw CSV text
- * @returns {Record<string, any>[]} Array of row objects
+ * @returns {Record<string, string>[]} Array of row objects
  */
 function parseCSV(csv) {
-  /** @type {Record<string, any>[]} */
+  /** @type {Record<string, string>[]} */
   const rows = [];
   let current = "";
   let inQuotes = false;
@@ -82,7 +82,7 @@ function parseCSV(csv) {
   const headers = parseRow(lines[0]);
   for (let i = 1; i < lines.length; i++) {
     const fields = parseRow(lines[i]);
-    /** @type {Record<string, any>} */
+    /** @type {Record<string, string>} */
     const obj = {};
     for (let j = 0; j < headers.length; j++) {
       obj[headers[j].trim()] = fields[j]?.trim() ?? "";
@@ -94,35 +94,35 @@ function parseCSV(csv) {
 
 // ─── Markdown loader ──────────────────────────────────────────────────────────
 
-/** @type {any} */
+/**
+ * @type {{
+ *   MarkdownFile: new (opts: Record<string, unknown>) => { resolve(): MarkdownFileResult };
+ * } | null}
+ */
 let _mdModule = null;
 
 /**
  * Lazily import @jxsuite/parser for Markdown support. This avoids hard dependency — only loads when
  * MD content types exist.
  *
- * @returns {Promise<any>}
+ * @returns {Promise<{
+ *   MarkdownFile: new (opts: Record<string, unknown>) => { resolve(): MarkdownFileResult };
+ * }>}
  */
 async function getMarkdownModule() {
   if (!_mdModule) {
-    _mdModule = await import("@jxsuite/parser");
+    _mdModule = /** @type {any} */ (await import("@jxsuite/parser"));
   }
-  return _mdModule;
+  return /** @type {NonNullable<typeof _mdModule>} */ (_mdModule);
 }
 
-/**
- * Load a single markdown file into a ContentEntry.
- *
- * @param {string} filePath - Absolute path to .md file
- * @returns {Promise<object>} ContentEntry shape
- */
 /**
  * Load a markdown file into a ContentEntry. If directiveOptions are provided, they control which
  * custom element directives are available in the markdown.
  *
  * @param {string} filePath - Absolute path to .md file
- * @param {any} [directiveOptions] - Options for the MarkdownDirective plugin
- * @returns {Promise<object>} ContentEntry shape
+ * @param {unknown} [directiveOptions] - Options for the MarkdownDirective plugin
+ * @returns {Promise<ContentLoaderEntry>} ContentEntry shape
  */
 async function loadMarkdownEntry(filePath, directiveOptions) {
   const { MarkdownFile } = await getMarkdownModule();
@@ -147,22 +147,24 @@ async function loadMarkdownEntry(filePath, directiveOptions) {
  * an object with an `id` field, it's a single entry.
  *
  * @param {string} filePath - Absolute path to .json file
- * @returns {object[]} Array of ContentEntry shapes
+ * @returns {ContentLoaderEntry[]} Array of ContentEntry shapes
  */
 function loadJSONEntries(filePath) {
   const raw = JSON.parse(readFileSync(filePath, "utf-8"));
   if (Array.isArray(raw)) {
-    return raw.map((/** @type {any} */ item, /** @type {number} */ i) => ({
-      id: item.id ?? basename(filePath, ".json") + "-" + i,
+    return raw.map((/** @type {Record<string, unknown>} */ item, /** @type {number} */ i) => ({
+      id: /** @type {string} */ (item.id) ?? basename(filePath, ".json") + "-" + i,
       data: item,
       body: null,
     }));
   }
   // Single object file — filename is the id
+  /** @type {Record<string, unknown>} */
+  const rawObj = raw;
   return [
     {
-      id: raw.id ?? basename(filePath, ".json"),
-      data: raw,
+      id: /** @type {string} */ (rawObj.id) ?? basename(filePath, ".json"),
+      data: rawObj,
       body: null,
     },
   ];
@@ -172,26 +174,29 @@ function loadJSONEntries(filePath) {
  * Load a CSV file into ContentEntry(s).
  *
  * @param {string} filePath - Absolute path to .csv file
- * @param {any} [schema] - Content type schema (for type coercion)
- * @returns {object[]} Array of ContentEntry shapes
+ * @param {ContentTypeSchema} [schema] - Content type schema (for type coercion)
+ * @returns {ContentLoaderEntry[]} Array of ContentEntry shapes
  */
 function loadCSVEntries(filePath, schema) {
   const csv = readFileSync(filePath, "utf-8");
   const rows = parseCSV(csv);
-  return rows.map((/** @type {Record<string, any>} */ row, /** @type {number} */ i) => {
+  return rows.map((/** @type {Record<string, string>} */ row, /** @type {number} */ i) => {
     // Apply type coercion based on schema if available
+    /** @type {Record<string, unknown>} */
+    const data = { ...row };
     if (schema?.properties) {
       for (const [key, def] of Object.entries(schema.properties)) {
-        const d = /** @type {any} */ (def);
-        if (key in row) {
-          if (d.type === "number") row[key] = Number(row[key]);
-          else if (d.type === "boolean") row[key] = row[key] === "true";
+        if (key in data) {
+          if (def.type === "number") data[key] = Number(data[key]);
+          else if (def.type === "boolean") data[key] = data[key] === "true";
         }
       }
     }
     // Use `id` column, `sku` column, or row index as the entry ID
-    const id = row.id ?? row.sku ?? String(i);
-    return { id, data: row, body: null };
+    const id = /** @type {string | undefined} */ (data.id) ??
+    /** @type {string | undefined} */ (data.sku) ??
+    String(i);
+    return { id, data, body: null };
   });
 }
 
@@ -201,14 +206,16 @@ function loadCSVEntries(filePath, schema) {
  * Load and parse content types config from project.json.
  *
  * @param {string} projectRoot - Project root directory
- * @param {Record<string, any>} [projectConfig] - Already-loaded project config with `contentTypes`
- *   key
- * @returns {{ config: any; contentDir: string } | null} Parsed config or null if no content dir
+ * @param {ProjectConfig} [projectConfig] - Already-loaded project config with `contentTypes` key
+ * @returns {{
+ *   config: { contentTypes: Record<string, ContentTypeDef> };
+ *   contentDir: string;
+ * } | null}
+ *   Parsed config or null if no content dir
  */
 export function loadContentConfig(projectRoot, projectConfig = undefined) {
   const contentDir = resolve(projectRoot, "content");
 
-  /** @type {any} */
   const config = { contentTypes: projectConfig?.contentTypes ?? {} };
 
   return { config, contentDir };
@@ -220,19 +227,20 @@ export function loadContentConfig(projectRoot, projectConfig = undefined) {
  * Load all content types defined in project.json.
  *
  * @param {string} projectRoot - Project root directory
- * @param {Record<string, any>} [projectConfig] - Already-loaded project config
- * @returns {Promise<Map<string, any[]>>} Map of content type name → array of ContentEntry
+ * @param {ProjectConfig} [projectConfig] - Already-loaded project config
+ * @returns {Promise<Map<string, ContentLoaderEntry[]>>} Map of content type name → array of
+ *   ContentEntry
  */
 export async function loadContentTypes(projectRoot, projectConfig = undefined) {
   const result = loadContentConfig(projectRoot, projectConfig);
   if (!result) return new Map();
 
   const { config } = result;
-  /** @type {Map<string, any[]>} */
+  /** @type {Map<string, ContentLoaderEntry[]>} */
   const contentTypes = new Map();
 
   for (const [name, contentTypeDef] of Object.entries(config.contentTypes)) {
-    const entries = await loadContentType(name, /** @type {any} */ (contentTypeDef), projectRoot);
+    const entries = await loadContentType(name, contentTypeDef, projectRoot);
     contentTypes.set(name, entries);
   }
 
@@ -244,8 +252,8 @@ export async function loadContentTypes(projectRoot, projectConfig = undefined) {
  *
  * @param {string} projectRoot - Project root directory
  * @param {string} contentTypeName - Name of the content type
- * @param {Record<string, any>} [projectConfig] - Already-loaded project config
- * @returns {any[] | undefined}
+ * @param {ProjectConfig} [projectConfig] - Already-loaded project config
+ * @returns {(string | JxElement)[] | undefined}
  */
 export function getContentTypeElements(projectRoot, contentTypeName, projectConfig = undefined) {
   const result = loadContentConfig(projectRoot, projectConfig);
@@ -258,21 +266,24 @@ export function getContentTypeElements(projectRoot, contentTypeName, projectConf
  * Load a single content type by its definition.
  *
  * @param {string} name - Content type name
- * @param {any} contentTypeDef - Content type definition from project.json
+ * @param {ContentTypeDef} contentTypeDef - Content type definition from project.json
  * @param {string} projectRoot - Absolute path to project root directory
- * @returns {Promise<any[]>} Array of ContentEntry
+ * @returns {Promise<ContentLoaderEntry[]>} Array of ContentEntry
  */
 async function loadContentType(name, contentTypeDef, projectRoot) {
   const source = contentTypeDef.source;
   const schema = contentTypeDef.schema;
 
   // Derive directive allowedNames from content type $elements (tag names from npm packages)
-  /** @type {any} */
   const directiveOptions = contentTypeDef.$elements?.length
     ? {
         allowedNames: contentTypeDef.$elements
-          .filter((/** @type {any} */ e) => typeof e === "string" || e?.$ref)
-          .map((/** @type {any} */ e) => (typeof e === "string" ? e : e.$ref)),
+          .filter(
+            (e) =>
+              typeof e === "string" ||
+              (typeof e === "object" && /** @type {JxMutableNode} */ (e)?.$ref),
+          )
+          .map((e) => (typeof e === "string" ? e : /** @type {JxMutableNode} */ (e).$ref)),
       }
     : undefined;
 
@@ -280,7 +291,7 @@ async function loadContentType(name, contentTypeDef, projectRoot) {
   const pattern = resolve(projectRoot, source).split("\\").join("/");
   const files = globSync(pattern, { absolute: true });
 
-  /** @type {any[]} */
+  /** @type {ContentLoaderEntry[]} */
   const entries = [];
 
   for (const filePath of files) {
@@ -309,8 +320,8 @@ async function loadContentType(name, contentTypeDef, projectRoot) {
  * Validate content entries against their content type schema. Logs warnings for missing required
  * fields and type mismatches.
  *
- * @param {any[]} entries - Array of ContentEntry
- * @param {any} schema - JSON Schema for the content type
+ * @param {ContentLoaderEntry[]} entries - Array of ContentEntry
+ * @param {ContentTypeSchema} schema - JSON Schema for the content type
  * @param {string} contentTypeName - For error messages
  */
 function validateEntries(entries, schema, contentTypeName) {
@@ -329,23 +340,22 @@ function validateEntries(entries, schema, contentTypeName) {
 
     // Check types
     for (const [field, def] of Object.entries(properties)) {
-      const d = /** @type {any} */ (def);
       const value = entry.data[field];
       if (value == null) continue;
 
-      if (d.type === "string" && typeof value !== "string") {
+      if (def.type === "string" && typeof value !== "string") {
         console.warn(
           `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected string, got ${typeof value}`,
         );
-      } else if (d.type === "number" && typeof value !== "number") {
+      } else if (def.type === "number" && typeof value !== "number") {
         console.warn(
           `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected number, got ${typeof value}`,
         );
-      } else if (d.type === "boolean" && typeof value !== "boolean") {
+      } else if (def.type === "boolean" && typeof value !== "boolean") {
         console.warn(
           `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected boolean, got ${typeof value}`,
         );
-      } else if (d.type === "array" && !Array.isArray(value)) {
+      } else if (def.type === "array" && !Array.isArray(value)) {
         console.warn(
           `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected array, got ${typeof value}`,
         );
@@ -360,18 +370,23 @@ function validateEntries(entries, schema, contentTypeName) {
  * Query a loaded content type with filter, sort, and limit. Implements the ContentCollection
  * $prototype resolution.
  *
- * @param {any[]} entries - Full content type entries
- * @param {any} [query] - Query options
- * @returns {any[]} Filtered, sorted, limited entries
+ * @param {ContentLoaderEntry[]} entries - Full content type entries
+ * @param {{
+ *   filter?: Record<string, unknown>;
+ *   sort?: { field: string; order?: string };
+ *   limit?: number;
+ * }} [query]
+ *   - Query options
+ * @returns {ContentLoaderEntry[]} Filtered, sorted, limited entries
  */
 export function queryContentType(entries, query = {}) {
   let result = [...entries];
 
   // Filter
   if (query.filter && typeof query.filter === "object") {
-    result = result.filter((/** @type {any} */ entry) => {
+    result = result.filter((entry) => {
       for (const [key, expected] of Object.entries(
-        /** @type {Record<string, any>} */ (query.filter),
+        /** @type {Record<string, unknown>} */ (query.filter),
       )) {
         const actual = entry.data[key];
         if (actual !== expected) return false;
@@ -383,9 +398,9 @@ export function queryContentType(entries, query = {}) {
   // Sort
   if (query.sort) {
     const { field, order = "asc" } = query.sort;
-    result.sort((/** @type {any} */ a, /** @type {any} */ b) => {
-      const aVal = a.data[field] ?? "";
-      const bVal = b.data[field] ?? "";
+    result.sort((a, b) => {
+      const aVal = /** @type {string | number} */ (a.data[field] ?? "");
+      const bVal = /** @type {string | number} */ (b.data[field] ?? "");
       if (aVal < bVal) return order === "asc" ? -1 : 1;
       if (aVal > bVal) return order === "asc" ? 1 : -1;
       return 0;
@@ -403,12 +418,12 @@ export function queryContentType(entries, query = {}) {
 /**
  * Find a single entry by ID in a content type. Implements the ContentEntry $prototype resolution.
  *
- * @param {any[]} entries - Full content type entries
+ * @param {ContentLoaderEntry[]} entries - Full content type entries
  * @param {string} id - Entry ID to find
- * @returns {any | null} The matching entry or null
+ * @returns {ContentLoaderEntry | null} The matching entry or null
  */
 export function findEntry(entries, id) {
-  return entries.find((/** @type {any} */ e) => e.id === id) ?? null;
+  return entries.find((e) => e.id === id) ?? null;
 }
 
 // ─── Content Type Reference Resolution ──────────────────────────────────────
@@ -418,29 +433,27 @@ export function findEntry(entries, id) {
  * "jane-doe"` with a schema `$ref` to the authors content type gets resolved to the full author
  * entry.
  *
- * @param {Map<string, any[]>} contentTypes - All loaded content types @param {any} config -
- * Content.config.json
+ * @param {Map<string, ContentLoaderEntry[]>} contentTypes - All loaded content types @param {{
+ * contentTypes: Record<string, ContentTypeDef> }} config - Content config
  */
 export function resolveContentTypeRefs(contentTypes, config) {
   for (const [name, contentTypeDef] of Object.entries(config.contentTypes)) {
-    const cd = /** @type {any} */ (contentTypeDef);
-    const schema = cd.schema;
+    const schema = contentTypeDef.schema;
     if (!schema?.properties) continue;
 
     const entries = contentTypes.get(name);
     if (!entries) continue;
 
     for (const [field, def] of Object.entries(schema.properties)) {
-      const d = /** @type {any} */ (def);
-      if (!d.$ref?.startsWith("#/contentTypes/")) continue;
-      const refContentType = d.$ref.replace("#/contentTypes/", "");
+      if (!def.$ref?.startsWith("#/contentTypes/")) continue;
+      const refContentType = def.$ref.replace("#/contentTypes/", "");
       const refEntries = contentTypes.get(refContentType);
       if (!refEntries) continue;
 
       for (const entry of entries) {
         const refId = entry.data[field];
         if (typeof refId === "string") {
-          const resolved = refEntries.find((/** @type {any} */ e) => e.id === refId);
+          const resolved = refEntries.find((e) => e.id === refId);
           if (resolved) {
             entry.data[field] = resolved;
           }

package/src/site/context-injection.js

@@ -18,12 +18,12 @@ import { resolve, dirname, relative } from "node:path";
 /**
  * Inject $site and $page context into a page document's state.
  *
- * @param {any} doc - The page document (mutated)
- * @param {any} projectConfig - Loaded project configuration
- * @param {any} route - The resolved route for this page
- * @param {Map<string, any[]>} [contentTypes] - Loaded content types
+ * @param {JxDocument} doc - The page document (mutated)
+ * @param {ProjectConfig} projectConfig - Loaded project configuration
+ * @param {SiteRoute} route - The resolved route for this page
+ * @param {Map<string, ContentLoaderEntry[]>} [contentTypes] - Loaded content types
  * @param {string | null} [projectRoot] - Absolute path to the project root (for import rebasing)
- * @returns {any} The mutated document
+ * @returns {JxDocument} The mutated document
  */
 export function injectContext(
   doc,
@@ -57,7 +57,7 @@ export function injectContext(
   if (projectConfig.state) {
     for (const [key, value] of Object.entries(projectConfig.state)) {
       if (key !== "$site" && key !== "$page" && !(key in doc.state)) {
-        doc.state[key] = value;
+        doc.state[key] = /** @type {JxStateDefinition} */ (value);
       }
     }
   }
@@ -91,10 +91,14 @@ export function injectContext(
     } else {
       /** @type {Set<string>} */
       const seen = new Set();
-      /** @type {any[]} */
+      /** @type {(string | JxElement)[]} */
       const merged = [];
-      for (const entry of [...projectConfig.$elements, ...doc.$elements]) {
-        const key = typeof entry === "string" ? entry : entry?.$ref;
+      for (const entry of [
+        ...projectConfig.$elements,
+        .../** @type {(string | JxElement)[]} */ (doc.$elements),
+      ]) {
+        const key =
+          typeof entry === "string" ? entry : /** @type {{ $ref?: string }} */ (entry)?.$ref;
         if (key && !seen.has(key)) {
           seen.add(key);
           merged.push(entry);
@@ -113,40 +117,42 @@ export function injectContext(
  * Replaces state entries like: { "$prototype": "ContentCollection", "contentType": "blog", ... }
  * with the actual resolved content type data.
  *
- * @param {Record<string, any>} state - Page state (mutated)
- * @param {Map<string, any[]>} contentTypes - Loaded content types
- * @param {Record<string, any>} params - Route parameters for $ref resolution
+ * @param {Record<string, unknown>} state - Page state (mutated)
+ * @param {Map<string, ContentLoaderEntry[]>} contentTypes - Loaded content types
+ * @param {Record<string, string>} params - Route parameters for $ref resolution
  */
 function resolveContentPrototypes(state, contentTypes, params) {
   for (const [key, value] of Object.entries(state)) {
-    if (!value || typeof value !== "object" || !value.$prototype) continue;
+    if (!value || typeof value !== "object" || !(/** @type {JxMutableNode} */ (value).$prototype))
+      continue;
+    const v = /** @type {JxPrototypeDef} */ (value);
 
-    if (value.$prototype === "ContentCollection") {
-      const entries = contentTypes.get(value.contentType);
+    if (v.$prototype === "ContentCollection") {
+      const entries = contentTypes.get(/** @type {string} */ (v.contentType));
       if (!entries) {
-        console.warn(`ContentCollection: content type "${value.contentType}" not found`);
+        console.warn(`ContentCollection: content type "${v.contentType}" not found`);
         state[key] = [];
         continue;
       }
       state[key] = queryContentType(entries, {
-        filter: value.filter,
-        sort: value.sort,
-        limit: value.limit,
+        filter: v.filter,
+        sort: v.sort,
+        limit: v.limit,
       });
-    } else if (value.$prototype === "ContentEntry") {
-      const entries = contentTypes.get(value.contentType);
+    } else if (v.$prototype === "ContentEntry") {
+      const entries = contentTypes.get(/** @type {string} */ (v.contentType));
       if (!entries) {
-        console.warn(`ContentEntry: content type "${value.contentType}" not found`);
+        console.warn(`ContentEntry: content type "${v.contentType}" not found`);
         state[key] = null;
         continue;
       }
       // Resolve the ID — may reference $params
-      let id = value.id;
+      let id = v.id;
       if (id && typeof id === "object" && id.$ref?.startsWith("#/$params/")) {
         const paramName = id.$ref.replace("#/$params/", "");
         id = params[paramName];
       }
-      state[key] = findEntry(entries, id);
+      state[key] = findEntry(entries, /** @type {string} */ (id));
     }
   }
 }

package/src/site/head-merger.js

@@ -17,14 +17,15 @@
 /**
  * Merge $head arrays from site, layout, and page levels.
  *
- * @param {any[]} [siteHead] - Site.json $head entries
- * @param {any[]} [layoutHead] - Layout $head entries (may be empty)
- * @param {any[]} [pageHead] - Page $head entries (may be empty)
- * @param {any} [context] - { title, lang, charset, url, pageUrl }
- * @returns {any[]} Merged, deduplicated $head array
+ * @param {JxHeadEntry[]} [siteHead] - Site.json $head entries
+ * @param {JxHeadEntry[]} [layoutHead] - Layout $head entries (may be empty)
+ * @param {JxHeadEntry[]} [pageHead] - Page $head entries (may be empty)
+ * @param {HeadMergeContext} [context] - { title, lang, charset, url, pageUrl }
+ * @returns {JxHeadEntry[]} Merged, deduplicated $head array
  */
 export function mergeHead(siteHead = [], layoutHead = [], pageHead = [], context = {}) {
   // Start with auto-injected defaults
+  /** @type {JxHeadEntry[]} */
   const defaults = [
     { tagName: "meta", attributes: { charset: context.charset ?? "utf-8" } },
     {
@@ -34,7 +35,7 @@ export function mergeHead(siteHead = [], layoutHead = [], pageHead = [], context
   ];
 
   // Merge layers: site → layout → page (later wins)
-  /** @type {Map<string, any>} */
+  /** @type {Map<string, JxHeadEntry>} */
   const merged = new Map();
 
   for (const entry of [...defaults, ...siteHead, ...layoutHead, ...pageHead]) {
@@ -62,7 +63,7 @@ export function mergeHead(siteHead = [], layoutHead = [], pageHead = [], context
  * Generate a deduplication key for a <head> element. Elements with the same key are considered
  * duplicates; the last one wins.
  *
- * @param {any} entry
+ * @param {JxHeadEntry} entry
  * @returns {string}
  */
 function headEntryKey(entry) {
@@ -118,17 +119,17 @@ function simpleHash(str) {
 /**
  * Render a merged $head array to HTML string for insertion into <head>.
  *
- * @param {any[]} headEntries - Merged head entries
+ * @param {JxHeadEntry[]} headEntries - Merged head entries
  * @returns {string} HTML string
  */
 export function renderHead(headEntries) {
-  return headEntries.map((/** @type {any} */ e) => renderHeadEntry(e)).join("\n  ");
+  return headEntries.map((/** @type {JxHeadEntry} */ e) => renderHeadEntry(e)).join("\n  ");
 }
 
 /**
  * Render a single $head entry to an HTML string.
  *
- * @param {any} entry
+ * @param {JxHeadEntry} entry
  * @returns {string}
  */
 function renderHeadEntry(entry) {
@@ -138,7 +139,7 @@ function renderHeadEntry(entry) {
   const tag = entry.tagName;
   const attrs = entry.attributes ?? {};
   const attrStr = Object.entries(attrs)
-    .map(([k, v]) => (v === true ? k : `${k}="${escapeAttr(/** @type {any} */ (v))}"`))
+    .map(([k, v]) => (v === true ? k : `${k}="${escapeAttr(v)}"`))
     .join(" ");
 
   const open = attrStr ? `<${tag} ${attrStr}>` : `<${tag}>`;
@@ -153,7 +154,7 @@ function renderHeadEntry(entry) {
 }
 
 /**
- * @param {any} val
+ * @param {unknown} val
  * @returns {string}
  */
 function escapeAttr(val) {

package/src/site/image-optimizer.js

@@ -20,7 +20,7 @@ async function getSharp() {
     return _sharp;
   } catch (e) {
     throw new Error(
-      `Sharp is required for image optimization but failed to load: ${/** @type {any} */ (e).message}`,
+      `Sharp is required for image optimization but failed to load: ${/** @type {Error} */ (e).message}`,
     );
   }
 }
@@ -152,7 +152,7 @@ export async function processImage(srcPath, outDir, config) {
       const quality = config.quality[/** @type {keyof ImageConfig["quality"]} */ (format)] ?? 80;
       const task = sharp(srcPath)
         .resize(width)
-        .toFormat(/** @type {any} */ (format), { quality })
+        .toFormat(/** @type {keyof import("sharp").FormatEnum} */ (format), { quality })
         .toFile(absolutePath)
         .then(() => {});
 

package/src/site/image-transform.js

@@ -48,7 +48,7 @@ async function resolveManifest(absoluteSrc, src, config, outDir, cache) {
 /**
  * Check if a src value should be skipped for optimization.
  *
- * @param {any} src
+ * @param {string} src
  * @returns {boolean}
  */
 function shouldSkip(src) {
@@ -81,7 +81,7 @@ function resolveImagePath(src, projectRoot) {
  * Mutates img nodes in place, injecting srcset, sizes, width, height, loading, and decoding.
  * Returns a set of absolute source paths that need processing.
  *
- * @param {any} doc - The Jx document tree (mutated in place)
+ * @param {JxMutableNode | JxDocument} doc - The Jx document tree (mutated in place)
  * @param {ImageConfig} config
  * @param {string} projectRoot
  * @param {string} outDir
@@ -100,7 +100,7 @@ export async function transformImageNodes(doc, config, projectRoot, outDir, cach
 }
 
 /**
- * @param {any} node
+ * @param {JxMutableNode | JxDocument} node
  * @param {ImageConfig} config
  * @param {string} projectRoot
  * @param {string} outDir
@@ -127,13 +127,14 @@ async function walkAndTransform(node, config, projectRoot, outDir, cache, imageR
 
   if (Array.isArray(node.children)) {
     for (const child of node.children) {
+      if (typeof child === "string") continue;
       await walkAndTransform(child, config, projectRoot, outDir, cache, imageRefs);
     }
   }
 }
 
 /**
- * @param {any} node
+ * @param {JxMutableNode | JxDocument} node
  * @param {ImageConfig} config
  * @param {string} projectRoot
  * @param {string} outDir