@jxsuite/runtime 0.19.0 → 0.21.0

package/src/runtime.js

@@ -25,7 +25,7 @@ import { reactive, ref, computed, effect, isRef, onEffectCleanup } from "@vue/re
  *
  * @param {string | Record<string, any>} source - Path to .json file, URL, or raw document object
  * @param {HTMLElement} [target] Default is `document.body`
- * @param {any} [options]
+ * @param {JxRenderOptions} [options]
  * @returns {Promise<Record<string, any>>} Resolves with the live component scope (state reactive
  *   proxy)
  */
@@ -88,6 +88,13 @@ export function setSkipServerFunctions(/** @type {boolean} */ v) {
   _serverFnConfig.skip = v;
 }
 
+/** @type {{ skip: boolean }} */
+const _contentConfig = { skip: false };
+/** Set to true to suppress ContentCollection/ContentEntry resolution (used by Studio edit mode). */
+export function setSkipContentResolution(/** @type {boolean} */ v) {
+  _contentConfig.skip = v;
+}
+
 /**
  * Build the reactive scope (state) from the document using the five-shape detection algorithm.
  *
@@ -232,11 +239,12 @@ export { hasSchemaKeywords };
  *
  * @param {string} str
  * @param {Record<string, any>} state
- * @returns {any}
+ * @returns {string}
  */
 function evaluateTemplate(str, state) {
-  const fn = new Function("state", "$map", `return \`${str}\``);
-  return fn(state, state?.$map);
+  const $map = state?.$map;
+  const fn = new Function("state", "$map", "item", "index", `return \`${str}\``);
+  return fn(state, $map, $map?.item, $map?.index);
 }
 
 // ─── Step 2b: Function resolution (Shape 4) ─────────────────────────────────
@@ -254,7 +262,7 @@ const _moduleCache = new Map();
  * @param {Record<string, any>} state - Reactive scope proxy
  * @param {string} key - Def key name
  * @param {string} [base] - Base URL for resolving $src imports
- * @returns {Promise<any>}
+ * @returns {Promise<unknown>}
  */
 async function resolveFunction(def, state, key, base) {
   if (def.body && def.$src) {
@@ -385,7 +393,7 @@ export const RESERVED_KEYS = new Set([
  *
  * @param {Record<string, any>} def
  * @param {Record<string, any>} state - Reactive scope proxy (or child scope via Object.create)
- * @param {any} [options]
+ * @param {JxRenderOptions} [options]
  * @returns {HTMLElement | Text}
  */
 export function renderNode(def, state, options) {
@@ -448,7 +456,7 @@ export function renderNode(def, state, options) {
 /**
  * Check if a value is a template string (contains ${}).
  *
- * @param {any} val
+ * @param {unknown} val
  * @returns {boolean}
  */
 function isTemplateString(val) {
@@ -492,19 +500,22 @@ function applyProperties(el, def, state) {
 }
 
 /**
- * @param {any} el
+ * @param {HTMLElement} el
  * @param {string} key
- * @param {any} val
+ * @param {unknown} val
  * @param {Record<string, any>} state
  */
 function bindProperty(el, key, val, state) {
+  const target = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (el));
   if (isRefObj(val)) {
     if (key === "id") {
-      el[key] = resolveRef(val.$ref, state);
+      target[key] = /** @type {string} */ (
+        resolveRef(/** @type {{ $ref: string }} */ (val).$ref, state)
+      );
       return;
     }
     effect(() => {
-      el[key] = resolveRef(val.$ref, state);
+      target[key] = resolveRef(/** @type {{ $ref: string }} */ (val).$ref, state);
     });
     return;
   }
@@ -512,12 +523,12 @@ function bindProperty(el, key, val, state) {
   // Universal ${} reactivity — template strings in element properties
   if (isTemplateString(val)) {
     effect(() => {
-      el[key] = evaluateTemplate(val, state);
+      target[key] = evaluateTemplate(/** @type {string} */ (val), state);
     });
     return;
   }
 
-  el[key] = val;
+  target[key] = val;
 }
 
 /**
@@ -548,9 +559,10 @@ export function applyStyle(el, styleDef, mediaQueries = {}, state = {}) {
       else el.style.setProperty(prop, val);
     } else if (isTemplateString(val))
       effect(() => {
-        /** @type {any} */ (el.style)[prop] = evaluateTemplate(val, state);
+        /** @type {Record<string, string>} */ (/** @type {unknown} */ (el.style))[prop] =
+          evaluateTemplate(val, state);
       });
-    else /** @type {any} */ (el.style)[prop] = val;
+    else /** @type {Record<string, string>} */ (/** @type {unknown} */ (el.style))[prop] = val;
   }
 
   const hasNested = Object.keys(nested).length > 0;
@@ -647,7 +659,7 @@ function applyAttributes(el, attrs, state) {
 /**
  * @param {Record<string, any>} def
  * @param {Record<string, any>} state
- * @param {any} [options]
+ * @param {JxRenderOptions} [options]
  * @returns {HTMLElement}
  */
 function renderMappedArray(def, state, options) {
@@ -672,11 +684,13 @@ function renderMappedArray(def, state, options) {
     if (!Array.isArray(items)) return;
     if (filterRef) {
       const fn = resolveRef(filterRef.$ref, state);
-      if (typeof fn === "function") items = items.filter(fn);
+      if (typeof fn === "function")
+        items = items.filter(/** @type {(v: unknown) => boolean} */ (fn));
     }
     if (sortRef) {
       const fn = resolveRef(sortRef.$ref, state);
-      if (typeof fn === "function") items = [...items].sort(fn);
+      if (typeof fn === "function")
+        items = [...items].sort(/** @type {(a: unknown, b: unknown) => number} */ (fn));
     }
 
     items.forEach((item, index) => {
@@ -699,7 +713,7 @@ function renderMappedArray(def, state, options) {
 /**
  * @param {Record<string, any>} def
  * @param {Record<string, any>} state
- * @param {any} [options]
+ * @param {JxRenderOptions} [options]
  * @returns {HTMLElement}
  */
 function renderSwitch(def, state, options) {
@@ -715,7 +729,7 @@ function renderSwitch(def, state, options) {
 
   effect(() => {
     container.innerHTML = "";
-    const key = resolveRef(def.$switch.$ref, state);
+    const key = /** @type {string} */ (resolveRef(def.$switch.$ref, state));
     const caseDef = def.cases?.[key];
     if (!caseDef) return;
 
@@ -732,7 +746,7 @@ function renderSwitch(def, state, options) {
           const childOpts = options ? { ...options, _path: [...path, "cases", key] } : undefined;
           container.appendChild(renderNode(doc, childScope, childOpts));
         })
-        .catch((/** @type {any} */ e) =>
+        .catch((/** @type {unknown} */ e) =>
           console.error("Jx $switch: failed to load external case", caseDef.$ref, e),
         );
       return;
@@ -757,7 +771,7 @@ function renderSwitch(def, state, options) {
  * @param {Record<string, any>} state - Reactive scope proxy
  * @param {string} key - Def key (for diagnostics)
  * @param {string} [base] - Base URL for resolving $src imports
- * @returns {Promise<any>}
+ * @returns {Promise<unknown>}
  */
 export async function resolvePrototype(def, state, key, base) {
   // ── External class via $src ─────────────────────────────────────────────────
@@ -767,10 +781,10 @@ export async function resolvePrototype(def, state, key, base) {
 
   switch (def.$prototype) {
     case "Request": {
-      /** @type {import("@vue/reactivity").Ref<any>} */
+      /** @type {import("@vue/reactivity").Ref<unknown>} */
       const s = ref(null);
       const debounceMs = def.debounce ?? 0;
-      /** @type {any} */
+      /** @type {ReturnType<typeof setTimeout> | null} */
       let debounceTimer = null;
 
       if (!def.manual) {
@@ -786,7 +800,7 @@ export async function resolvePrototype(def, state, key, base) {
           const controller = new AbortController();
           onEffectCleanup(() => {
             controller.abort();
-            clearTimeout(debounceTimer);
+            if (debounceTimer !== null) clearTimeout(debounceTimer);
           });
 
           const doFetch = () =>
@@ -802,8 +816,8 @@ export async function resolvePrototype(def, state, key, base) {
               .then((d) => {
                 s.value = d;
               })
-              .catch((/** @type {any} */ e) => {
-                if (e.name !== "AbortError") s.value = { error: String(e) };
+              .catch((/** @type {unknown} */ e) => {
+                if (/** @type {Error} */ (e).name !== "AbortError") s.value = { error: String(e) };
               });
 
           if (debounceMs > 0) {
@@ -902,22 +916,22 @@ export async function resolvePrototype(def, state, key, base) {
       } = def;
       const req = indexedDB.open(database, version);
       req.onupgradeneeded = (e) => {
-        /** @type {any} */
-        const db = /** @type {any} */ (e.target)?.result;
+        /** @type {IDBDatabase} */
+        const db = /** @type {IDBOpenDBRequest} */ (e.target).result;
         if (!db.objectStoreNames.contains(store)) {
           const os = db.createObjectStore(store, { keyPath, autoIncrement });
           for (const i of indexes) os.createIndex(i.name, i.keyPath, { unique: i.unique ?? false });
         }
       };
       req.onsuccess = (e) => {
-        /** @type {any} */
-        const db = /** @type {any} */ (e.target)?.result;
+        /** @type {IDBDatabase} */
+        const db = /** @type {IDBOpenDBRequest} */ (e.target).result;
         idbState.value = {
           database,
           store,
           version,
           isReady: true,
-          getStore: (/** @type {string} */ mode = "readwrite") =>
+          getStore: (/** @type {IDBTransactionMode} */ mode = "readwrite") =>
             Promise.resolve(db.transaction(store, mode).objectStore(store)),
         };
       };
@@ -945,6 +959,42 @@ export async function resolvePrototype(def, state, key, base) {
     case "ReadableStream":
       return null;
 
+    case "ContentCollection":
+    case "ContentEntry": {
+      if (_contentConfig.skip) {
+        return ref(def.$prototype === "ContentCollection" ? [{ id: "", data: {} }] : null);
+      }
+      const s = ref(def.$prototype === "ContentCollection" ? [] : null);
+      effect(() => {
+        let id = def.id;
+        if (id && typeof id === "object" && id.$ref?.startsWith("#/$params/")) {
+          const paramName = id.$ref.replace("#/$params/", "");
+          id = state?.$params?.[paramName];
+        } else if (typeof id === "string" && id.includes("${")) {
+          id = evaluateTemplate(id, state);
+        }
+        if (def.$prototype === "ContentEntry" && !id) return;
+        fetch("/__studio/content", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            $prototype: def.$prototype,
+            contentType: def.contentType,
+            id,
+            filter: def.filter,
+            sort: def.sort,
+            limit: def.limit,
+          }),
+        })
+          .then((r) => (r.ok ? r.json() : null))
+          .then((d) => {
+            s.value = d;
+          })
+          .catch(() => {});
+      });
+      return s;
+    }
+
     default:
       console.warn(
         `Jx: unknown $prototype "${def.$prototype}" for "${key}". Did you mean to add '$src'?`,
@@ -976,7 +1026,7 @@ const EXTERNAL_RESERVED = new Set([
  * @param {Record<string, any>} state
  * @param {string} key
  * @param {string} [base]
- * @returns {Promise<any>}
+ * @returns {Promise<unknown>}
  */
 async function resolveExternalPrototype(def, state, key, base) {
   const src = def.$src;
@@ -1000,7 +1050,7 @@ async function resolveExternalPrototype(def, state, key, base) {
  * @param {string} src - JS module URL to import
  * @param {string} exportName - Export name to look up
  * @param {string} [base] - Base URL for resolution
- * @returns {Promise<any>}
+ * @returns {Promise<unknown>}
  */
 async function importAndInstantiate(def, src, exportName, base) {
   let mod;
@@ -1049,7 +1099,7 @@ async function importAndInstantiate(def, src, exportName, base) {
   /** @type {import("@vue/reactivity").Ref<any>} */
   const s = ref(value);
   if (typeof instance.subscribe === "function") {
-    instance.subscribe((/** @type {any} */ newVal) => {
+    instance.subscribe((/** @type {unknown} */ newVal) => {
       s.value = newVal;
     });
   }
@@ -1064,7 +1114,7 @@ async function importAndInstantiate(def, src, exportName, base) {
  * @param {Record<string, any>} state
  * @param {string} key
  * @param {string} [base]
- * @returns {Promise<any>}
+ * @returns {Promise<unknown>}
  */
 async function resolveClassJson(def, state, key, base) {
   const src = def.$src;
@@ -1116,7 +1166,7 @@ async function resolveClassJson(def, state, key, base) {
   /** @type {import("@vue/reactivity").Ref<any>} */
   const s = ref(value);
   if (typeof instance.subscribe === "function") {
-    instance.subscribe((/** @type {any} */ newVal) => {
+    instance.subscribe((/** @type {unknown} */ newVal) => {
       s.value = newVal;
     });
   }
@@ -1128,7 +1178,7 @@ async function resolveClassJson(def, state, key, base) {
  * fields to _-prefixed public fields.
  *
  * @param {Record<string, any>} classDef
- * @returns {any}
+ * @returns {DynamicClass}
  */
 function classFromSchema(classDef) {
   const fields = classDef.$defs?.fields ?? {};
@@ -1138,16 +1188,34 @@ function classFromSchema(classDef) {
   class DynClass {
     constructor(/** @type {Record<string, any>} */ config = {}) {
       for (const [key, field] of Object.entries(fields)) {
-        /** @type {any} */
-        const typedField = field;
+        /**
+         * @type {{
+         *   identifier?: string;
+         *   access?: string;
+         *   initializer?: unknown;
+         *   default?: unknown;
+         * }}
+         */
+        const typedField =
+          /**
+           * @type {{
+           *   identifier?: string;
+           *   access?: string;
+           *   initializer?: unknown;
+           *   default?: unknown;
+           * }}
+           */ (field);
         const id = typedField.identifier ?? key;
         const propName = typedField.access === "private" ? `_${id}` : id;
-        if (config[id] !== undefined) /** @type {any} */ (this)[propName] = config[id];
+        if (config[id] !== undefined)
+          /** @type {Record<string, unknown>} */ (this)[propName] = config[id];
         else if (typedField.initializer !== undefined)
-          /** @type {any} */ (this)[propName] = typedField.initializer;
+          /** @type {Record<string, unknown>} */ (this)[propName] = typedField.initializer;
         else if (typedField.default !== undefined)
-          /** @type {any} */ (this)[propName] = structuredClone(typedField.default);
-        else /** @type {any} */ (this)[propName] = null;
+          /** @type {Record<string, unknown>} */ (this)[propName] = structuredClone(
+            typedField.default,
+          );
+        else /** @type {Record<string, unknown>} */ (this)[propName] = null;
       }
       if (ctor?.body) {
         const bodyStr = Array.isArray(ctor.body) ? ctor.body.join("\n") : ctor.body;
@@ -1157,13 +1225,35 @@ function classFromSchema(classDef) {
   }
 
   for (const [key, method] of Object.entries(methods)) {
-    /** @type {any} */
-    const typedMethod = method;
+    /**
+     * @type {{
+     *   identifier?: string;
+     *   parameters?: Record<string, unknown>[];
+     *   body?: string | string[];
+     *   role?: string;
+     *   scope?: string;
+     *   getter?: { body: string };
+     *   setter?: { body: string; parameters?: Record<string, unknown>[] };
+     * }}
+     */
+    const typedMethod = /**
+     * @type {{
+     *   identifier?: string;
+     *   parameters?: Record<string, unknown>[];
+     *   body?: string | string[];
+     *   role?: string;
+     *   scope?: string;
+     *   getter?: { body: string };
+     *   setter?: { body: string; parameters?: Record<string, unknown>[] };
+     * }}
+     */ (method);
     const name = typedMethod.identifier ?? key;
-    const params = (typedMethod.parameters ?? []).map((/** @type {any} */ p) => {
-      if (p.$ref) return p.$ref.split("/").pop();
-      return p.identifier ?? p.name ?? "arg";
-    });
+    const params = /** @type {string[]} */ (
+      (typedMethod.parameters ?? []).map((/** @type {Record<string, unknown>} */ p) => {
+        if (p.$ref) return /** @type {string} */ (/** @type {string} */ (p.$ref).split("/").pop());
+        return /** @type {string} */ (p.identifier ?? p.name ?? "arg");
+      })
+    );
     const bodyStr = Array.isArray(typedMethod.body)
       ? typedMethod.body.join("\n")
       : (typedMethod.body ?? "");
@@ -1172,23 +1262,27 @@ function classFromSchema(classDef) {
       /** @type {PropertyDescriptor} */
       const descriptor = {};
       if (typedMethod.getter)
-        descriptor.get = /** @type {any} */ (new Function(typedMethod.getter.body));
+        descriptor.get = /** @type {() => unknown} */ (new Function(typedMethod.getter.body));
       if (typedMethod.setter) {
         const sp = (typedMethod.setter.parameters ?? []).map(
-          (/** @type {any} */ p) => p.$ref?.split("/").pop() ?? "v",
+          (/** @type {Record<string, unknown>} */ p) =>
+            /** @type {string} */ (p.$ref)?.split("/").pop() ?? "v",
+        );
+        descriptor.set = /** @type {(v: unknown) => void} */ (
+          new Function(...sp, typedMethod.setter.body)
         );
-        descriptor.set = /** @type {any} */ (new Function(...sp, typedMethod.setter.body));
       }
       Object.defineProperty(DynClass.prototype, name, { ...descriptor, configurable: true });
     } else if (typedMethod.scope === "static") {
-      /** @type {any} */ (DynClass)[name] = new Function(...params, bodyStr);
+      /** @type {DynamicClass} */ (DynClass)[name] = new Function(...params, bodyStr);
     } else {
-      /** @type {any} */ (DynClass.prototype)[name] = new Function(...params, bodyStr);
+      /** @type {DynamicClass} */ (DynClass).prototype[name] = new Function(...params, bodyStr);
     }
   }
 
   Object.defineProperty(DynClass, "name", { value: classDef.title, configurable: true });
-  return DynClass;
+  const dynCtor = /** @type {DynamicClass} */ (/** @type {unknown} */ (DynClass));
+  return dynCtor;
 }
 
 /**
@@ -1200,7 +1294,7 @@ function classFromSchema(classDef) {
  * @param {Record<string, any>} state
  * @param {string} key
  * @param {string} [base]
- * @returns {Promise<any>}
+ * @returns {Promise<unknown>}
  */
 async function resolveViaDevProxy(def, state, key, base) {
   /** @type {Record<string, any>} */
@@ -1209,7 +1303,9 @@ async function resolveViaDevProxy(def, state, key, base) {
     if (!EXTERNAL_RESERVED.has(k)) config[k] = v;
   }
 
-  const hasTemplates = Object.values(config).some((/** @type {any} */ v) => isTemplateString(v));
+  const hasTemplates = Object.values(config).some((/** @type {unknown} */ v) =>
+    isTemplateString(v),
+  );
 
   /** @param {Record<string, any>} resolvedConfig */
   const doResolve = (resolvedConfig) =>
@@ -1239,17 +1335,17 @@ async function resolveViaDevProxy(def, state, key, base) {
         resolvedConfig[k] = isTemplateString(v) ? evaluateTemplate(v, state) : v;
       }
       doResolve(resolvedConfig)
-        .then((/** @type {any} */ value) => {
+        .then((/** @type {unknown} */ value) => {
           s.value = value;
         })
-        .catch((/** @type {any} */ e) => console.error("Jx dev proxy:", e));
+        .catch((/** @type {unknown} */ e) => console.error("Jx dev proxy:", e));
     });
   } else {
     doResolve(config)
-      .then((/** @type {any} */ value) => {
+      .then((/** @type {unknown} */ value) => {
         s.value = value;
       })
-      .catch((/** @type {any} */ e) => console.error("Jx dev proxy:", e));
+      .catch((/** @type {unknown} */ e) => console.error("Jx dev proxy:", e));
   }
   return s;
 }
@@ -1264,7 +1360,7 @@ async function resolveViaDevProxy(def, state, key, base) {
  * @param {Record<string, any>} state
  * @param {string} key
  * @param {string} [base]
- * @returns {Promise<any>}
+ * @returns {Promise<unknown>}
  */
 async function resolveServerFunction(def, state, key, base) {
   const src = def.$src;
@@ -1298,12 +1394,12 @@ async function resolveServerFunction(def, state, key, base) {
     throw new Error(`Jx: "${exportName}" from "${src}" is not a function`);
 
   const rawArgs = def.arguments ?? {};
-  const hasReactiveArg = Object.values(rawArgs).some((/** @type {any} */ v) => isRefObj(v));
+  const hasReactiveArg = Object.values(rawArgs).some((/** @type {unknown} */ v) => isRefObj(v));
   const resolveArgs = () => {
     /** @type {Record<string, any>} */
     const args = {};
     for (const [k, v] of Object.entries(rawArgs)) {
-      args[k] = isRefObj(v) ? resolveRef(/** @type {any} */ (v).$ref, state) : v;
+      args[k] = isRefObj(v) ? resolveRef(/** @type {{ $ref: string }} */ (v).$ref, state) : v;
     }
     return args;
   };
@@ -1316,7 +1412,7 @@ async function resolveServerFunction(def, state, key, base) {
       const args = resolveArgs();
       onEffectCleanup(() => {});
       fn(args)
-        .then((/** @type {any} */ result) => {
+        .then((/** @type {unknown} */ result) => {
           s.value = result;
         })
         .catch(() => {});
@@ -1336,17 +1432,17 @@ async function resolveServerFunction(def, state, key, base) {
  * @param {Record<string, any>} state
  * @param {string} key
  * @param {string} [base]
- * @returns {Promise<any>}
+ * @returns {Promise<unknown>}
  */
 async function resolveServerFunctionViaProxy(def, state, key, base) {
   const rawArgs = def.arguments ?? {};
-  const hasReactiveArg = Object.values(rawArgs).some((/** @type {any} */ v) => isRefObj(v));
+  const hasReactiveArg = Object.values(rawArgs).some((/** @type {unknown} */ v) => isRefObj(v));
 
   const resolveArgs = () => {
     /** @type {Record<string, any>} */
     const args = {};
     for (const [k, v] of Object.entries(rawArgs)) {
-      args[k] = isRefObj(v) ? resolveRef(/** @type {any} */ (v).$ref, state) : v;
+      args[k] = isRefObj(v) ? resolveRef(/** @type {{ $ref: string }} */ (v).$ref, state) : v;
     }
     return args;
   };
@@ -1375,17 +1471,17 @@ async function resolveServerFunctionViaProxy(def, state, key, base) {
       const args = resolveArgs();
       onEffectCleanup(() => {});
       doResolve(args)
-        .then((/** @type {any} */ result) => {
+        .then((/** @type {unknown} */ result) => {
           s.value = result;
         })
-        .catch((/** @type {any} */ e) => console.error("Jx server proxy:", e));
+        .catch((/** @type {unknown} */ e) => console.error("Jx server proxy:", e));
     });
   } else {
     doResolve(resolveArgs())
-      .then((/** @type {any} */ result) => {
+      .then((/** @type {unknown} */ result) => {
         s.value = result;
       })
-      .catch((/** @type {any} */ e) => console.error("Jx server proxy:", e));
+      .catch((/** @type {unknown} */ e) => console.error("Jx server proxy:", e));
   }
   return s;
 }
@@ -1398,7 +1494,7 @@ async function resolveServerFunctionViaProxy(def, state, key, base) {
  *
  * @param {string} ref
  * @param {Record<string, any>} state - Reactive scope proxy (or child scope)
- * @returns {any}
+ * @returns {unknown}
  */
 export function resolveRef(ref, state) {
   if (typeof ref !== "string") return ref;
@@ -1426,7 +1522,7 @@ export function resolveRef(ref, state) {
 /**
  * Check if v is a Vue ref (including computed).
  *
- * @param {any} v
+ * @param {unknown} v
  * @returns {boolean}
  */
 export function isSignal(v) {
@@ -1434,11 +1530,15 @@ export function isSignal(v) {
 }
 
 /**
- * @param {any} v
+ * @param {unknown} v
  * @returns {boolean}
  */
 function isRefObj(v) {
-  return v !== null && typeof v === "object" && typeof v.$ref === "string";
+  return (
+    v !== null &&
+    typeof v === "object" &&
+    typeof (/** @type {Record<string, unknown>} */ (v).$ref) === "string"
+  );
 }
 
 /**
@@ -1450,12 +1550,12 @@ function isNestedSelector(k) {
 }
 
 /**
- * @param {any} obj
+ * @param {unknown} obj
  * @param {string} path
- * @returns {any}
+ * @returns {unknown}
  */
 function getPath(obj, path) {
-  return path.split(/[./]/).reduce((o, k) => o?.[k], obj);
+  return path.split(/[./]/).reduce((o, k) => /** @type {Record<string, unknown>} */ (o)?.[k], obj);
 }
 
 /**
@@ -1484,7 +1584,7 @@ export function camelToKebab(s) {
 /**
  * Convert a style rules object to a CSS text string (skipping nested selectors).
  *
- * @param {Record<string, any>} rules
+ * @param {Record<string, unknown> | object} rules
  * @returns {string}
  */
 export function toCSSText(rules) {
@@ -1630,8 +1730,8 @@ export async function defineElement(source, base) {
 
       // Merge $props set as JS properties by parent before connection
       for (const key of Object.keys(def.state ?? {})) {
-        if (key in this && /** @type {any} */ (this)[key] !== undefined) {
-          state[key] = /** @type {any} */ (this)[key];
+        if (key in this && /** @type {Record<string, unknown>} */ (this)[key] !== undefined) {
+          state[key] = /** @type {Record<string, unknown>} */ (this)[key];
         }
       }
       // Set up property getters/setters that forward into reactive state
@@ -1639,7 +1739,7 @@ export async function defineElement(source, base) {
         if (!(key in HTMLElement.prototype)) {
           Object.defineProperty(this, key, {
             get: () => state[key],
-            set: (/** @type {any} */ v) => {
+            set: (/** @type {unknown} */ v) => {
               state[key] = v;
             },
             configurable: true,
@@ -1647,7 +1747,7 @@ export async function defineElement(source, base) {
         }
       }
 
-      /** @type {any} */ (this)._state = state;
+      /** @type {Record<string, unknown>} */ (this)._state = state;
 
       // Capture light DOM children (for slot distribution) before rendering
       const slottedChildren = Array.from(this.childNodes);
@@ -1677,16 +1777,16 @@ export async function defineElement(source, base) {
     }
 
     disconnectedCallback() {
-      /** @type {any} */
-      const self = this;
+      /** @type {{ _state?: Record<string, any> }} */
+      const self = /** @type {{ _state?: Record<string, any> }} */ (/** @type {unknown} */ (this));
       if (typeof self._state?.onUnmount === "function") {
         self._state.onUnmount(self._state);
       }
     }
 
     adoptedCallback() {
-      /** @type {any} */
-      const self = this;
+      /** @type {{ _state?: Record<string, any> }} */
+      const self = /** @type {{ _state?: Record<string, any> }} */ (/** @type {unknown} */ (this));
       if (typeof self._state?.onAdopted === "function") {
         self._state.onAdopted(self._state);
       }
@@ -1697,8 +1797,8 @@ export async function defineElement(source, base) {
       /** @type {string | null} */ oldVal,
       /** @type {string | null} */ newVal,
     ) {
-      /** @type {any} */
-      const self = this;
+      /** @type {{ _state?: Record<string, any> }} */
+      const self = /** @type {{ _state?: Record<string, any> }} */ (/** @type {unknown} */ (this));
       if (!self._state || oldVal === newVal) return;
       const camelKey = name.replace(
         /-([a-z])/g,
@@ -1720,31 +1820,30 @@ export async function defineElement(source, base) {
  *
  * @param {Record<string, any>} def
  * @param {Record<string, any>} state
- * @param {any} [options]
- * @param {any[]} [path]
+ * @param {JxRenderOptions} [options]
+ * @param {JxPath} [path]
  * @returns {HTMLElement}
  */
 function renderCustomElementWithProps(def, state, options, path) {
-  /** @type {any} */
   const el = document.createElement(def.tagName);
 
-  if (options?.onNodeCreated) options.onNodeCreated(el, path, def);
+  if (options?.onNodeCreated) options.onNodeCreated(el, path ?? [], def);
 
   // Set JS properties from $props (before connection)
   for (const [key, val] of Object.entries(def.$props ?? {})) {
     if (isRefObj(val)) {
       const resolved = resolveRef(val.$ref, state);
-      el[key] = resolved;
+      /** @type {Record<string, unknown>} */ (el)[key] = resolved;
       // Reactive forwarding: re-set the property when the source changes
       effect(() => {
-        el[key] = resolveRef(val.$ref, state);
+        /** @type {Record<string, unknown>} */ (el)[key] = resolveRef(val.$ref, state);
       });
     } else if (isTemplateString(val)) {
       effect(() => {
-        el[key] = evaluateTemplate(val, state);
+        /** @type {Record<string, unknown>} */ (el)[key] = evaluateTemplate(val, state);
       });
     } else {
-      el[key] = val;
+      /** @type {Record<string, unknown>} */ (el)[key] = val;
     }
   }