@jxsuite/compiler 0.23.1 → 0.24.0

package/src/site/{content-loader.js → content-loader.ts}

@@ -9,8 +9,15 @@
  * @module content-loader
  */
 
-import { readFileSync, readdirSync, existsSync, globSync } from "node:fs";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { resolve, basename, extname } from "node:path";
+import type {
+  ProjectConfig,
+  ContentTypeDef,
+  ContentTypeSchema,
+  JxMutableNode,
+} from "@jxsuite/schema/types";
+import type { MarkdownFileResult, ContentLoaderEntry } from "@jxsuite/parser/types";
 
 // ─── CSV Parser (minimal, spec-compliant) ─────────────────────────────────────
 
@@ -21,13 +28,11 @@ import { resolve, basename, extname } from "node:path";
  * @param {string} csv - Raw CSV text
  * @returns {Record<string, string>[]} Array of row objects
  */
-function parseCSV(csv) {
-  /** @type {Record<string, string>[]} */
-  const rows = [];
+function parseCSV(csv: string) {
+  const rows: Record<string, string>[] = [];
   let current = "";
   let inQuotes = false;
-  /** @type {string[]} */
-  const lines = [];
+  const lines: string[] = [];
 
   // Split into rows respecting quoted newlines (preserve raw characters)
   for (let i = 0; i < csv.length; i++) {
@@ -53,9 +58,8 @@ function parseCSV(csv) {
   if (lines.length === 0) return [];
 
   /** @param {string} line */
-  const parseRow = (line) => {
-    /** @type {string[]} */
-    const fields = [];
+  const parseRow = (line: string) => {
+    const fields: string[] = [];
     let field = "";
     let q = false;
     for (let i = 0; i < line.length; i++) {
@@ -81,8 +85,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, string>} */
-    const obj = {};
+    const obj: Record<string, string> = {};
     for (let j = 0; j < headers.length; j++) {
       obj[headers[j].trim()] = fields[j]?.trim() ?? "";
     }
@@ -98,7 +101,9 @@ function parseCSV(csv) {
  *   MarkdownFile: new (opts: Record<string, unknown>) => { resolve(): MarkdownFileResult };
  * } | null}
  */
-let _mdModule = null;
+let _mdModule: {
+  MarkdownFile: new (opts: Record<string, unknown>) => { resolve(): MarkdownFileResult };
+} | null = null;
 
 /**
  * Lazily import @jxsuite/parser for Markdown support. This avoids hard dependency — only loads when
@@ -110,9 +115,9 @@ let _mdModule = null;
  */
 async function getMarkdownModule() {
   if (!_mdModule) {
-    _mdModule = /** @type {any} */ (await import("@jxsuite/parser"));
+    _mdModule = (await import("@jxsuite/parser")) as unknown as NonNullable<typeof _mdModule>;
   }
-  return /** @type {NonNullable<typeof _mdModule>} */ (_mdModule);
+  return _mdModule as NonNullable<typeof _mdModule>;
 }
 
 /**
@@ -123,21 +128,21 @@ async function getMarkdownModule() {
  * @param {unknown} [directiveOptions] - Options for the MarkdownDirective plugin
  * @returns {Promise<ContentLoaderEntry>} ContentEntry shape
  */
-async function loadMarkdownEntry(filePath, directiveOptions) {
+async function loadMarkdownEntry(filePath: string, directiveOptions?: unknown) {
   const { MarkdownFile } = await getMarkdownModule();
   const file = new MarkdownFile({ src: filePath, directiveOptions });
   const result = file.resolve();
+  const _meta: ContentLoaderEntry["_meta"] = {};
+  if (result.$excerpt != null) _meta.excerpt = result.$excerpt;
+  if (result.$toc != null) _meta.toc = result.$toc;
+  if (result.$readingTime != null) _meta.readingTime = result.$readingTime;
+  if (result.$wordCount != null) _meta.wordCount = result.$wordCount;
   return {
     id: result.slug,
     data: result.frontmatter,
     body: readFileSync(filePath, "utf-8"),
     $children: result.$children,
-    _meta: {
-      excerpt: result.$excerpt,
-      toc: result.$toc,
-      readingTime: result.$readingTime,
-      wordCount: result.$wordCount,
-    },
+    _meta,
   };
 }
 
@@ -148,21 +153,20 @@ async function loadMarkdownEntry(filePath, directiveOptions) {
  * @param {string} filePath - Absolute path to .json file
  * @returns {ContentLoaderEntry[]} Array of ContentEntry shapes
  */
-function loadJSONEntries(filePath) {
+function loadJSONEntries(filePath: string) {
   const raw = JSON.parse(readFileSync(filePath, "utf-8"));
   if (Array.isArray(raw)) {
-    return raw.map((/** @type {Record<string, unknown>} */ item, /** @type {number} */ i) => ({
-      id: /** @type {string} */ (item.id) ?? basename(filePath, ".json") + "-" + i,
+    return raw.map((item: Record<string, unknown>, i: number) => ({
+      id: (item.id as string) ?? basename(filePath, ".json") + "-" + i,
       data: item,
       body: null,
     }));
   }
   // Single object file — filename is the id
-  /** @type {Record<string, unknown>} */
-  const rawObj = raw;
+  const rawObj: Record<string, unknown> = raw;
   return [
     {
-      id: /** @type {string} */ (rawObj.id) ?? basename(filePath, ".json"),
+      id: (rawObj.id as string) ?? basename(filePath, ".json"),
       data: rawObj,
       body: null,
     },
@@ -176,13 +180,12 @@ function loadJSONEntries(filePath) {
  * @param {ContentTypeSchema} [schema] - Content type schema (for type coercion)
  * @returns {ContentLoaderEntry[]} Array of ContentEntry shapes
  */
-function loadCSVEntries(filePath, schema) {
+function loadCSVEntries(filePath: string, schema?: ContentTypeSchema) {
   const csv = readFileSync(filePath, "utf-8");
   const rows = parseCSV(csv);
-  return rows.map((/** @type {Record<string, string>} */ row, /** @type {number} */ i) => {
+  return rows.map((row: Record<string, string>, i: number) => {
     // Apply type coercion based on schema if available
-    /** @type {Record<string, unknown>} */
-    const data = { ...row };
+    const data: Record<string, unknown> = { ...row };
     if (schema?.properties) {
       for (const [key, def] of Object.entries(schema.properties)) {
         if (key in data) {
@@ -192,9 +195,7 @@ function loadCSVEntries(filePath, schema) {
       }
     }
     // Use `id` column, `sku` column, or row index as the entry ID
-    const id = /** @type {string | undefined} */ (data.id) ??
-    /** @type {string | undefined} */ (data.sku) ??
-    String(i);
+    const id = (data.id as string | undefined) ?? (data.sku as string | undefined) ?? String(i);
     return { id, data, body: null };
   });
 }
@@ -212,7 +213,7 @@ function loadCSVEntries(filePath, schema) {
  * } | null}
  *   Parsed config or null if no content dir
  */
-export function loadContentConfig(projectRoot, projectConfig = undefined) {
+export function loadContentConfig(projectRoot: string, projectConfig?: ProjectConfig) {
   const contentDir = resolve(projectRoot, "content");
 
   const config = { contentTypes: projectConfig?.contentTypes ?? {} };
@@ -230,13 +231,12 @@ export function loadContentConfig(projectRoot, projectConfig = undefined) {
  * @returns {Promise<Map<string, ContentLoaderEntry[]>>} Map of content type name → array of
  *   ContentEntry
  */
-export async function loadContentTypes(projectRoot, projectConfig = undefined) {
+export async function loadContentTypes(projectRoot: string, projectConfig?: ProjectConfig) {
   const result = loadContentConfig(projectRoot, projectConfig);
   if (!result) return new Map();
 
   const { config } = result;
-  /** @type {Map<string, ContentLoaderEntry[]>} */
-  const contentTypes = new Map();
+  const contentTypes: Map<string, ContentLoaderEntry[]> = new Map();
 
   for (const [name, contentTypeDef] of Object.entries(config.contentTypes)) {
     const entries = await loadContentType(name, contentTypeDef, projectRoot);
@@ -254,7 +254,11 @@ export async function loadContentTypes(projectRoot, projectConfig = undefined) {
  * @param {ProjectConfig} [projectConfig] - Already-loaded project config
  * @returns {(string | JxElement)[] | undefined}
  */
-export function getContentTypeElements(projectRoot, contentTypeName, projectConfig = undefined) {
+export function getContentTypeElements(
+  projectRoot: string,
+  contentTypeName: string,
+  projectConfig?: ProjectConfig,
+) {
   const result = loadContentConfig(projectRoot, projectConfig);
   if (!result) return undefined;
   const def = result.config.contentTypes?.[contentTypeName];
@@ -269,8 +273,9 @@ export function getContentTypeElements(projectRoot, contentTypeName, projectConf
  * @param {string} projectRoot - Absolute path to project root directory
  * @returns {Promise<ContentLoaderEntry[]>} Array of ContentEntry
  */
-async function loadContentType(name, contentTypeDef, projectRoot) {
+async function loadContentType(name: string, contentTypeDef: ContentTypeDef, projectRoot: string) {
   const source = contentTypeDef.source;
+  if (!source) return [];
   const schema = contentTypeDef.schema;
 
   // Derive directive allowedNames from content type $elements (tag names from npm packages)
@@ -278,22 +283,18 @@ async function loadContentType(name, contentTypeDef, projectRoot) {
     ? {
         allowedNames: contentTypeDef.$elements
           .filter(
-            (e) =>
-              typeof e === "string" ||
-              (typeof e === "object" && /** @type {JxMutableNode} */ (e)?.$ref),
+            (e) => typeof e === "string" || (typeof e === "object" && (e as JxMutableNode)?.$ref),
           )
-          .map((e) => (typeof e === "string" ? e : /** @type {JxMutableNode} */ (e).$ref)),
+          .map((e) => (typeof e === "string" ? e : (e as JxMutableNode).$ref)),
       }
     : undefined;
 
   // Resolve source path and discover files
   const resolvedSource = resolve(projectRoot, source).split("\\").join("/");
   /** @type {string[]} */
-  let files;
+  let files: string[];
 
-  if (source.includes("*") || source.includes("?")) {
-    files = globSync(source, { cwd: projectRoot }).map((f) => resolve(projectRoot, f));
-  } else if (extname(source)) {
+  if (extname(source)) {
     files = existsSync(resolvedSource) ? [resolvedSource] : [];
   } else {
     const format = contentTypeDef.format || "md";
@@ -308,8 +309,7 @@ async function loadContentType(name, contentTypeDef, projectRoot) {
     }
   }
 
-  /** @type {ContentLoaderEntry[]} */
-  const entries = [];
+  const entries: ContentLoaderEntry[] = [];
 
   for (const filePath of files) {
     const ext = extname(filePath).toLowerCase();
@@ -341,7 +341,11 @@ async function loadContentType(name, contentTypeDef, projectRoot) {
  * @param {ContentTypeSchema} schema - JSON Schema for the content type
  * @param {string} contentTypeName - For error messages
  */
-function validateEntries(entries, schema, contentTypeName) {
+function validateEntries(
+  entries: ContentLoaderEntry[],
+  schema: ContentTypeSchema,
+  contentTypeName: string,
+) {
   const required = schema.required ?? [];
   const properties = schema.properties ?? {};
 
@@ -395,7 +399,10 @@ export { queryContentType, findEntry } from "@jxsuite/parser/content";
  * @param {Map<string, ContentLoaderEntry[]>} contentTypes - All loaded content types @param {{
  * contentTypes: Record<string, ContentTypeDef> }} config - Content config
  */
-export function resolveContentTypeRefs(contentTypes, config) {
+export function resolveContentTypeRefs(
+  contentTypes: Map<string, ContentLoaderEntry[]>,
+  config: { contentTypes: Record<string, ContentTypeDef> },
+) {
   for (const [name, contentTypeDef] of Object.entries(config.contentTypes)) {
     const schema = contentTypeDef.schema;
     if (!schema?.properties) continue;

package/src/site/{context-injection.js → context-injection.ts}

@@ -13,6 +13,14 @@
  */
 
 import { resolve, dirname, relative } from "node:path";
+import type {
+  JxElement,
+  JxDocument,
+  JxStateDefinition,
+  ProjectConfig,
+} from "@jxsuite/schema/types";
+import type { ContentLoaderEntry } from "@jxsuite/parser/types";
+import type { SiteRoute } from "../types.ts";
 
 /**
  * Inject $site and $page context into a page document's state.
@@ -25,11 +33,11 @@ import { resolve, dirname, relative } from "node:path";
  * @returns {JxDocument} The mutated document
  */
 export function injectContext(
-  doc,
-  projectConfig,
-  route,
-  contentTypes = new Map(),
-  projectRoot = null,
+  doc: JxDocument,
+  projectConfig: ProjectConfig,
+  route: SiteRoute,
+  contentTypes: Map<string, ContentLoaderEntry[]> = new Map(),
+  projectRoot: string | null = null,
 ) {
   if (!doc.state) doc.state = {};
 
@@ -51,7 +59,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] = /** @type {JxStateDefinition} */ (value);
+        doc.state[key] = value as JxStateDefinition;
       }
     }
   }
@@ -66,7 +74,7 @@ export function injectContext(
     if (!doc.imports) doc.imports = {};
     for (const [name, srcPath] of Object.entries(projectConfig.imports)) {
       if (!(name in doc.imports)) {
-        const src = /** @type {string} */ (srcPath);
+        const src = srcPath as string;
         // Only rebase relative paths — bare/npm specifiers pass through unmodified
         if (projectRoot && route.sourcePath && (src.startsWith("./") || src.startsWith("../"))) {
           const abs = resolve(projectRoot, src);
@@ -83,13 +91,11 @@ export function injectContext(
     if (!doc.$elements?.length) {
       doc.$elements = [...projectConfig.$elements];
     } else {
-      /** @type {Set<string>} */
-      const seen = new Set();
-      /** @type {(string | JxElement)[]} */
-      const merged = [];
+      const seen: Set<string> = new Set();
+      const merged: (string | JxElement)[] = [];
       for (const entry of [
         ...projectConfig.$elements,
-        .../** @type {(string | JxElement)[]} */ (doc.$elements),
+        ...(doc.$elements as (string | JxElement)[]),
       ]) {
         const key =
           typeof entry === "string" ? entry : /** @type {{ $ref?: string }} */ (entry)?.$ref;

package/src/site/{head-merger.js → head-merger.ts}

@@ -14,6 +14,9 @@
  * - Charset and viewport are auto-injected if missing
  */
 
+import type { JxHeadEntry } from "@jxsuite/schema/types";
+import type { HeadMergeContext } from "../types.ts";
+
 /**
  * Merge $head arrays from site, layout, and page levels.
  *
@@ -23,10 +26,14 @@
  * @param {HeadMergeContext} [context] - { title, lang, charset, url, pageUrl }
  * @returns {JxHeadEntry[]} Merged, deduplicated $head array
  */
-export function mergeHead(siteHead = [], layoutHead = [], pageHead = [], context = {}) {
+export function mergeHead(
+  siteHead: JxHeadEntry[] = [],
+  layoutHead: JxHeadEntry[] = [],
+  pageHead: JxHeadEntry[] = [],
+  context: HeadMergeContext = {},
+) {
   // Start with auto-injected defaults
-  /** @type {JxHeadEntry[]} */
-  const defaults = [
+  const defaults: JxHeadEntry[] = [
     { tagName: "meta", attributes: { charset: context.charset ?? "utf-8" } },
     {
       tagName: "meta",
@@ -35,8 +42,7 @@ export function mergeHead(siteHead = [], layoutHead = [], pageHead = [], context
   ];
 
   // Merge layers: site → layout → page (later wins)
-  /** @type {Map<string, JxHeadEntry>} */
-  const merged = new Map();
+  const merged: Map<string, JxHeadEntry> = new Map();
 
   for (const entry of [...defaults, ...siteHead, ...layoutHead, ...pageHead]) {
     const key = headEntryKey(entry);
@@ -66,7 +72,7 @@ export function mergeHead(siteHead = [], layoutHead = [], pageHead = [], context
  * @param {JxHeadEntry} entry
  * @returns {string}
  */
-function headEntryKey(entry) {
+function headEntryKey(entry: JxHeadEntry) {
   if (!entry || typeof entry !== "object") return String(entry);
 
   const tag = entry.tagName ?? "unknown";
@@ -110,7 +116,7 @@ function headEntryKey(entry) {
  * @param {string} str
  * @returns {string}
  */
-function simpleHash(str) {
+function simpleHash(str: string) {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
     hash = ((hash << 5) - hash + str.charCodeAt(i)) | 0;
@@ -124,8 +130,8 @@ function simpleHash(str) {
  * @param {JxHeadEntry[]} headEntries - Merged head entries
  * @returns {string} HTML string
  */
-export function renderHead(headEntries) {
-  return headEntries.map((/** @type {JxHeadEntry} */ e) => renderHeadEntry(e)).join("\n  ");
+export function renderHead(headEntries: JxHeadEntry[]) {
+  return headEntries.map((e: JxHeadEntry) => renderHeadEntry(e)).join("\n  ");
 }
 
 /**
@@ -134,7 +140,7 @@ export function renderHead(headEntries) {
  * @param {JxHeadEntry} entry
  * @returns {string}
  */
-function renderHeadEntry(entry) {
+function renderHeadEntry(entry: JxHeadEntry) {
   if (typeof entry === "string") return entry;
   if (!entry || typeof entry !== "object") return "";
 
@@ -161,6 +167,6 @@ function renderHeadEntry(entry) {
  * @param {unknown} val
  * @returns {string}
  */
-function escapeAttr(val) {
+function escapeAttr(val: unknown) {
   return String(val).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }

package/src/site/{image-cache.js → image-cache.ts}

@@ -7,26 +7,21 @@
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { contentHash, configHash } from "./image-optimizer.js";
+import { contentHash, configHash } from "./image-optimizer.ts";
 
-/**
- * @typedef {import("./image-optimizer.js").ImageManifest} ImageManifest
- *
- * @typedef {import("./image-optimizer.js").ImageConfig} ImageConfig
- */
+import type { ImageManifest } from "./image-optimizer.ts";
+import type { ImageConfig } from "./image-optimizer.ts";
 
-/**
- * @typedef {Object} CacheEntry
- * @property {string} source - Relative path to source image
- * @property {ImageManifest} manifest - Processed image manifest
- * @property {number} timestamp - When the entry was cached
- */
+interface CacheEntry {
+  source: string; // Relative path to source image
+  manifest: ImageManifest; // Processed image manifest
+  timestamp: number; // When the entry was cached
+}
 
-/**
- * @typedef {Object} CacheManifest
- * @property {number} version - Cache format version
- * @property {Record<string, CacheEntry>} entries - Cached entries keyed by content+config hash
- */
+export interface CacheManifest {
+  version: number; // Cache format version
+  entries: Record<string, CacheEntry>; // Cached entries keyed by content+config hash
+}
 
 /**
  * Build a cache key from source file content and config.
@@ -35,7 +30,7 @@ import { contentHash, configHash } from "./image-optimizer.js";
  * @param {ImageConfig} config
  * @returns {string}
  */
-export function cacheKey(srcPath, config) {
+export function cacheKey(srcPath: string, config: ImageConfig) {
   return `${contentHash(srcPath)}:${configHash(config)}`;
 }
 
@@ -45,7 +40,7 @@ export function cacheKey(srcPath, config) {
  * @param {string} projectRoot
  * @returns {CacheManifest}
  */
-export function loadCache(projectRoot) {
+export function loadCache(projectRoot: string) {
   const manifestPath = resolve(projectRoot, ".jx-cache/images/manifest.json");
   if (!existsSync(manifestPath)) {
     return { version: 1, entries: {} };
@@ -63,7 +58,7 @@ export function loadCache(projectRoot) {
  * @param {string} projectRoot
  * @param {CacheManifest} cache
  */
-export function saveCache(projectRoot, cache) {
+export function saveCache(projectRoot: string, cache: CacheManifest) {
   const cacheDir = resolve(projectRoot, ".jx-cache/images");
   mkdirSync(cacheDir, { recursive: true });
   writeFileSync(resolve(cacheDir, "manifest.json"), JSON.stringify(cache, null, 2), "utf8");
@@ -76,7 +71,7 @@ export function saveCache(projectRoot, cache) {
  * @param {string} key
  * @returns {ImageManifest | null}
  */
-export function getCached(cache, key) {
+export function getCached(cache: CacheManifest, key: string) {
   const entry = cache.entries[key];
   if (!entry) return null;
   return entry.manifest;
@@ -90,7 +85,12 @@ export function getCached(cache, key) {
  * @param {string} sourcePath - Relative source path for reference
  * @param {ImageManifest} manifest
  */
-export function setCached(cache, key, sourcePath, manifest) {
+export function setCached(
+  cache: CacheManifest,
+  key: string,
+  sourcePath: string,
+  manifest: ImageManifest,
+) {
   cache.entries[key] = {
     source: sourcePath,
     manifest,

package/src/site/{image-optimizer.js → image-optimizer.ts}

@@ -9,8 +9,29 @@ import { createHash } from "node:crypto";
 import { readFileSync, mkdirSync, existsSync } from "node:fs";
 import { resolve, basename, extname } from "node:path";
 
-/** @type {typeof import("sharp") | null} */
-let _sharp = null;
+export interface ImageVariant {
+  width: number; // Pixel width of the variant
+  format: string; // "webp", "avif", "jpeg", "png"
+  outputPath: string; // Relative path from outDir (e.g.
+  absolutePath: string; // Absolute filesystem path to the generated file
+}
+
+export interface ImageManifest {
+  variants: ImageVariant[]; // Array of generated responsive variants
+  contentHash: string; // 8-char content hash for cache busting
+  original?: { width: number; height: number }; // Original image dimensions
+}
+
+export interface ImageConfig {
+  optimize: boolean;
+  widths: number[];
+  formats: string[];
+  quality: { webp?: number; avif?: number; jpeg?: number; png?: number };
+  sizes: string;
+  lazyLoad: boolean;
+}
+
+let _sharp: typeof import("sharp") | null = null;
 
 async function getSharp() {
   if (_sharp) return _sharp;
@@ -20,39 +41,11 @@ async function getSharp() {
     return _sharp;
   } catch (e) {
     throw new Error(
-      `Sharp is required for image optimization but failed to load: ${/** @type {Error} */ (e).message}`,
+      `Sharp is required for image optimization but failed to load: ${(e as Error).message}`,
     );
   }
 }
 
-/**
- * @typedef {Object} ImageVariant
- * @property {number} width - Pixel width of the variant
- * @property {string} format - "webp", "avif", "jpeg", "png"
- * @property {string} outputPath - Relative path from outDir (e.g.
- *   "/images/_optimized/hero-640-a1b2c3d4.webp")
- * @property {string} absolutePath - Absolute filesystem path to the generated file
- */
-
-/**
- * @typedef {Object} ImageManifest
- * @property {{ width: number; height: number; format: string }} original - Original image
- *   dimensions and format
- * @property {ImageVariant[]} variants - Array of generated responsive variants
- * @property {string} contentHash - 8-char content hash for cache busting
- */
-
-/**
- * @typedef {Object} ImageConfig
- * @property {boolean} optimize - Enable image optimization
- * @property {number[]} widths - Breakpoint widths to generate
- * @property {string[]} formats - Output formats ("webp", "avif", etc.)
- * @property {{ webp?: number; avif?: number; jpeg?: number; png?: number }} quality - Compression
- *   quality per format
- * @property {string} sizes - CSS sizes attribute for srcset
- * @property {boolean} lazyLoad - Add loading="lazy" and decoding="async"
- */
-
 const OPTIMIZED_DIR = "images/_optimized";
 
 /**
@@ -61,13 +54,13 @@ const OPTIMIZED_DIR = "images/_optimized";
  * @param {string} srcPath - Absolute path to source image
  * @returns {Promise<{ width: number; height: number; format: string }>}
  */
-export async function getImageMetadata(srcPath) {
+export async function getImageMetadata(srcPath: string) {
   const sharp = await getSharp();
   const meta = await sharp(srcPath).metadata();
   return {
     width: meta.width ?? 0,
     height: meta.height ?? 0,
-    format: meta.format ?? "unknown",
+    format: (meta.format ?? "unknown") as string,
   };
 }
 
@@ -77,7 +70,7 @@ export async function getImageMetadata(srcPath) {
  * @param {string} srcPath - Absolute path to source image
  * @returns {string} 8-character hex hash
  */
-export function contentHash(srcPath) {
+export function contentHash(srcPath: string) {
   const buf = readFileSync(srcPath);
   return createHash("md5").update(buf).digest("hex").slice(0, 8);
 }
@@ -88,7 +81,7 @@ export function contentHash(srcPath) {
  * @param {ImageConfig} config
  * @returns {string}
  */
-export function configHash(config) {
+export function configHash(config: ImageConfig) {
   const key = JSON.stringify({
     widths: config.widths,
     formats: config.formats,
@@ -106,7 +99,7 @@ export function configHash(config) {
  * @param {string} format - "webp", "avif", "jpeg", "png"
  * @returns {string}
  */
-export function variantFilename(stem, width, hash8, format) {
+export function variantFilename(stem: string, width: number, hash8: string, format: string) {
   return `${stem}-${width}-${hash8}.${format}`;
 }
 
@@ -118,7 +111,7 @@ export function variantFilename(stem, width, hash8, format) {
  * @param {ImageConfig} config
  * @returns {Promise<ImageManifest>}
  */
-export async function processImage(srcPath, outDir, config) {
+export async function processImage(srcPath: string, outDir: string, config: ImageConfig) {
   const sharp = await getSharp();
   const meta = await getImageMetadata(srcPath);
   const hash8 = contentHash(srcPath);
@@ -127,8 +120,7 @@ export async function processImage(srcPath, outDir, config) {
   const optimizedDir = resolve(outDir, OPTIMIZED_DIR);
   mkdirSync(optimizedDir, { recursive: true });
 
-  /** @type {ImageVariant[]} */
-  const variants = [];
+  const variants: ImageVariant[] = [];
 
   const widths = config.widths.filter((w) => w <= meta.width);
   if (widths.length === 0 || !widths.includes(meta.width)) {
@@ -136,8 +128,7 @@ export async function processImage(srcPath, outDir, config) {
   }
   widths.sort((a, b) => a - b);
 
-  /** @type {Promise<void>[]} */
-  const tasks = [];
+  const tasks: Promise<void>[] = [];
 
   for (const width of widths) {
     for (const format of config.formats) {
@@ -149,10 +140,10 @@ export async function processImage(srcPath, outDir, config) {
 
       if (existsSync(absolutePath)) continue;
 
-      const quality = config.quality[/** @type {keyof ImageConfig["quality"]} */ (format)] ?? 80;
+      const quality = config.quality[format as keyof ImageConfig["quality"]] ?? 80;
       const task = sharp(srcPath)
         .resize(width)
-        .toFormat(/** @type {keyof import("sharp").FormatEnum} */ (format), { quality })
+        .toFormat(format as keyof import("sharp").FormatEnum, { quality })
         .toFile(absolutePath)
         .then(() => {});
 
@@ -179,7 +170,7 @@ export async function processImage(srcPath, outDir, config) {
  * @param {string} format
  * @returns {string}
  */
-export function buildSrcset(variants, format) {
+export function buildSrcset(variants: ImageVariant[], format: string) {
   return variants
     .filter((v) => v.format === format)
     .map((v) => `${v.outputPath} ${v.width}w`)