@jxsuite/compiler 0.19.0 → 0.21.0

package/src/site/layout-resolver.js

@@ -19,14 +19,17 @@ import { resolve } from "node:path";
 /**
  * Resolve a page's layout, wrapping the page content in the layout structure.
  *
- * @param {any} pageDoc - The raw page JSON document
- * @param {any} projectConfig - Site configuration (for defaults.layout)
+ * @param {JxDocument} pageDoc - The raw page JSON document
+ * @param {Record<string, unknown>} projectConfig - Site configuration (for defaults.layout)
  * @param {string} projectRoot - Project root directory
- * @returns {any} The merged document (layout wrapping page content)
+ * @returns {JxDocument} The merged document (layout wrapping page content)
  */
 export function resolveLayout(pageDoc, projectConfig, projectRoot) {
   // Determine which layout to use
-  const layoutRef = pageDoc.$layout ?? projectConfig.defaults?.layout ?? null;
+  const layoutRef =
+    pageDoc.$layout ??
+    /** @type {Record<string, unknown>} */ (projectConfig.defaults)?.layout ??
+    null;
 
   if (!layoutRef) {
     // No layout — return page as-is
@@ -34,17 +37,17 @@ export function resolveLayout(pageDoc, projectConfig, projectRoot) {
   }
 
   // Load the layout file
-  const layoutPath = resolve(projectRoot, layoutRef);
+  const layoutPath = resolve(projectRoot, /** @type {string} */ (layoutRef));
   if (!existsSync(layoutPath)) {
     throw new Error(`Layout not found: ${layoutRef} (resolved to ${layoutPath})`);
   }
 
-  /** @type {any} */
+  /** @type {JxDocument} */
   let layoutDoc;
   try {
     layoutDoc = JSON.parse(readFileSync(layoutPath, "utf8"));
   } catch (e) {
-    const err = /** @type {any} */ (e);
+    const err = /** @type {Error} */ (e);
     throw new Error(`Invalid layout JSON at ${layoutPath}: ${err.message}`);
   }
 
@@ -55,7 +58,9 @@ export function resolveLayout(pageDoc, projectConfig, projectRoot) {
 
   // Distribute page children into layout slots
   const rawChildren = pageDoc.children ?? [];
-  const pageChildren = typeof rawChildren === "string" ? [rawChildren] : rawChildren;
+  const pageChildren = /** @type {(JxElement | string)[]} */ (
+    typeof rawChildren === "string" ? [rawChildren] : Array.isArray(rawChildren) ? rawChildren : []
+  );
   const merged = deepClone(layoutDoc);
 
   distributeSlots(merged, pageChildren);
@@ -102,24 +107,24 @@ export function resolveLayout(pageDoc, projectConfig, projectRoot) {
  * 3. Remaining children go into the default (unnamed) slot
  * 4. Replace each <slot> element with its distributed children
  *
- * @param {any} node - Layout document tree (mutated in place)
- * @param {any[]} children - Page children to distribute
+ * @param {JxElement} node - Layout document tree (mutated in place)
+ * @param {(JxElement | string)[]} children - Page children to distribute
  */
 function distributeSlots(node, children) {
   if (!node || typeof node !== "object") return;
   if (!Array.isArray(node.children)) return;
 
   // Collect named and default children
-  /** @type {Map<string, any[]>} */
+  /** @type {Map<string, (JxElement | string)[]>} */
   const named = new Map(); // slot name → children[]
-  /** @type {any[]} */
+  /** @type {(JxElement | string)[]} */
   const defaults = []; // children without a slot target
 
   for (const child of children) {
     if (child && typeof child === "object" && child.attributes?.slot) {
-      const slotName = child.attributes.slot;
+      const slotName = /** @type {string} */ (child.attributes.slot);
       if (!named.has(slotName)) named.set(slotName, []);
-      /** @type {any[]} */ (named.get(slotName)).push(child);
+      /** @type {(JxElement | string)[]} */ (named.get(slotName)).push(child);
     } else {
       defaults.push(child);
     }
@@ -132,25 +137,27 @@ function distributeSlots(node, children) {
 /**
  * Recursively walk the tree and replace <slot> elements with distributed content.
  *
- * @param {any} node
- * @param {Map<string, any[]>} named
- * @param {any[]} defaults
+ * @param {JxElement} node
+ * @param {Map<string, (JxElement | string)[]>} named
+ * @param {(JxElement | string)[]} defaults
  */
 function fillSlots(node, named, defaults) {
   if (!node || typeof node !== "object") return;
   if (!Array.isArray(node.children)) return;
 
-  /** @type {any[]} */
+  /** @type {(JxElement | string)[]} */
   const newChildren = [];
 
   for (const child of node.children) {
     if (child && typeof child === "object" && child.tagName === "slot") {
       const slotName = child.attributes?.name;
 
-      if (slotName && named.has(slotName)) {
+      if (slotName && named.has(/** @type {string} */ (slotName))) {
         // Named slot — replace with matching children
-        newChildren.push(.../** @type {any[]} */ (named.get(slotName)));
-        named.delete(slotName); // consumed
+        newChildren.push(
+          .../** @type {(JxElement | string)[]} */ (named.get(/** @type {string} */ (slotName))),
+        );
+        named.delete(/** @type {string} */ (slotName)); // consumed
       } else if (!slotName && defaults.length > 0) {
         // Default slot — replace with unassigned children
         newChildren.push(...defaults);
@@ -158,13 +165,13 @@ function fillSlots(node, named, defaults) {
         // but if there are multiple, the first one wins
       } else {
         // No matching content — keep slot's fallback children
-        if (child.children) {
+        if (Array.isArray(child.children)) {
           newChildren.push(...child.children);
         }
       }
     } else {
       // Not a slot — recurse into it
-      fillSlots(child, named, defaults);
+      fillSlots(/** @type {JxElement} */ (child), named, defaults);
       newChildren.push(child);
     }
   }
@@ -175,8 +182,8 @@ function fillSlots(node, named, defaults) {
 /**
  * Deep clone a JSON-serializable object.
  *
- * @param {any} obj
- * @returns {any}
+ * @param {JxDocument} obj
+ * @returns {JxDocument}
  */
 function deepClone(obj) {
   return JSON.parse(JSON.stringify(obj));

package/src/site/pages-discovery.js

@@ -183,7 +183,7 @@ export async function expandDynamicRoutes(routes, projectRoot, contentTypes = ne
     }
 
     // Read the page to look for $paths
-    /** @type {any} */
+    /** @type {Record<string, unknown>} */
     let raw;
     try {
       raw = JSON.parse(readFileSync(route.sourcePath, "utf8"));
@@ -245,7 +245,7 @@ function resolvePathEntries($paths, projectRoot, contentTypes) {
     }
     const param = $paths.param ?? "slug";
     const field = $paths.field ?? "id";
-    return entries.map((/** @type {any} */ entry) => ({
+    return entries.map((/** @type {ContentLoaderEntry} */ entry) => ({
       [param]: field === "id" ? entry.id : (entry.data[field] ?? entry.id),
     }));
   }
@@ -253,18 +253,18 @@ function resolvePathEntries($paths, projectRoot, contentTypes) {
   // Explicit values: { values: ["en", "fr"], param: "lang" }
   if (Array.isArray($paths.values)) {
     const param = $paths.param ?? "value";
-    return $paths.values.map((/** @type {any} */ v) => ({ [param]: v }));
+    return $paths.values.map((/** @type {string} */ v) => ({ [param]: v }));
   }
 
   // Data file ref: { "$ref": "./data/products.json", param: "id", field: "sku" }
   if ($paths.$ref) {
     const filePath = resolve(projectRoot, $paths.$ref);
-    /** @type {any} */
+    /** @type {Record<string, unknown>[]} */
     let data;
     try {
       data = JSON.parse(readFileSync(filePath, "utf8"));
     } catch (e) {
-      const err = /** @type {any} */ (e);
+      const err = /** @type {Error} */ (e);
       console.warn(`Warning: $paths.$ref could not load "${$paths.$ref}": ${err.message}`);
       return [];
     }
@@ -274,7 +274,7 @@ function resolvePathEntries($paths, projectRoot, contentTypes) {
     }
     const param = $paths.param ?? "id";
     const field = $paths.field ?? "id";
-    return data.map((/** @type {any} */ item) => ({
+    return data.map((/** @type {Record<string, unknown>} */ item) => ({
       [param]: item[field] ?? item.id ?? String(item),
     }));
   }

package/src/site/prototype-resolver.js

@@ -65,7 +65,7 @@ const RESERVED_KEYS = new Set([
  * - Instantiates the class with the config - Calls .resolve() and replaces the state entry with the
  * result
  *
- * @param {any} doc - The page document (mutated in place)
+ * @param {JxMutableNode | JxDocument} doc - The page document (mutated in place)
  * @param {{ sourcePath?: string }} route - Route info (sourcePath = absolute path to page .json)
  * @param {string} projectRoot - Absolute path to the project root
  */

package/src/site/site-build.js

@@ -121,7 +121,7 @@ export async function buildSite(projectRoot, options = {}) {
   const compiledComponentTags = [];
   /** @type {Map<string, string>} */
   const componentCSS = new Map(); // tagName → CSS text
-  /** @type {Map<string, any>} */
+  /** @type {Map<string, JxElement>} */
   const componentDefs = new Map(); // tagName → parsed component definition
   if (existsSync(componentsDir)) {
     log("Compiling components...");
@@ -160,7 +160,7 @@ export async function buildSite(projectRoot, options = {}) {
           }
         }
       } catch (e) {
-        const err = /** @type {any} */ (e);
+        const err = /** @type {Error} */ (e);
         errors.push(`Error compiling component ${file}: ${err.message}`);
         console.error(`Error compiling component ${file}: ${err.message}`);
       }
@@ -232,7 +232,7 @@ export async function buildSite(projectRoot, options = {}) {
           fileCount++;
         }
       } catch (e) {
-        const err = /** @type {any} */ (e);
+        const err = /** @type {Error} */ (e);
         errors.push(`Error exporting markdown for ${route.urlPattern}: ${err.message}`);
       }
 
@@ -251,7 +251,7 @@ export async function buildSite(projectRoot, options = {}) {
         fileCount++;
       }
     } catch (e) {
-      const err = /** @type {any} */ (e);
+      const err = /** @type {Error} */ (e);
       const msg = `Error compiling ${route.urlPattern}: ${err.message}`;
       errors.push(msg);
       console.error(msg);
@@ -361,13 +361,19 @@ export async function buildSite(projectRoot, options = {}) {
  *
  * Pipeline: load JSON → resolve layout → inject context → merge head → compile
  *
- * @param {any} route
- * @param {any} projectConfig
+ * @param {SiteRoute} route
+ * @param {ProjectConfig} projectConfig
  * @param {string} projectRoot
- * @param {Map<string, any[]>} [contentTypes]
+ * @param {Map<string, ContentLoaderEntry[]>} [contentTypes]
  * @param {import("./image-cache.js").CacheManifest | null} [imageCache]
  * @param {string} [outDir]
- * @returns {Promise<{ html: string; files: any[]; serverHandler: string | null; doc: any }>}
+ * @param {Map<string, JxElement>} [componentDefs]
+ * @returns {Promise<{
+ *   html: string;
+ *   files: { path: string; content: string; tagName?: string }[];
+ *   serverHandler: string | null;
+ *   doc: JxDocument;
+ * }>}
  */
 async function compilePage(
   route,
@@ -380,20 +386,20 @@ async function compilePage(
 ) {
   // Load the raw page document
   let pageDoc;
-  if (route.sourcePath.endsWith(".md")) {
+  if (/** @type {string} */ (route.sourcePath).endsWith(".md")) {
     const { transpileJxMarkdown } = await import("@jxsuite/parser/transpile");
-    pageDoc = transpileJxMarkdown(readFileSync(route.sourcePath, "utf8"));
+    pageDoc = transpileJxMarkdown(readFileSync(/** @type {string} */ (route.sourcePath), "utf8"));
   } else {
-    pageDoc = JSON.parse(readFileSync(route.sourcePath, "utf8"));
+    pageDoc = JSON.parse(readFileSync(/** @type {string} */ (route.sourcePath), "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 = pageDoc.$head ?? layoutDoc._pageHead ?? [];
+  const pageHead = /** @type {JxHeadEntry[]} */ (pageDoc.$head ?? layoutDoc._pageHead ?? []);
   const layoutHead = layoutDoc.$head ?? [];
-  const pageTitle = pageDoc.title ?? layoutDoc._pageTitle ?? null;
+  const pageTitle = /** @type {string | null} */ (pageDoc.title ?? layoutDoc._pageTitle ?? null);
 
   // Clean up internal properties
   delete layoutDoc._pageHead;
@@ -411,7 +417,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 = evaluateStaticTemplate(title, scope) ?? title;
+    title = /** @type {string} */ (evaluateStaticTemplate(title, scope) ?? title);
   }
 
   // Resolve template strings in $head entries
@@ -434,7 +440,7 @@ async function compilePage(
         def &&
         typeof def === "object" &&
         !Array.isArray(def) &&
-        /** @type {any} */ (def).timing === "compiler"
+        /** @type {JxMutableNode} */ (def).timing === "compiler"
       ) {
         delete layoutDoc.state[key];
       }
@@ -475,18 +481,19 @@ async function compilePage(
 
   // Inject <script type="module"> for npm $elements (cherry-picked component imports)
   const npmElements = (layoutDoc.$elements ?? []).filter(
-    (/** @type {any} */ e) => typeof e === "string" && !e.startsWith("./") && !e.startsWith("../"),
+    (/** @type {JxElement | string} */ e) =>
+      typeof e === "string" && !e.startsWith("./") && !e.startsWith("../"),
   );
   if (npmElements.length > 0) {
-    result.html = injectNpmElementScripts(result.html, npmElements);
+    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;
-  if (!projectConfig.build.adapter) {
+  if (!projectConfig.build?.adapter) {
     try {
-      const serverResult = await compileServer(route.sourcePath);
+      const serverResult = await compileServer(/** @type {string} */ (route.sourcePath));
       if (serverResult) {
         serverHandler = serverResult;
       }
@@ -501,25 +508,28 @@ async function compilePage(
 /**
  * Resolve template strings in $head entries against the compiled scope.
  *
- * @param {any[]} headEntries
- * @param {any} scope
- * @returns {any[]}
+ * @param {JxHeadEntry[]} headEntries
+ * @param {Record<string, unknown>} scope
+ * @returns {JxHeadEntry[]}
  */
 function resolveHeadTemplates(headEntries, scope) {
-  return headEntries.map((/** @type {any} */ entry) => {
+  return headEntries.map((/** @type {JxHeadEntry} */ entry) => {
     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] = evaluateStaticTemplate(v, scope) ?? v;
+          resolved.attributes[k] = /** @type {string | boolean} */ (
+            evaluateStaticTemplate(v, scope) ?? v
+          );
         }
       }
     }
     if (typeof resolved.textContent === "string" && isTemplateString(resolved.textContent)) {
-      resolved.textContent =
-        evaluateStaticTemplate(resolved.textContent, scope) ?? resolved.textContent;
+      resolved.textContent = /** @type {string | undefined} */ (
+        evaluateStaticTemplate(resolved.textContent, scope) ?? resolved.textContent
+      );
     }
     return resolved;
   });
@@ -530,11 +540,11 @@ function resolveHeadTemplates(headEntries, scope) {
  * "@shoelace-style/shoelace/dist/themes/light.css" →
  * "/node_modules/@shoelace-style/shoelace/dist/themes/light.css"
  *
- * @param {any[]} headEntries
- * @returns {any[]}
+ * @param {JxHeadEntry[]} headEntries
+ * @returns {JxHeadEntry[]}
  */
 function resolveHeadBareSpecifiers(headEntries) {
-  return headEntries.map((/** @type {any} */ entry) => {
+  return headEntries.map((/** @type {JxHeadEntry} */ entry) => {
     if (!entry || typeof entry !== "object" || !entry.attributes) return entry;
     const resolved = { ...entry, attributes: { ...entry.attributes } };
     for (const key of ["href", "src"]) {
@@ -567,8 +577,8 @@ function isBareSpecifier(s) {
  * Recursively resolve template strings in a document tree against a scope. Mutates the document in
  * place — evaluates ${...} in innerHTML, textContent, style values, and attribute values.
  *
- * @param {any} node
- * @param {any} scope
+ * @param {JxElement | string} node
+ * @param {Record<string, unknown>} scope
  */
 function resolveDocTemplates(node, scope) {
   if (!node || typeof node !== "object") return;
@@ -579,16 +589,20 @@ function resolveDocTemplates(node, scope) {
       // Encode any remaining `${` as HTML entities so the compile phase won't
       // re-interpret them as template expressions. After resolution, any `${` in the
       // result is literal content (e.g., code examples), not an intentional template.
-      node.innerHTML = resolved.replaceAll("${", "&#36;{");
+      node.innerHTML = String(resolved).replaceAll("${", "&#36;{");
     }
   }
   if (typeof node.textContent === "string" && isTemplateString(node.textContent)) {
-    node.textContent = evaluateStaticTemplate(node.textContent, scope) ?? node.textContent;
+    node.textContent = /** @type {string | null} */ (
+      evaluateStaticTemplate(node.textContent, scope) ?? node.textContent
+    );
   }
   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] = evaluateStaticTemplate(v, scope) ?? v;
+        node.style[k] = /** @type {string | number | JxStyle} */ (
+          evaluateStaticTemplate(v, scope) ?? v
+        );
       }
     }
   }
@@ -599,11 +613,13 @@ function resolveDocTemplates(node, scope) {
       }
     }
   }
-  if (typeof node.children === "string" && isTemplateString(node.children)) {
-    const resolved = evaluateStaticTemplate(node.children, scope);
+  const rawChildren = /** @type {unknown} */ (node.children);
+  if (typeof rawChildren === "string" && isTemplateString(rawChildren)) {
+    const resolved = evaluateStaticTemplate(rawChildren, scope);
     if (Array.isArray(resolved)) {
-      node.children = resolved;
-      for (const child of node.children) {
+      const resolvedNodes = /** @type {(JxElement | string)[]} */ (resolved);
+      node.children = resolvedNodes;
+      for (const child of resolvedNodes) {
         resolveDocTemplates(child, scope);
       }
     }
@@ -614,11 +630,12 @@ function resolveDocTemplates(node, scope) {
       if (typeof child === "string" && isTemplateString(child)) {
         const resolved = evaluateStaticTemplate(child, scope);
         if (Array.isArray(resolved)) {
-          node.children.splice(i, 1, ...resolved);
-          for (const spliced of resolved) {
+          const resolvedNodes = /** @type {(JxElement | string)[]} */ (resolved);
+          node.children.splice(i, 1, ...resolvedNodes);
+          for (const spliced of resolvedNodes) {
             resolveDocTemplates(spliced, scope);
           }
-          i += resolved.length;
+          i += resolvedNodes.length;
           continue;
         }
       }
@@ -632,8 +649,8 @@ function resolveDocTemplates(node, scope) {
  * Walk the document tree and expand registered custom elements in-place. Applies $props via
  * preRenderComponentHtml, marks static/prerendered.
  *
- * @param {any} node
- * @param {Map<string, any>} componentDefs
+ * @param {JxElement | string} node
+ * @param {Map<string, JxElement>} componentDefs
  */
 function expandComponents(node, componentDefs) {
   if (!node || typeof node !== "object") return;
@@ -649,11 +666,13 @@ function expandComponents(node, componentDefs) {
     }
   }
 
-  const def = componentDefs.get(node.tagName);
+  const def = componentDefs.get(/** @type {string} */ (node.tagName));
   if (def) {
     const slotContent =
       Array.isArray(node.children) && node.children.length > 0
-        ? node.children.map((/** @type {any} */ c) => renderStaticNode(c, {}, null)).join("\n")
+        ? node.children
+            .map((/** @type {JxElement | string} */ c) => renderStaticNode(c, {}, null))
+            .join("\n")
         : null;
 
     const innerHTML = preRenderComponentHtml(def, node.$props || null, slotContent);
@@ -664,13 +683,14 @@ 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 };
       for (const [key, value] of Object.entries(node.$props)) {
-        if (key in stateDefs) stateDefs[key] = value;
-        else stateDefs[key] = value;
+        if (key in stateDefs) stateDefs[key] = /** @type {JxStateDefinition} */ (value);
+        else stateDefs[key] = /** @type {JxStateDefinition} */ (value);
       }
       const scope = buildInitialScope(stateDefs, null);
-      /** @type {Record<string, any>} */
+      /** @type {Record<string, unknown>} */
       const resolvedStyle = {};
       for (const [prop, value] of Object.entries(def.style)) {
         if (typeof value === "string" && isTemplateString(value)) {
@@ -679,7 +699,7 @@ function expandComponents(node, componentDefs) {
         }
       }
       if (Object.keys(resolvedStyle).length > 0) {
-        node.style = { ...node.style, ...resolvedStyle };
+        node.style = /** @type {JxStyle} */ ({ ...node.style, ...resolvedStyle });
       }
     }
 
@@ -771,7 +791,7 @@ function injectNpmElementScripts(html, npmElements) {
  * Replaces the compiler's default <head> section with our merged version.
  *
  * @param {string} html
- * @param {any[]} headEntries
+ * @param {JxHeadEntry[]} headEntries
  * @param {string} lang
  * @returns {string}
  */
@@ -833,7 +853,7 @@ function routeToOutputPath(urlPattern, outDir, trailingSlash) {
 /**
  * Generate redirect files (HTML meta refresh and _redirects).
  *
- * @param {Record<string, any>} redirects
+ * @param {Record<string, string | { destination: string; status?: number }>} redirects
  * @param {string} outDir
  * @returns {number} Number of files written
  */

package/src/site/site-loader.js

@@ -61,7 +61,7 @@ export function loadProjectConfig(projectRoot) {
   try {
     raw = JSON.parse(readFileSync(configPath, "utf8"));
   } catch (e) {
-    const err = /** @type {any} */ (e);
+    const err = /** @type {Error} */ (e);
     throw new Error(`Invalid JSON in ${configPath}: ${err.message}`);
   }
 

package/src/targets/compile-class.js

@@ -8,8 +8,8 @@
 /**
  * Compile a .class.json schema to a JavaScript ES module string.
  *
- * @param {any} classDef - Parsed .class.json content (must have $prototype: "Class")
- * @param {any} [_opts]
+ * @param {JxMutableNode} classDef - Parsed .class.json content (must have $prototype: "Class")
+ * @param {Record<string, unknown>} [_opts]
  * @returns {string} JavaScript module source code
  */
 export function compileClassJson(classDef, _opts = {}) {
@@ -17,9 +17,10 @@ export function compileClassJson(classDef, _opts = {}) {
   if (!className) throw new Error("compileClassJson: missing title (class name)");
 
   const baseClass = resolveBaseClass(classDef.extends);
-  const fields = classDef.$defs?.fields ?? {};
-  const ctor = classDef.$defs?.constructor;
-  const methods = classDef.$defs?.methods ?? {};
+  const defs = /** @type {Record<string, unknown> | undefined} */ (classDef.$defs);
+  const fields = /** @type {Record<string, JxMutableNode>} */ (defs?.fields ?? {});
+  const ctor = /** @type {JxMutableNode | undefined} */ (defs?.constructor);
+  const methods = /** @type {Record<string, JxMutableNode>} */ (defs?.methods ?? {});
 
   /** @type {string[]} */
   const lines = [];
@@ -33,7 +34,7 @@ export function compileClassJson(classDef, _opts = {}) {
 
   // Static fields
   for (const [key, field] of Object.entries(fields)) {
-    const f = /** @type {any} */ (field);
+    const f = /** @type {JxMutableNode} */ (field);
     if (f.scope !== "static") continue;
     const name = f.identifier ?? key;
     const prefix = f.access === "private" ? "#" : "";
@@ -48,7 +49,7 @@ export function compileClassJson(classDef, _opts = {}) {
 
   // Instance field declarations (private)
   for (const [key, field] of Object.entries(fields)) {
-    const f = /** @type {any} */ (field);
+    const f = /** @type {JxMutableNode} */ (field);
     if (f.scope === "static") continue;
     if (f.access !== "private") continue;
     const name = f.identifier ?? key;
@@ -66,7 +67,7 @@ export function compileClassJson(classDef, _opts = {}) {
 
   // Initialize instance fields from config or defaults
   for (const [key, field] of Object.entries(fields)) {
-    const f = /** @type {any} */ (field);
+    const f = /** @type {JxMutableNode} */ (field);
     if (f.scope === "static") continue;
     const name = f.identifier ?? key;
     const prefix = f.access === "private" ? "#" : "";
@@ -92,13 +93,17 @@ export function compileClassJson(classDef, _opts = {}) {
 
   // Methods
   for (const [key, method] of Object.entries(methods)) {
-    const m = /** @type {any} */ (method);
+    const m = /** @type {JxMutableNode} */ (method);
     const name = m.identifier ?? key;
     const isStatic = m.scope === "static";
     const isPrivate = m.access === "private";
     const prefix = isPrivate ? "#" : "";
     const staticPrefix = isStatic ? "static " : "";
-    const asyncPrefix = m.returnType?.$ref?.includes("Promise") || isMethodAsync(m) ? "async " : "";
+    const asyncPrefix =
+      m.returnType?.$ref?.includes("Promise") ||
+      isMethodAsync(/** @type {{ body?: string | string[] }} */ (/** @type {unknown} */ (m)))
+        ? "async "
+        : "";
 
     const params = resolveParams(m.parameters ?? []);
     const bodyStr = resolveBody(m.body);
@@ -140,15 +145,15 @@ export function compileClassJson(classDef, _opts = {}) {
 /**
  * Resolve the base class name from an extends value.
  *
- * @param {any} ext
+ * @param {unknown} ext
  * @returns {string}
  */
 function resolveBaseClass(ext) {
   if (!ext) return "Object";
   if (typeof ext === "string") return ext;
-  // { $ref: "./Parent.class.json" } — extract title from filename as best guess
-  if (ext.$ref) {
-    const ref = ext.$ref;
+  const e = /** @type {JxMutableNode} */ (ext);
+  if (e.$ref) {
+    const ref = e.$ref;
     const match = ref.match(/([A-Za-z0-9_]+)\.class\.json/);
     return match ? match[1] : "Object";
   }
@@ -158,14 +163,15 @@ function resolveBaseClass(ext) {
 /**
  * Resolve parameter names from $ref or inline definitions.
  *
- * @param {any[]} params
+ * @param {unknown[]} params
  * @returns {string}
  */
 function resolveParams(params) {
   return params
-    .map((/** @type {any} */ p) => {
-      if (p.$ref) return p.$ref.split("/").pop();
-      return p.identifier ?? p.name ?? "arg";
+    .map((p) => {
+      const param = /** @type {JxMutableNode} */ (p);
+      if (param.$ref) return param.$ref.split("/").pop();
+      return param.identifier ?? param.name ?? "arg";
     })
     .join(", ");
 }
@@ -173,19 +179,19 @@ function resolveParams(params) {
 /**
  * Resolve body from string or array of strings.
  *
- * @param {any} body
+ * @param {unknown} body
  * @returns {string[]}
  */
 function resolveBody(body) {
   if (!body) return [""];
   if (Array.isArray(body)) return body;
-  return [body];
+  return [/** @type {string} */ (body)];
 }
 
 /**
  * Simple heuristic: does the method body contain await?
  *
- * @param {any} method
+ * @param {{ body?: string | string[] }} method
  * @returns {boolean}
  */
 function isMethodAsync(method) {