@jxsuite/runtime 0.18.0 → 0.20.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)
  */
@@ -232,7 +232,7 @@ 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}\``);
@@ -254,7 +254,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) {
@@ -281,15 +281,15 @@ async function resolveFunction(def, state, key, base) {
     if (_moduleCache.has(src)) {
       mod = _moduleCache.get(src);
     } else {
-      try {
-        mod = await import(src);
-      } catch {
-        if (base) {
-          const resolvedSrc = new URL(src, base).href;
+      if (base) {
+        const resolvedSrc = new URL(src, base).href;
+        try {
           mod = await import(resolvedSrc);
-        } else {
-          throw new Error(`Jx: failed to import '$src' "${src}" for "${key}"`);
+        } catch {
+          mod = await import(src);
         }
+      } else {
+        mod = await import(src);
       }
       _moduleCache.set(src, mod);
     }
@@ -299,8 +299,18 @@ async function resolveFunction(def, state, key, base) {
     }
   }
 
-  // Detect computed: body contains a return statement
-  if (def.body && /\breturn\b/.test(def.body)) {
+  // Detect computed: body contains a return statement, or $src function introspection.
+  // Functions with parameters (event handlers, callbacks) are never computed.
+  const hasParams = (def.parameters ?? def.arguments ?? []).length > 0;
+  let isComputed = false;
+  if (!hasParams) {
+    if (def.body) {
+      isComputed = /\breturn\b/.test(def.body);
+    } else if (fn) {
+      isComputed = fn.length <= 1 && /\breturn\b/.test(fn.toString());
+    }
+  }
+  if (isComputed) {
     return computed(() => fn(state));
   }
 
@@ -343,6 +353,8 @@ export const RESERVED_KEYS = new Set([
   "$ref",
   "$props",
   "$elements",
+  "$title",
+  "$description",
   "$switch",
   "$prototype",
   "$src",
@@ -373,7 +385,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) {
@@ -436,7 +448,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) {
@@ -480,19 +492,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;
   }
@@ -500,12 +515,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;
 }
 
 /**
@@ -527,6 +542,7 @@ export function applyStyle(el, styleDef, mediaQueries = {}, state = {}) {
   for (const [prop, val] of Object.entries(styleDef)) {
     if (prop.startsWith("@")) media[prop] = val;
     else if (isNestedSelector(prop)) nested[prop] = val;
+    else if (val !== null && typeof val === "object" && !Array.isArray(val)) nested[prop] = val;
     else if (prop.startsWith("--")) {
       if (isTemplateString(val))
         effect(() => {
@@ -535,9 +551,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;
@@ -549,13 +566,32 @@ export function applyStyle(el, styleDef, mediaQueries = {}, state = {}) {
 
   let css = "";
 
+  function emitNested(/** @type {string} */ scope, /** @type {Record<string, any>} */ rules) {
+    const props = toCSSText(rules);
+    if (props) css += `${scope} { ${props} }\n`;
+    for (const [sel, sub] of Object.entries(rules)) {
+      if (sub === null || typeof sub !== "object" || Array.isArray(sub)) continue;
+      if (sel.startsWith("@")) continue;
+      const resolved = sel.startsWith("&")
+        ? sel.replace("&", scope)
+        : sel.startsWith("[")
+          ? `${scope}${sel}`
+          : sel.startsWith(":") || sel.startsWith(".")
+            ? `${scope}${sel}`
+            : `${scope} ${sel}`;
+      emitNested(resolved, sub);
+    }
+  }
+
   for (const [sel, rules] of Object.entries(nested)) {
     const resolved = sel.startsWith("&")
       ? sel.replace("&", `[data-jx="${uid}"]`)
       : sel.startsWith("[")
         ? `[data-jx="${uid}"]${sel}`
-        : `[data-jx="${uid}"] ${sel}`;
-    css += `${resolved} { ${toCSSText(rules)} }\n`;
+        : sel.startsWith(":") || sel.startsWith(".")
+          ? `[data-jx="${uid}"]${sel}`
+          : `[data-jx="${uid}"] ${sel}`;
+    emitNested(resolved, rules);
   }
 
   for (const [key, rules] of Object.entries(media)) {
@@ -565,15 +601,27 @@ export function applyStyle(el, styleDef, mediaQueries = {}, state = {}) {
       : key.slice(1);
     const scope = `[data-jx="${uid}"]`;
     css += `@media ${query} { ${scope} { ${toCSSText(rules)} } }\n`;
-    for (const [sel, nestedRules] of Object.entries(rules)) {
-      if (!isNestedSelector(sel)) continue;
-      const resolved = sel.startsWith("&")
-        ? sel.replace("&", scope)
-        : sel.startsWith("[")
-          ? `${scope}${sel}`
-          : `${scope} ${sel}`;
-      css += `@media ${query} { ${resolved} { ${toCSSText(nestedRules)} } }\n`;
+
+    function emitMediaNested(
+      /** @type {string} */ parentSel,
+      /** @type {Record<string, any>} */ obj,
+    ) {
+      for (const [sel, sub] of Object.entries(obj)) {
+        if (sub === null || typeof sub !== "object" || Array.isArray(sub)) continue;
+        if (sel.startsWith("@")) continue;
+        const resolved = sel.startsWith("&")
+          ? sel.replace("&", parentSel)
+          : sel.startsWith("[")
+            ? `${parentSel}${sel}`
+            : sel.startsWith(":") || sel.startsWith(".")
+              ? `${parentSel}${sel}`
+              : `${parentSel} ${sel}`;
+        const props = toCSSText(sub);
+        if (props) css += `@media ${query} { ${resolved} { ${props} } }\n`;
+        emitMediaNested(resolved, sub);
+      }
     }
+    emitMediaNested(scope, rules);
   }
 
   const tag = document.createElement("style");
@@ -603,7 +651,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) {
@@ -628,11 +676,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) => {
@@ -655,7 +705,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) {
@@ -671,7 +721,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;
 
@@ -688,7 +738,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;
@@ -713,7 +763,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 ─────────────────────────────────────────────────
@@ -723,10 +773,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) {
@@ -742,7 +792,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 = () =>
@@ -758,8 +808,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) {
@@ -858,22 +908,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)),
         };
       };
@@ -932,7 +982,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;
@@ -956,7 +1006,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;
@@ -1005,7 +1055,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;
     });
   }
@@ -1020,7 +1070,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;
@@ -1072,7 +1122,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;
     });
   }
@@ -1084,7 +1134,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 ?? {};
@@ -1094,16 +1144,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;
@@ -1113,13 +1181,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 ?? "");
@@ -1128,23 +1218,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;
 }
 
 /**
@@ -1156,7 +1250,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>} */
@@ -1165,7 +1259,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) =>
@@ -1195,17 +1291,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;
 }
@@ -1220,7 +1316,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;
@@ -1254,12 +1350,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;
   };
@@ -1272,7 +1368,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(() => {});
@@ -1292,17 +1388,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;
   };
@@ -1331,17 +1427,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;
 }
@@ -1354,7 +1450,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;
@@ -1382,7 +1478,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) {
@@ -1390,11 +1486,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"
+  );
 }
 
 /**
@@ -1406,12 +1506,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);
 }
 
 /**
@@ -1440,12 +1540,12 @@ 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) {
   return Object.entries(rules)
-    .filter(([k]) => !isNestedSelector(k))
+    .filter(([k, v]) => !isNestedSelector(k) && (v === null || typeof v !== "object"))
     .map(([p, v]) => `${camelToKebab(p)}: ${v}`)
     .join("; ");
 }
@@ -1586,8 +1686,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
@@ -1595,7 +1695,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,
@@ -1603,7 +1703,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);
@@ -1633,16 +1733,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);
       }
@@ -1653,8 +1753,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,
@@ -1676,31 +1776,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;
     }
   }