@jxsuite/compiler 0.23.1 → 0.24.0

package/src/site/{site-build.js → site-build.ts}

@@ -1,5 +1,5 @@
 /**
- * Site-build.js — Multi-page build orchestrator
+ * Site-build — Multi-page build orchestrator
  *
  * Coordinates the full site build pipeline: 1. Load project.json 2. Discover pages/ routes 3.
  * Expand dynamic routes ($paths) 4. For each route: resolve layout, merge $head, inject context,
@@ -20,13 +20,13 @@ import {
   readdirSync,
 } from "node:fs";
 import { resolve, dirname, join } from "node:path";
-import { loadProjectConfig } from "./site-loader.js";
-import { discoverPages, expandDynamicRoutes } from "./pages-discovery.js";
-import { resolveLayout } from "./layout-resolver.js";
-import { mergeHead, renderHead } from "./head-merger.js";
-import { injectContext } from "./context-injection.js";
-import { compile, compileServer, compileSiteServer, compilePagesFunctions } from "../compiler.js";
-import { compileElement } from "../targets/compile-element.js";
+import { loadProjectConfig } from "./site-loader.ts";
+import { discoverPages, expandDynamicRoutes } from "./pages-discovery.ts";
+import { resolveLayout } from "./layout-resolver.ts";
+import { mergeHead, renderHead } from "./head-merger.ts";
+import { injectContext } from "./context-injection.ts";
+import { compile, compileServer, compileSiteServer, compilePagesFunctions } from "../compiler.ts";
+import { compileElement } from "../targets/compile-element.ts";
 import {
   buildInitialScope,
   isTemplateString,
@@ -40,12 +40,22 @@ import {
   resolveRefValue,
   DEFAULT_REACTIVITY_SRC,
   DEFAULT_LIT_HTML_SRC,
-} from "../shared.js";
-import { loadContentTypes, loadContentConfig, resolveContentTypeRefs } from "./content-loader.js";
-import { resolvePrototypes } from "./prototype-resolver.js";
-import { compileMarkdown } from "../targets/compile-markdown.js";
-import { transformImageNodes } from "./image-transform.js";
-import { loadCache, saveCache } from "./image-cache.js";
+} from "../shared.ts";
+import { loadContentTypes, loadContentConfig, resolveContentTypeRefs } from "./content-loader.ts";
+import { resolvePrototypes } from "./prototype-resolver.ts";
+import { compileMarkdown } from "../targets/compile-markdown.ts";
+import { transformImageNodes } from "./image-transform.ts";
+import { loadCache, saveCache } from "./image-cache.ts";
+import type {
+  JxElement,
+  JxMutableNode,
+  JxStyle,
+  JxHeadEntry,
+  JxStateDefinition,
+  ProjectConfig,
+} from "@jxsuite/schema/types";
+import type { ContentLoaderEntry } from "@jxsuite/parser/types";
+import type { SiteRoute } from "../types.ts";
 
 /**
  * Build an entire Jx site from a project directory.
@@ -56,10 +66,15 @@ import { loadCache, saveCache } from "./image-cache.js";
  * @param {boolean} [options.verbose] - Log progress
  * @returns {Promise<{ routes: number; files: number; errors: string[] }>}
  */
-export async function buildSite(projectRoot, options = {}) {
+export async function buildSite(
+  projectRoot: string,
+  options: {
+    clean?: boolean;
+    verbose?: boolean;
+  } = {},
+) {
   const { clean = true, verbose = false } = options;
-  /** @type {string[]} */
-  const errors = [];
+  const errors: string[] = [];
   const log = verbose ? console.log.bind(console) : () => {};
 
   // ── 1. Load project configuration ──────────────────────────────────────────
@@ -118,16 +133,13 @@ export async function buildSite(projectRoot, options = {}) {
 
   // ── 5. Compile site components ──────────────────────────────────────────
   const componentsDir = resolve(projectRoot, "components");
-  /** @type {string[]} */
-  const compiledComponentTags = [];
-  /** @type {Map<string, string>} */
-  const componentCSS = new Map(); // tagName → CSS text
-  /** @type {Map<string, JxElement>} */
-  const componentDefs = new Map(); // tagName → parsed component definition
+  const compiledComponentTags: string[] = [];
+  const componentCSS: Map<string, string> = new Map(); // tagName → CSS text
+  const componentDefs: Map<string, JxElement> = new Map(); // tagName → parsed component definition
   if (existsSync(componentsDir)) {
     log("Compiling components...");
     const componentFiles = readdirSync(componentsDir).filter(
-      (/** @type {string} */ f) => f.endsWith(".json") || f.endsWith(".md"),
+      (f: string) => f.endsWith(".json") || f.endsWith(".md"),
     );
     const componentOutDir = resolve(outDir, "components");
     mkdirSync(componentOutDir, { recursive: true });
@@ -137,9 +149,7 @@ export async function buildSite(projectRoot, options = {}) {
         const componentPath = resolve(componentsDir, file);
         const result = await compileElement(componentPath, { $media: projectConfig.$media });
         for (const f of result.files) {
-          const outName = f.path.includes("/")
-            ? /** @type {string} */ (f.path.split("/").pop())
-            : f.path;
+          const outName = f.path.includes("/") ? (f.path.split("/").pop() as string) : f.path;
           writeFileSync(resolve(componentOutDir, outName), f.content, "utf8");
           if (f.tagName) compiledComponentTags.push(f.tagName);
           fileCount++;
@@ -161,7 +171,7 @@ export async function buildSite(projectRoot, options = {}) {
           }
         }
       } catch (e) {
-        const err = /** @type {Error} */ (e);
+        const err = e as Error;
         errors.push(`Error compiling component ${file}: ${err.message}`);
         console.error(`Error compiling component ${file}: ${err.message}`);
       }
@@ -192,7 +202,7 @@ export async function buildSite(projectRoot, options = {}) {
     try {
       log(`  Compiling ${route.urlPattern} ...`);
       const result = await compilePage(
-        route,
+        route as unknown as SiteRoute,
         projectConfig,
         projectRoot,
         contentTypes,
@@ -202,8 +212,7 @@ export async function buildSite(projectRoot, options = {}) {
       );
 
       // Determine which component tags are fully static (for script omission)
-      /** @type {Set<string>} */
-      const staticTags = new Set();
+      const staticTags: Set<string> = new Set();
       for (const [tag, def] of componentDefs) {
         if (isComponentFullyStatic(def)) staticTags.add(tag);
       }
@@ -233,7 +242,7 @@ export async function buildSite(projectRoot, options = {}) {
           fileCount++;
         }
       } catch (e) {
-        const err = /** @type {Error} */ (e);
+        const err = e as Error;
         errors.push(`Error exporting markdown for ${route.urlPattern}: ${err.message}`);
       }
 
@@ -252,7 +261,7 @@ export async function buildSite(projectRoot, options = {}) {
         fileCount++;
       }
     } catch (e) {
-      const err = /** @type {Error} */ (e);
+      const err = e as Error;
       const msg = `Error compiling ${route.urlPattern}: ${err.message}`;
       errors.push(msg);
       console.error(msg);
@@ -341,8 +350,8 @@ export async function buildSite(projectRoot, options = {}) {
   if (projectConfig.copy) {
     log("Copying mapped files...");
     for (const [src, dest] of Object.entries(projectConfig.copy)) {
-      const srcPath = resolve(projectRoot, /** @type {string} */ (src));
-      const destPath = resolve(outDir, /** @type {string} */ (dest));
+      const srcPath = resolve(projectRoot, src as string);
+      const destPath = resolve(outDir, dest as string);
       mkdirSync(dirname(destPath), { recursive: true });
       cpSync(srcPath, destPath);
     }
@@ -377,30 +386,30 @@ export async function buildSite(projectRoot, options = {}) {
  * }>}
  */
 async function compilePage(
-  route,
-  projectConfig,
-  projectRoot,
-  contentTypes = new Map(),
-  imageCache = null,
-  outDir = "",
-  componentDefs = new Map(),
+  route: SiteRoute,
+  projectConfig: ProjectConfig,
+  projectRoot: string,
+  contentTypes: Map<string, ContentLoaderEntry[]> = new Map(),
+  imageCache: import("./image-cache.js").CacheManifest | null = null,
+  outDir: string = "",
+  componentDefs: Map<string, JxElement> = new Map(),
 ) {
   // Load the raw page document
   let pageDoc;
-  if (/** @type {string} */ (route.sourcePath).endsWith(".md")) {
+  if ((route.sourcePath as string).endsWith(".md")) {
     const { transpileJxMarkdown } = await import("@jxsuite/parser/transpile");
-    pageDoc = transpileJxMarkdown(readFileSync(/** @type {string} */ (route.sourcePath), "utf8"));
+    pageDoc = transpileJxMarkdown(readFileSync(route.sourcePath as string, "utf8"));
   } else {
-    pageDoc = JSON.parse(readFileSync(/** @type {string} */ (route.sourcePath), "utf8"));
+    pageDoc = JSON.parse(readFileSync(route.sourcePath as string, "utf8"));
   }
 
   // Resolve layout (wraps page in layout with slot distribution)
   const layoutDoc = resolveLayout(pageDoc, projectConfig, projectRoot);
 
   // Extract head arrays before they get lost in the merge
-  const pageHead = /** @type {JxHeadEntry[]} */ (pageDoc.$head ?? layoutDoc._pageHead ?? []);
+  const pageHead = pageDoc.$head ?? layoutDoc._pageHead ?? ([] as JxHeadEntry[]);
   const layoutHead = layoutDoc.$head ?? [];
-  const pageTitle = /** @type {string | null} */ (pageDoc.title ?? layoutDoc._pageTitle ?? null);
+  const pageTitle = pageDoc.title ?? layoutDoc._pageTitle ?? (null as string | null);
 
   // Clean up internal properties
   delete layoutDoc._pageHead;
@@ -421,7 +430,7 @@ async function compilePage(
   // Determine the page title — resolve template strings against the scope
   let title = pageTitle ?? projectConfig.name ?? "Jx Site";
   if (typeof title === "string" && isTemplateString(title)) {
-    title = /** @type {string} */ (evaluateStaticTemplate(title, scope) ?? title);
+    title = evaluateStaticTemplate(title, scope) ?? (title as string);
   }
 
   // Resolve template strings in $head entries
@@ -446,7 +455,7 @@ async function compilePage(
         def &&
         typeof def === "object" &&
         !Array.isArray(def) &&
-        /** @type {JxMutableNode} */ (def).timing === "compiler"
+        (def as JxMutableNode).timing === "compiler"
       ) {
         delete layoutDoc.state[key];
       } else if (Array.isArray(def)) {
@@ -462,8 +471,8 @@ async function compilePage(
   const mergedHead = mergeHead(resolvedSiteHead, resolvedLayoutHead, resolvedPageHead, {
     title,
     charset: projectConfig.defaults?.charset ?? "utf-8",
-    siteName: projectConfig.name,
-    siteUrl: projectConfig.url,
+    ...(projectConfig.name != null && { siteName: projectConfig.name }),
+    ...(projectConfig.url != null && { siteUrl: projectConfig.url }),
     pageUrl: route.urlPattern,
   });
 
@@ -474,7 +483,13 @@ async function compilePage(
 
   // Transform <img> nodes for responsive image optimization
   if (imageCache && projectConfig.images?.optimize && outDir) {
-    await transformImageNodes(layoutDoc, projectConfig.images, projectRoot, outDir, imageCache);
+    await transformImageNodes(
+      layoutDoc,
+      projectConfig.images as import("./image-optimizer").ImageConfig,
+      projectRoot,
+      outDir,
+      imageCache,
+    );
   }
 
   // Compile the document using the existing compiler
@@ -489,19 +504,17 @@ async function compilePage(
 
   // Inject <script type="module"> for npm $elements (cherry-picked component imports)
   const npmElements = (layoutDoc.$elements ?? []).filter(
-    (/** @type {JxElement | string} */ e) =>
-      typeof e === "string" && !e.startsWith("./") && !e.startsWith("../"),
+    (e: JxElement | string) => typeof e === "string" && !e.startsWith("./") && !e.startsWith("../"),
   );
   if (npmElements.length > 0) {
     result.html = injectNpmElementScripts(result.html, /** @type {string[]} */ (npmElements));
   }
 
   // Compile server handler if applicable (skip when provider bundles site-wide)
-  /** @type {string | null} */
-  let serverHandler = null;
+  let serverHandler: string | null = null;
   if (!projectConfig.build?.adapter) {
     try {
-      const serverResult = await compileServer(/** @type {string} */ (route.sourcePath));
+      const serverResult = await compileServer(route.sourcePath as string);
       if (serverResult) {
         serverHandler = serverResult;
       }
@@ -520,24 +533,22 @@ async function compilePage(
  * @param {Record<string, unknown>} scope
  * @returns {JxHeadEntry[]}
  */
-function resolveHeadTemplates(headEntries, scope) {
-  return headEntries.map((/** @type {JxHeadEntry} */ entry) => {
+function resolveHeadTemplates(headEntries: JxHeadEntry[], scope: Record<string, unknown>) {
+  return headEntries.map((entry: JxHeadEntry) => {
     if (!entry || typeof entry !== "object") return entry;
     const resolved = { ...entry };
     if (resolved.attributes) {
       resolved.attributes = { ...resolved.attributes };
       for (const [k, v] of Object.entries(resolved.attributes)) {
         if (typeof v === "string" && isTemplateString(v)) {
-          resolved.attributes[k] = /** @type {string | boolean} */ (
-            evaluateStaticTemplate(v, scope) ?? v
-          );
+          resolved.attributes[k] = evaluateStaticTemplate(v, scope) ?? (v as string | boolean);
         }
       }
     }
     if (typeof resolved.textContent === "string" && isTemplateString(resolved.textContent)) {
-      resolved.textContent = /** @type {string | undefined} */ (
-        evaluateStaticTemplate(resolved.textContent, scope) ?? resolved.textContent
-      );
+      resolved.textContent =
+        evaluateStaticTemplate(resolved.textContent, scope) ??
+        (resolved.textContent as string | undefined);
     }
     return resolved;
   });
@@ -551,8 +562,8 @@ function resolveHeadTemplates(headEntries, scope) {
  * @param {JxHeadEntry[]} headEntries
  * @returns {JxHeadEntry[]}
  */
-function resolveHeadBareSpecifiers(headEntries) {
-  return headEntries.map((/** @type {JxHeadEntry} */ entry) => {
+function resolveHeadBareSpecifiers(headEntries: JxHeadEntry[]) {
+  return headEntries.map((entry: JxHeadEntry) => {
     if (!entry || typeof entry !== "object" || !entry.attributes) return entry;
     const resolved = { ...entry, attributes: { ...entry.attributes } };
     for (const key of ["href", "src"]) {
@@ -571,7 +582,7 @@ function resolveHeadBareSpecifiers(headEntries) {
  * @param {string} s
  * @returns {boolean}
  */
-function isBareSpecifier(s) {
+function isBareSpecifier(s: string) {
   return (
     !s.startsWith("/") &&
     !s.startsWith("./") &&
@@ -588,9 +599,9 @@ function isBareSpecifier(s) {
  * @param {Record<string, unknown>} scope
  * @returns {JxMutableNode}
  */
-function expandMapTemplate(template, scope) {
+function expandMapTemplate(template: JxMutableNode, scope: Record<string, unknown>) {
   if (!template || typeof template !== "object") return template;
-  const node = /** @type {JxMutableNode} */ ({});
+  const node = {} as JxMutableNode;
   for (const [k, v] of Object.entries(template)) {
     if (k === "children" && Array.isArray(v)) {
       node.children = v.map((child) => {
@@ -598,19 +609,21 @@ function expandMapTemplate(template, scope) {
         return expandMapTemplate(/** @type {JxMutableNode} */ (child), scope);
       });
     } else if (k === "style" && v && typeof v === "object") {
-      node.style = { ...v };
-      for (const [sk, sv] of Object.entries(node.style)) {
+      const style = { ...v } as Record<string, unknown>;
+      for (const [sk, sv] of Object.entries(style)) {
         if (typeof sv === "string" && isTemplateString(sv)) {
-          node.style[sk] = evaluateMapTemplate(sv, scope) ?? sv;
+          style[sk] = evaluateMapTemplate(sv, scope) ?? sv;
         }
       }
+      node.style = style;
     } else if (k === "attributes" && v && typeof v === "object") {
-      node.attributes = { ...v };
-      for (const [ak, av] of Object.entries(node.attributes)) {
+      const attrs = { ...v } as Record<string, unknown>;
+      for (const [ak, av] of Object.entries(attrs)) {
         if (typeof av === "string" && isTemplateString(av)) {
-          node.attributes[ak] = evaluateMapTemplate(av, scope) ?? av;
+          attrs[ak] = evaluateMapTemplate(av, scope) ?? av;
         }
       }
+      node.attributes = attrs;
     } else if (typeof v === "string" && isTemplateString(v)) {
       node[k] = evaluateMapTemplate(v, scope) ?? v;
     } else {
@@ -628,10 +641,10 @@ function expandMapTemplate(template, scope) {
  * @param {Record<string, unknown>} scope
  * @returns {unknown}
  */
-function evaluateMapTemplate(str, scope) {
+function evaluateMapTemplate(str: string, scope: Record<string, unknown>) {
   try {
-    const item = /** @type {Record<string, unknown>} */ (scope.$map)?.item;
-    const index = /** @type {Record<string, unknown>} */ (scope.$map)?.index;
+    const item = (scope.$map as Record<string, unknown>)?.item;
+    const index = (scope.$map as Record<string, unknown>)?.index;
     const singleExprMatch = str.match(/^\$\{(.+)\}$/s);
     if (singleExprMatch) {
       const fn = new Function("state", "$map", "item", "index", `return (${singleExprMatch[1]})`);
@@ -651,7 +664,7 @@ function evaluateMapTemplate(str, scope) {
  * @param {JxElement | string} node
  * @param {Record<string, unknown>} scope
  */
-function resolveDocTemplates(node, scope) {
+function resolveDocTemplates(node: JxElement | string, scope: Record<string, unknown>) {
   if (!node || typeof node !== "object") return;
 
   if (typeof node.innerHTML === "string" && isTemplateString(node.innerHTML)) {
@@ -664,16 +677,13 @@ function resolveDocTemplates(node, scope) {
     }
   }
   if (typeof node.textContent === "string" && isTemplateString(node.textContent)) {
-    node.textContent = /** @type {string | null} */ (
-      evaluateStaticTemplate(node.textContent, scope) ?? node.textContent
-    );
+    node.textContent =
+      evaluateStaticTemplate(node.textContent, scope) ?? (node.textContent as string | null);
   }
   if (node.style && typeof node.style === "object") {
     for (const [k, v] of Object.entries(node.style)) {
       if (typeof v === "string" && isTemplateString(v)) {
-        node.style[k] = /** @type {string | number | JxStyle} */ (
-          evaluateStaticTemplate(v, scope) ?? v
-        );
+        node.style[k] = evaluateStaticTemplate(v, scope) ?? (v as string | number | JxStyle);
       }
     }
   }
@@ -684,18 +694,18 @@ function resolveDocTemplates(node, scope) {
       }
     }
   }
-  const rawChildren = /** @type {unknown} */ (node.children);
+  const rawChildren = node.children as unknown;
   if (
     rawChildren &&
     typeof rawChildren === "object" &&
     !Array.isArray(rawChildren) &&
-    /** @type {JxMutableNode} */ (rawChildren).$prototype === "Array"
+    (rawChildren as JxMutableNode).$prototype === "Array"
   ) {
-    const arrayDef = /** @type {JxMutableNode} */ (rawChildren);
+    const arrayDef = rawChildren as JxMutableNode;
     const itemsSrc = arrayDef.items;
     let items = null;
-    if (itemsSrc && typeof itemsSrc === "object" && /** @type {JxMutableNode} */ (itemsSrc).$ref) {
-      const ref = /** @type {string} */ (/** @type {JxMutableNode} */ (itemsSrc).$ref);
+    if (itemsSrc && typeof itemsSrc === "object" && (itemsSrc as JxMutableNode).$ref) {
+      const ref = (itemsSrc as JxMutableNode).$ref as string;
       items = resolveRefValue(ref, scope);
     } else if (Array.isArray(itemsSrc)) {
       items = itemsSrc;
@@ -707,16 +717,16 @@ function resolveDocTemplates(node, scope) {
         childScope["$map/item"] = item;
         childScope["$map/index"] = index;
         const expanded = expandMapTemplate(arrayDef.map, childScope);
-        resolveDocTemplates(expanded, childScope);
+        resolveDocTemplates(expanded as JxElement, childScope);
         return expanded;
-      });
+      }) as (string | JxElement)[];
       return;
     }
   }
   if (typeof rawChildren === "string" && isTemplateString(rawChildren)) {
     const resolved = evaluateStaticTemplate(rawChildren, scope);
     if (Array.isArray(resolved)) {
-      const resolvedNodes = /** @type {(JxElement | string)[]} */ (resolved);
+      const resolvedNodes = resolved as (JxElement | string)[];
       node.children = resolvedNodes;
       for (const child of resolvedNodes) {
         resolveDocTemplates(child, scope);
@@ -729,7 +739,7 @@ function resolveDocTemplates(node, scope) {
       if (typeof child === "string" && isTemplateString(child)) {
         const resolved = evaluateStaticTemplate(child, scope);
         if (Array.isArray(resolved)) {
-          const resolvedNodes = /** @type {(JxElement | string)[]} */ (resolved);
+          const resolvedNodes = resolved as (JxElement | string)[];
           node.children.splice(i, 1, ...resolvedNodes);
           for (const spliced of resolvedNodes) {
             resolveDocTemplates(spliced, scope);
@@ -751,7 +761,7 @@ function resolveDocTemplates(node, scope) {
  * @param {JxElement | string} node
  * @param {Map<string, JxElement>} componentDefs
  */
-function expandComponents(node, componentDefs) {
+function expandComponents(node: JxElement | string, componentDefs: Map<string, JxElement>) {
   if (!node || typeof node !== "object") return;
   if (Array.isArray(node)) {
     node.forEach((n) => expandComponents(n, componentDefs));
@@ -765,13 +775,11 @@ function expandComponents(node, componentDefs) {
     }
   }
 
-  const def = componentDefs.get(/** @type {string} */ (node.tagName));
+  const def = componentDefs.get(node.tagName as string);
   if (def) {
     const slotContent =
       Array.isArray(node.children) && node.children.length > 0
-        ? node.children
-            .map((/** @type {JxElement | string} */ c) => renderStaticNode(c, {}, null))
-            .join("\n")
+        ? node.children.map((c: JxElement | string) => renderStaticNode(c, {}, null)).join("\n")
         : null;
 
     const innerHTML = preRenderComponentHtml(def, node.$props || null, slotContent);
@@ -782,15 +790,13 @@ function expandComponents(node, componentDefs) {
 
     // Resolve template-string host styles with props (per-instance values like background-image)
     if (def.style && node.$props) {
-      /** @type {Record<string, JxStateDefinition>} */
-      let stateDefs = { ...def.state };
+      let stateDefs: Record<string, JxStateDefinition> = { ...def.state };
       for (const [key, value] of Object.entries(node.$props)) {
-        if (key in stateDefs) stateDefs[key] = /** @type {JxStateDefinition} */ (value);
-        else stateDefs[key] = /** @type {JxStateDefinition} */ (value);
+        if (key in stateDefs) stateDefs[key] = value as JxStateDefinition;
+        else stateDefs[key] = value as JxStateDefinition;
       }
       const scope = buildInitialScope(stateDefs, null);
-      /** @type {Record<string, unknown>} */
-      const resolvedStyle = {};
+      const resolvedStyle: Record<string, unknown> = {};
       for (const [prop, value] of Object.entries(def.style)) {
         if (typeof value === "string" && isTemplateString(value)) {
           const resolved = resolveStaticValue(value, scope);
@@ -798,7 +804,7 @@ function expandComponents(node, componentDefs) {
         }
       }
       if (Object.keys(resolvedStyle).length > 0) {
-        node.style = /** @type {JxStyle} */ ({ ...node.style, ...resolvedStyle });
+        node.style = { ...node.style, ...resolvedStyle } as JxStyle;
       }
     }
 
@@ -820,28 +826,28 @@ function expandComponents(node, componentDefs) {
  * @returns {string}
  */
 function injectComponentScripts(
-  html,
-  allComponentTags,
-  cssMap = new Map(),
-  staticTags = new Set(),
+  html: string,
+  allComponentTags: string[],
+  cssMap: Map<string, string> = new Map(),
+  staticTags: Set<string> = new Set(),
 ) {
   // Find which components are actually referenced in this page
   const usedTags = allComponentTags.filter(
-    (/** @type {string} */ tag) => html.includes(`<${tag}`), // matches <tag> and <tag ...>
+    (tag: string) => html.includes(`<${tag}`), // matches <tag> and <tag ...>
   );
   if (usedTags.length === 0) return html;
 
   // Inject CSS links in <head> for ALL components that have CSS sidecars
   const cssLinks = usedTags
-    .filter((/** @type {string} */ tag) => cssMap.has(tag))
-    .map((/** @type {string} */ tag) => `<link rel="stylesheet" href="/components/${tag}.css">`)
+    .filter((tag: string) => cssMap.has(tag))
+    .map((tag: string) => `<link rel="stylesheet" href="/components/${tag}.css">`)
     .join("\n  ");
   if (cssLinks) {
     html = html.replace("</head>", `  ${cssLinks}\n</head>`);
   }
 
   // Only inject JS for components that have non-static instances
-  const jsTags = usedTags.filter((/** @type {string} */ tag) => !staticTags.has(tag));
+  const jsTags = usedTags.filter((tag: string) => !staticTags.has(tag));
   if (jsTags.length === 0) return html;
 
   // Build import map (needed for @vue/reactivity and lit-html)
@@ -855,9 +861,7 @@ function injectComponentScripts(
   </script>`;
 
   const moduleScripts = jsTags
-    .map(
-      (/** @type {string} */ tag) => `<script type="module" src="/components/${tag}.js"></script>`,
-    )
+    .map((tag: string) => `<script type="module" src="/components/${tag}.js"></script>`)
     .join("\n  ");
 
   // Check if an import map already exists (from islands etc.)
@@ -876,11 +880,9 @@ function injectComponentScripts(
  *   "@shoelace-style/shoelace/components/button/button.js"
  * @returns {string}
  */
-function injectNpmElementScripts(html, npmElements) {
+function injectNpmElementScripts(html: string, npmElements: string[]) {
   const scripts = npmElements
-    .map(
-      (/** @type {string} */ spec) => `<script type="module" src="/node_modules/${spec}"></script>`,
-    )
+    .map((spec: string) => `<script type="module" src="/node_modules/${spec}"></script>`)
     .join("\n  ");
 
   return html.replace("</body>", `  ${scripts}\n</body>`);
@@ -894,7 +896,7 @@ function injectNpmElementScripts(html, npmElements) {
  * @param {string} lang
  * @returns {string}
  */
-function injectHead(html, headEntries, lang) {
+function injectHead(html: string, headEntries: JxHeadEntry[], lang: string) {
   const headHtml = renderHead(headEntries);
 
   // Replace the existing <head>...</head> block, preserving compiler-generated <style> and <script> blocks
@@ -912,7 +914,7 @@ function injectHead(html, headEntries, lang) {
   }
 
   // Set the lang attribute on <html>
-  html = html.replace(/<html\s[^>]*>/i, (/** @type {string} */ match) => {
+  html = html.replace(/<html\s[^>]*>/i, (match: string) => {
     if (/lang=/.test(match)) {
       return match.replace(/lang="[^"]*"/, `lang="${lang}"`);
     }
@@ -933,7 +935,7 @@ function injectHead(html, headEntries, lang) {
  * @param {string} trailingSlash
  * @returns {string}
  */
-function routeToOutputPath(urlPattern, outDir, trailingSlash) {
+function routeToOutputPath(urlPattern: string, outDir: string, trailingSlash: string) {
   if (urlPattern === "/") {
     return join(outDir, "index.html");
   }
@@ -956,10 +958,12 @@ function routeToOutputPath(urlPattern, outDir, trailingSlash) {
  * @param {string} outDir
  * @returns {number} Number of files written
  */
-function generateRedirects(redirects, outDir) {
+function generateRedirects(
+  redirects: Record<string, string | { destination: string; status?: number }>,
+  outDir: string,
+) {
   let count = 0;
-  /** @type {string[]} */
-  const redirectLines = [];
+  const redirectLines: string[] = [];
 
   for (const [source, target] of Object.entries(redirects)) {
     const dest = typeof target === "object" ? target.destination : target;
@@ -1004,7 +1008,7 @@ function generateRedirects(redirects, outDir) {
  * @param {string} str
  * @returns {string}
  */
-function escapeHtml(str) {
+function escapeHtml(str: string) {
   return String(str).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
@@ -1012,6 +1016,6 @@ function escapeHtml(str) {
  * @param {string} str
  * @returns {string}
  */
-function escapeAttr(str) {
+function escapeAttr(str: string) {
   return String(str).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }

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

@@ -50,7 +50,7 @@ const DEFAULTS = {
  * @returns {{ config: Record<string, any>; configPath: string; projectRoot: string }}
  * @throws {Error} If project.json is missing or invalid JSON
  */
-export function loadProjectConfig(projectRoot) {
+export function loadProjectConfig(projectRoot: string) {
   const configPath = resolve(projectRoot, "project.json");
 
   if (!existsSync(configPath)) {
@@ -61,7 +61,7 @@ export function loadProjectConfig(projectRoot) {
   try {
     raw = JSON.parse(readFileSync(configPath, "utf8"));
   } catch (e) {
-    const err = /** @type {Error} */ (e);
+    const err = e as Error;
     throw new Error(`Invalid JSON in ${configPath}: ${err.message}`);
   }