@jxsuite/compiler 0.23.2 → 0.25.0

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

@@ -8,16 +8,14 @@
 
 import { existsSync } from "node:fs";
 import { resolve, extname, basename } from "node:path";
-import { processImage, buildSrcset, contentHash, configHash } from "./image-optimizer.js";
-import { getCached, setCached } from "./image-cache.js";
+import { processImage, buildSrcset, contentHash, configHash } from "./image-optimizer.ts";
+import { getCached, setCached } from "./image-cache.ts";
 
-/**
- * @typedef {import("./image-optimizer.js").ImageConfig} ImageConfig
- *
- * @typedef {import("./image-optimizer.js").ImageManifest} ImageManifest
- *
- * @typedef {import("./image-cache.js").CacheManifest} CacheManifest
- */
+import type { ImageConfig } from "./image-optimizer.ts";
+import type { ImageManifest } from "./image-optimizer.ts";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { CacheManifest } from "./image-cache.ts";
+import type { JxDocument } from "@jxsuite/schema/types";
 
 const SKIP_EXTENSIONS = new Set([".svg", ".gif"]);
 const EXTERNAL_PREFIXES = ["http://", "https://", "data:", "//"];
@@ -30,7 +28,13 @@ const EXTERNAL_PREFIXES = ["http://", "https://", "data:", "//"];
  * @param {CacheManifest} cache
  * @returns {Promise<ImageManifest>}
  */
-async function resolveManifest(absoluteSrc, src, config, outDir, cache) {
+async function resolveManifest(
+  absoluteSrc: string,
+  src: string,
+  config: ImageConfig,
+  outDir: string,
+  cache: CacheManifest,
+) {
   const key = `${contentHash(absoluteSrc)}:${configHash(config)}`;
   const cached = getCached(cache, key);
 
@@ -51,7 +55,7 @@ async function resolveManifest(absoluteSrc, src, config, outDir, cache) {
  * @param {string} src
  * @returns {boolean}
  */
-function shouldSkip(src) {
+function shouldSkip(src: string) {
   if (typeof src !== "string") return true;
   if (src.includes("${")) return true;
   if (EXTERNAL_PREFIXES.some((p) => src.startsWith(p))) return true;
@@ -68,7 +72,7 @@ function shouldSkip(src) {
  * @param {string} projectRoot
  * @returns {string}
  */
-function resolveImagePath(src, projectRoot) {
+function resolveImagePath(src: string, projectRoot: string) {
   if (src.startsWith("/")) {
     return resolve(projectRoot, "public", src.slice(1));
   }
@@ -88,9 +92,14 @@ function resolveImagePath(src, projectRoot) {
  * @param {CacheManifest} cache
  * @returns {Promise<{ imageRefs: Map<string, ImageManifest> }>}
  */
-export async function transformImageNodes(doc, config, projectRoot, outDir, cache) {
-  /** @type {Map<string, ImageManifest>} */
-  const imageRefs = new Map();
+export async function transformImageNodes(
+  doc: JxMutableNode | JxDocument,
+  config: ImageConfig,
+  projectRoot: string,
+  outDir: string,
+  cache: CacheManifest,
+) {
+  const imageRefs: Map<string, ImageManifest> = new Map();
 
   if (!config.optimize) return { imageRefs };
 
@@ -107,7 +116,14 @@ export async function transformImageNodes(doc, config, projectRoot, outDir, cach
  * @param {CacheManifest} cache
  * @param {Map<string, ImageManifest>} imageRefs
  */
-async function walkAndTransform(node, config, projectRoot, outDir, cache, imageRefs) {
+async function walkAndTransform(
+  node: JxMutableNode | JxDocument,
+  config: ImageConfig,
+  projectRoot: string,
+  outDir: string,
+  cache: CacheManifest,
+  imageRefs: Map<string, ImageManifest>,
+) {
   if (!node || typeof node !== "object") return;
 
   if (node.tagName === "img") {
@@ -141,7 +157,14 @@ async function walkAndTransform(node, config, projectRoot, outDir, cache, imageR
  * @param {CacheManifest} cache
  * @param {Map<string, ImageManifest>} imageRefs
  */
-async function transformImgNode(node, config, projectRoot, outDir, cache, imageRefs) {
+async function transformImgNode(
+  node: JxMutableNode | JxDocument,
+  config: ImageConfig,
+  projectRoot: string,
+  outDir: string,
+  cache: CacheManifest,
+  imageRefs: Map<string, ImageManifest>,
+) {
   if (!node.attributes) node.attributes = {};
 
   const src = node.attributes.src ?? node.src;
@@ -166,10 +189,10 @@ async function transformImgNode(node, config, projectRoot, outDir, cache, imageR
     node.attributes.sizes = node.attributes.sizes ?? config.sizes;
   }
 
-  if (!node.attributes.width && manifest.original.width) {
+  if (!node.attributes.width && manifest.original?.width) {
     node.attributes.width = String(manifest.original.width);
   }
-  if (!node.attributes.height && manifest.original.height) {
+  if (!node.attributes.height && manifest.original?.height) {
     node.attributes.height = String(manifest.original.height);
   }
 
@@ -195,7 +218,14 @@ const DATA_NO_OPT_RE = /\bdata-no-optimize\b/;
  * @param {Map<string, ImageManifest>} imageRefs
  * @returns {Promise<string>}
  */
-async function transformInnerHtmlImages(html, config, projectRoot, outDir, cache, imageRefs) {
+async function transformInnerHtmlImages(
+  html: string,
+  config: ImageConfig,
+  projectRoot: string,
+  outDir: string,
+  cache: CacheManifest,
+  imageRefs: Map<string, ImageManifest>,
+) {
   /** @type {{ match: string; replacement: string }[]} */
   const replacements = [];
 
@@ -226,10 +256,10 @@ async function transformInnerHtmlImages(html, config, projectRoot, outDir, cache
     if (!srcset) continue;
 
     let extra = ` srcset="${srcset}" sizes="${config.sizes}"`;
-    if (!/\bwidth=/.test(attrs) && manifest.original.width) {
+    if (!/\bwidth=/.test(attrs) && manifest.original?.width) {
       extra += ` width="${manifest.original.width}"`;
     }
-    if (!/\bheight=/.test(attrs) && manifest.original.height) {
+    if (!/\bheight=/.test(attrs) && manifest.original?.height) {
       extra += ` height="${manifest.original.height}"`;
     }
     if (config.lazyLoad && !/\bloading="eager"/.test(attrs)) {

package/src/site/{layout-resolver.js → layout-resolver.ts}

@@ -15,6 +15,7 @@
 
 import { readFileSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
+import type { JxElement, JxDocument } from "@jxsuite/schema/types";
 
 /**
  * Resolve a page's layout, wrapping the page content in the layout structure.
@@ -24,12 +25,14 @@ import { resolve } from "node:path";
  * @param {string} projectRoot - Project root directory
  * @returns {JxDocument} The merged document (layout wrapping page content)
  */
-export function resolveLayout(pageDoc, projectConfig, projectRoot) {
+export function resolveLayout(
+  pageDoc: JxDocument,
+  projectConfig: Record<string, unknown>,
+  projectRoot: string,
+) {
   // Determine which layout to use
   const layoutRef =
-    pageDoc.$layout ??
-    /** @type {Record<string, unknown>} */ (projectConfig.defaults)?.layout ??
-    null;
+    pageDoc.$layout ?? (projectConfig.defaults as Record<string, unknown>)?.layout ?? null;
 
   if (!layoutRef) {
     // No layout — return page as-is
@@ -37,7 +40,7 @@ export function resolveLayout(pageDoc, projectConfig, projectRoot) {
   }
 
   // Load the layout file
-  const layoutPath = resolve(projectRoot, /** @type {string} */ (layoutRef));
+  const layoutPath = resolve(projectRoot, layoutRef as string);
   if (!existsSync(layoutPath)) {
     throw new Error(`Layout not found: ${layoutRef} (resolved to ${layoutPath})`);
   }
@@ -47,7 +50,7 @@ export function resolveLayout(pageDoc, projectConfig, projectRoot) {
   try {
     layoutDoc = JSON.parse(readFileSync(layoutPath, "utf8"));
   } catch (e) {
-    const err = /** @type {Error} */ (e);
+    const err = e as Error;
     throw new Error(`Invalid layout JSON at ${layoutPath}: ${err.message}`);
   }
 
@@ -58,9 +61,12 @@ export function resolveLayout(pageDoc, projectConfig, projectRoot) {
 
   // Distribute page children into layout slots
   const rawChildren = pageDoc.children ?? [];
-  const pageChildren = /** @type {(JxElement | string)[]} */ (
-    typeof rawChildren === "string" ? [rawChildren] : Array.isArray(rawChildren) ? rawChildren : []
-  );
+  const pageChildren =
+    typeof rawChildren === "string"
+      ? [rawChildren]
+      : Array.isArray(rawChildren)
+        ? rawChildren
+        : ([] as (JxElement | string)[]);
   const merged = deepClone(layoutDoc);
 
   distributeSlots(merged, pageChildren);
@@ -110,21 +116,19 @@ export function resolveLayout(pageDoc, projectConfig, projectRoot) {
  * @param {JxElement} node - Layout document tree (mutated in place)
  * @param {(JxElement | string)[]} children - Page children to distribute
  */
-function distributeSlots(node, children) {
+function distributeSlots(node: JxElement, children: (JxElement | string)[]) {
   if (!node || typeof node !== "object") return;
   if (!Array.isArray(node.children)) return;
 
   // Collect named and default children
-  /** @type {Map<string, (JxElement | string)[]>} */
-  const named = new Map(); // slot name → children[]
-  /** @type {(JxElement | string)[]} */
-  const defaults = []; // children without a slot target
+  const named: Map<string, (JxElement | string)[]> = new Map(); // slot name → children[]
+  const defaults: (JxElement | string)[] = []; // children without a slot target
 
   for (const child of children) {
     if (child && typeof child === "object" && child.attributes?.slot) {
-      const slotName = /** @type {string} */ (child.attributes.slot);
+      const slotName = child.attributes.slot as string;
       if (!named.has(slotName)) named.set(slotName, []);
-      /** @type {(JxElement | string)[]} */ (named.get(slotName)).push(child);
+      (named.get(slotName) as (JxElement | string)[]).push(child);
     } else {
       defaults.push(child);
     }
@@ -141,23 +145,24 @@ function distributeSlots(node, children) {
  * @param {Map<string, (JxElement | string)[]>} named
  * @param {(JxElement | string)[]} defaults
  */
-function fillSlots(node, named, defaults) {
+function fillSlots(
+  node: JxElement,
+  named: Map<string, (JxElement | string)[]>,
+  defaults: (JxElement | string)[],
+) {
   if (!node || typeof node !== "object") return;
   if (!Array.isArray(node.children)) return;
 
-  /** @type {(JxElement | string)[]} */
-  const newChildren = [];
+  const newChildren: (JxElement | string)[] = [];
 
   for (const child of node.children) {
     if (child && typeof child === "object" && child.tagName === "slot") {
       const slotName = child.attributes?.name;
 
-      if (slotName && named.has(/** @type {string} */ (slotName))) {
+      if (slotName && named.has(slotName as string)) {
         // Named slot — replace with matching children
-        newChildren.push(
-          .../** @type {(JxElement | string)[]} */ (named.get(/** @type {string} */ (slotName))),
-        );
-        named.delete(/** @type {string} */ (slotName)); // consumed
+        newChildren.push(...(named.get(slotName as string) as (JxElement | string)[]));
+        named.delete(slotName as string); // consumed
       } else if (!slotName && defaults.length > 0) {
         // Default slot — replace with unassigned children
         newChildren.push(...defaults);
@@ -171,7 +176,7 @@ function fillSlots(node, named, defaults) {
       }
     } else {
       // Not a slot — recurse into it
-      fillSlots(/** @type {JxElement} */ (child), named, defaults);
+      fillSlots(child as JxElement, named, defaults);
       newChildren.push(child);
     }
   }
@@ -185,6 +190,6 @@ function fillSlots(node, named, defaults) {
  * @param {JxDocument} obj
  * @returns {JxDocument}
  */
-function deepClone(obj) {
+function deepClone(obj: JxDocument) {
   return JSON.parse(JSON.stringify(obj));
 }

package/src/site/{pages-discovery.js → pages-discovery.ts}

@@ -12,18 +12,18 @@
 
 import { readdirSync, readFileSync } from "node:fs";
 import { resolve, relative, extname, join } from "node:path";
-
-/**
- * @typedef {object} Route
- * @property {string} urlPattern - URL pattern (e.g. "/blog/:slug")
- * @property {string} sourcePath - Absolute path to the .json source file
- * @property {string} relativePath - Path relative to pages/ dir
- * @property {boolean} isDynamic - Whether route has parameters
- * @property {boolean} isCatchAll - Whether route uses [...param] spread
- * @property {string[]} params - Parameter names (e.g. ["slug"])
- * @property {string | null} $layout - Layout override from page frontmatter, if any
- * @property {Record<string, string>} [_pathParams] - Resolved path parameters
- */
+import type { ContentLoaderEntry } from "@jxsuite/parser/types";
+
+interface Route {
+  urlPattern: string; // URL pattern (e.g. "/blog/:slug")
+  sourcePath: string; // Absolute path to the .json source file
+  relativePath: string; // Path relative to pages/ dir
+  isDynamic: boolean; // Whether route has parameters
+  isCatchAll: boolean; // Whether route uses [...param] spread
+  params: string[]; // Parameter names (e.g. ["slug"])
+  $layout: string | null; // Layout override from page frontmatter, if any
+  _pathParams?: Record<string, string>; // Resolved path parameters
+}
 
 /**
  * Discover all routable pages in a pages/ directory.
@@ -31,9 +31,8 @@ import { resolve, relative, extname, join } from "node:path";
  * @param {string} pagesDir - Absolute path to the pages/ directory
  * @returns {Route[]} Sorted route table (static routes first, then dynamic)
  */
-export function discoverPages(pagesDir) {
-  /** @type {Route[]} */
-  const routes = [];
+export function discoverPages(pagesDir: string) {
+  const routes: Route[] = [];
   walkDir(pagesDir, pagesDir, routes);
 
   // Sort: static routes first, then by specificity (more segments = more specific)
@@ -53,7 +52,7 @@ export function discoverPages(pagesDir) {
  * @param {string} pagesRoot
  * @param {Route[]} routes
  */
-function walkDir(dir, pagesRoot, routes) {
+function walkDir(dir: string, pagesRoot: string, routes: Route[]) {
   const entries = readdirSync(dir, { withFileTypes: true });
 
   for (const entry of entries) {
@@ -86,7 +85,7 @@ function walkDir(dir, pagesRoot, routes) {
  * @param {string} absolutePath - Full filesystem path
  * @returns {Route}
  */
-function fileToRoute(relativePath, absolutePath) {
+function fileToRoute(relativePath: string, absolutePath: string) {
   // Remove .json or .md extension
   let urlPath = relativePath.replace(/\.(json|md)$/, "");
 
@@ -104,15 +103,14 @@ function fileToRoute(relativePath, absolutePath) {
   if (!urlPath.startsWith("/")) urlPath = "/" + urlPath;
 
   // Extract parameters from bracket syntax
-  /** @type {string[]} */
-  const params = [];
+  const params: string[] = [];
   let isDynamic = false;
   let isCatchAll = false;
 
   // Convert [param] → :param and [...param] → *
   const urlPattern = urlPath.replace(
     /\[\.\.\.(\w+)\]|\[(\w+)\]/g,
-    (/** @type {string} */ match, /** @type {string} */ spread, /** @type {string} */ named) => {
+    (match: string, spread: string, named: string) => {
       if (spread) {
         isCatchAll = true;
         isDynamic = true;
@@ -172,9 +170,12 @@ function fileToRoute(relativePath, absolutePath) {
  * @param {Map<string, any[]>} [contentTypes] - Loaded content types (from content-loader)
  * @returns {Promise<Route[]>} Expanded routes with concrete paths
  */
-export async function expandDynamicRoutes(routes, projectRoot, contentTypes = new Map()) {
-  /** @type {Route[]} */
-  const expanded = [];
+export async function expandDynamicRoutes(
+  routes: Route[],
+  projectRoot: string,
+  contentTypes: Map<string, any[]> = new Map(),
+) {
+  const expanded: Route[] = [];
 
   for (const route of routes) {
     if (!route.isDynamic) {
@@ -202,8 +203,8 @@ export async function expandDynamicRoutes(routes, projectRoot, contentTypes = ne
     for (const pathEntry of pathEntries) {
       let concreteUrl = route.urlPattern;
       for (const [param, value] of Object.entries(pathEntry)) {
-        concreteUrl = concreteUrl.replace(`:${param}`, /** @type {string} */ (value));
-        concreteUrl = concreteUrl.replace("*", /** @type {string} */ (value));
+        concreteUrl = concreteUrl.replace(`:${param}`, value as string);
+        concreteUrl = concreteUrl.replace("*", value as string);
       }
 
       expanded.push({
@@ -228,7 +229,7 @@ export async function expandDynamicRoutes(routes, projectRoot, contentTypes = ne
  * @param {Map<string, any[]>} contentTypes
  * @returns {Record<string, any>[]} Array of { paramName: value } objects
  */
-function resolvePathEntries($paths, projectRoot, contentTypes) {
+function resolvePathEntries($paths: any, projectRoot: string, contentTypes: Map<string, any[]>) {
   // Legacy: array of param objects
   if (Array.isArray($paths)) {
     return $paths;
@@ -245,7 +246,7 @@ function resolvePathEntries($paths, projectRoot, contentTypes) {
     }
     const param = $paths.param ?? "slug";
     const field = $paths.field ?? "id";
-    return entries.map((/** @type {ContentLoaderEntry} */ entry) => ({
+    return entries.map((entry: ContentLoaderEntry) => ({
       [param]: field === "id" ? entry.id : (entry.data[field] ?? entry.id),
     }));
   }
@@ -253,7 +254,7 @@ 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 {string} */ v) => ({ [param]: v }));
+    return $paths.values.map((v: string) => ({ [param]: v }));
   }
 
   // Data file ref: { "$ref": "./data/products.json", param: "id", field: "sku" }
@@ -264,7 +265,7 @@ function resolvePathEntries($paths, projectRoot, contentTypes) {
     try {
       data = JSON.parse(readFileSync(filePath, "utf8"));
     } catch (e) {
-      const err = /** @type {Error} */ (e);
+      const err = e as Error;
       console.warn(`Warning: $paths.$ref could not load "${$paths.$ref}": ${err.message}`);
       return [];
     }
@@ -274,7 +275,7 @@ function resolvePathEntries($paths, projectRoot, contentTypes) {
     }
     const param = $paths.param ?? "id";
     const field = $paths.field ?? "id";
-    return data.map((/** @type {Record<string, unknown>} */ item) => ({
+    return data.map((item: Record<string, unknown>) => ({
       [param]: item[field] ?? item.id ?? String(item),
     }));
   }

package/src/site/{prototype-resolver.js → prototype-resolver.ts}

@@ -18,6 +18,7 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
+import type { JxDocument, JxMutableNode } from "@jxsuite/schema/types";
 
 /**
  * Prototype names handled elsewhere (builtins + legacy content system). These are skipped by the
@@ -54,7 +55,12 @@ const RESERVED_KEYS = new Set([
  * @param {{ config?: Record<string, unknown>; contentTypes?: Map<string, unknown[]> }} [projectContext] -
  *   Project-level context injected into all classes
  */
-export async function resolvePrototypes(doc, route, projectRoot, projectContext = {}) {
+export async function resolvePrototypes(
+  doc: JxMutableNode | JxDocument,
+  route: { sourcePath?: string; _pathParams?: Record<string, string> },
+  projectRoot: string,
+  projectContext: { config?: Record<string, unknown>; contentTypes?: Map<string, unknown[]> } = {},
+) {
   const imports = doc.imports ?? {};
   const state = doc.state;
   if (!state) return;
@@ -83,7 +89,7 @@ export async function resolvePrototypes(doc, route, projectRoot, projectContext
     } catch (err) {
       console.warn(
         `prototype-resolver: failed to resolve "${key}" ($prototype: "${def.$prototype}"):`,
-        /** @type {Error} */ (err).message,
+        (err as Error).message,
       );
     }
   }
@@ -99,7 +105,13 @@ export async function resolvePrototypes(doc, route, projectRoot, projectContext
  * @param {{ config?: Record<string, unknown>; contentTypes?: Map<string, unknown[]> }} projectContext
  * @returns {Promise<any>} The resolved value
  */
-async function resolveClassPrototype(def, route, projectRoot, state, projectContext) {
+async function resolveClassPrototype(
+  def: Record<string, any>,
+  route: { sourcePath?: string; _pathParams?: Record<string, string> },
+  projectRoot: string,
+  state: Record<string, unknown>,
+  projectContext: { config?: Record<string, unknown>; contentTypes?: Map<string, unknown[]> },
+) {
   const src = def.$src;
 
   // 1. Resolve .class.json path — handles both npm specifiers and relative paths
@@ -138,8 +150,7 @@ async function resolveClassPrototype(def, route, projectRoot, state, projectCont
   }
 
   // 6. Build config — filter out reserved keys
-  /** @type {Record<string, any>} */
-  const config = {};
+  const config: Record<string, any> = {};
   for (const [k, v] of Object.entries(def)) {
     if (!RESERVED_KEYS.has(k)) config[k] = v;
   }