@ktjs/core 0.22.2 → 0.23.0

package/dist/index.d.ts

@@ -21,6 +21,10 @@ declare class KTRef<T> {
      */
     get value(): T;
     set value(newValue: T);
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback: RefChangeHandler<T>): void;
     removeOnChange(callback: RefChangeHandler<T>): boolean;
 }
@@ -29,9 +33,11 @@ declare const isKTRef: <T = any>(obj: any) => obj is KTRef<T>;
  * Reference to the created HTML element.
  * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
  * - can alse be used to store normal values, but it is not reactive.
+ * - if the value is already a `KTRef`, it will be returned **directly**.
  * @param value mostly an HTMLElement
  */
-declare function ref<T = JSX.Element>(value?: T, onChange?: RefChangeHandler<T>): KTRef<T>;
+declare function ref<T = JSX.Element>(value?: T | KTRef<T>, onChange?: RefChangeHandler<T>): KTRef<T>;
+declare function deref<T = JSX.Element>(value: T | KTRef<T>): T;
 type KTSurfaceRef<T extends Object> = {
     [K in keyof T]: KTRef<T[K]>;
 } & {
@@ -45,6 +51,10 @@ type KTSurfaceRef<T extends Object> = {
  * - `obj.a.b` is not reactive
  */
 declare const surfaceRef: <T extends Object>(obj: T) => KTSurfaceRef<T>;
+/**
+ * Assert k-model to be a ref object
+ */
+declare const $modelOrRef: <T = any>(props: any, defaultValue?: T) => KTRef<T>;
 
 type HTML<T extends (HTMLTag | SVGTag | MathMLTag) & otherstring> = T extends SVGTag
   ? SVGElementTagNameMap[T]
@@ -85,6 +95,12 @@ interface KTBaseAttribute {
    */
   'k-model'?: KTRef<any>;
 
+  /**
+   * Directly apply html string to `innerHTML`.
+   * - Would be reactive if `KTRef` instance is provided
+   */
+  'k-html'?: any;
+
   // # normal HTML attributes
   id?: string;
   class?: string;
@@ -162,7 +178,7 @@ type KTComponent = (
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.23.0 (Last Update: 2026.02.03 17:15:01.812)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -1467,5 +1483,5 @@ interface KTForProps<T> {
  */
 declare function KTFor<T>(props: KTForProps<T>): KTForElement;
 
-export { Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, h, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
+export { $modelOrRef, Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, deref, h, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
 export type { EventHandler, HTMLTag, InputElementTag, KTAttribute, KTForElement, KTForProps, KTRawAttr, KTRawContent, KTRawContents, KTSurfaceRef, MathMLTag, SVGTag };

package/dist/index.iife.js

@@ -8,6 +8,7 @@ var __ktjs_core__ = (function (exports) {
 
     // DOM manipulation utilities
     // # dom natives
+    const $isNode = (x) => x?.nodeType > 0;
     /**
      * & Remove `bind` because it is shockingly slower than wrapper
      * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -54,8 +55,9 @@ var __ktjs_core__ = (function (exports) {
     };
 
     // Shared utilities and cached native methods for kt.js framework
+    // import './misc/symbol-polyfill.js';
     // Re-export all utilities
-    Object.defineProperty(window, '__ktjs__', { value: '0.22.2' });
+    Object.defineProperty(window, '__ktjs__', { value: '0.22.3' });
 
     class KTRef {
         /**
@@ -97,7 +99,14 @@ var __ktjs_core__ = (function (exports) {
                 this._onChanges[i](newValue, oldValue);
             }
         }
+        /**
+         * Register a callback when the value changes
+         * @param callback (newValue, oldValue) => xxx
+         */
         addOnChange(callback) {
+            if (typeof callback !== 'function') {
+                throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
+            }
             this._onChanges.push(callback);
         }
         removeOnChange(callback) {
@@ -110,18 +119,26 @@ var __ktjs_core__ = (function (exports) {
             return false;
         }
     }
-    const isKTRef = (obj) => {
-        return typeof obj === 'object' && obj !== null && obj.isKT === true;
-    };
+    const isKTRef = (obj) => obj?.isKT === true;
     /**
      * Reference to the created HTML element.
      * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
      * - can alse be used to store normal values, but it is not reactive.
+     * - if the value is already a `KTRef`, it will be returned **directly**.
      * @param value mostly an HTMLElement
      */
     function ref(value, onChange) {
+        if (isKTRef(value)) {
+            if (onChange) {
+                value.addOnChange(onChange);
+            }
+            return value;
+        }
         return new KTRef(value, onChange ? [onChange] : []);
     }
+    function deref(value) {
+        return isKTRef(value) ? value.value : value;
+    }
     function kcollect() {
         const newObj = {};
         const entries = $entries(this);
@@ -146,6 +163,21 @@ var __ktjs_core__ = (function (exports) {
         }
         return newObj;
     };
+    // # asserts
+    /**
+     * Assert k-model to be a ref object
+     */
+    const $modelOrRef = (props, defaultValue) => {
+        // & props is an object. Won't use it in any other place
+        if ('k-model' in props) {
+            const kmodel = props['k-model'];
+            if (!kmodel?.isKT) {
+                throw new Error(`[kt.js error] k-model data must be a KTRef object, please use 'ref(...)' to wrap it.`);
+            }
+            return kmodel;
+        }
+        return ref(defaultValue);
+    };
 
     const booleanHandler = (element, key, value) => {
         if (key in element) {
@@ -205,13 +237,24 @@ var __ktjs_core__ = (function (exports) {
                 }
             }
         }
+        if ('k-html' in attr) {
+            const html = attr['k-html'];
+            if (isKTRef(html)) {
+                element.innerHTML = html.value;
+                html.addOnChange((v) => (element.innerHTML = v));
+            }
+            else {
+                element.innerHTML = html;
+            }
+        }
         for (const key in attr) {
             if (key === 'class' ||
                 key === 'className' ||
                 key === 'style' ||
                 key === 'children' ||
                 key === 'k-if' ||
-                key.startsWith('k-model') ||
+                key === 'k-model' ||
+                key === 'k-html' ||
                 key === 'ref') {
                 continue;
             }
@@ -222,6 +265,7 @@ var __ktjs_core__ = (function (exports) {
             }
             // normal attributes
             else {
+                // todo 这里也可以绑定ref的
                 (handlers[key] || defaultHandler)(element, key, o);
             }
         }
@@ -238,13 +282,25 @@ var __ktjs_core__ = (function (exports) {
         }
     }
 
+    const assureNode = (o) => ($isNode(o) ? o : document.createTextNode(o));
     function apdSingle(element, c) {
         // & JSX should ignore false, undefined, and null
         if (c === false || c === undefined || c === null) {
             return;
         }
-        if (typeof c === 'object' && c !== null && 'isKT' in c) {
-            $append.call(element, c.value);
+        if (isKTRef(c)) {
+            let node = assureNode(c.value);
+            $append.call(element, node);
+            c.addOnChange((newValue, oldValue) => {
+                if ($isNode(newValue) && $isNode(oldValue)) {
+                    // & this case is handled automically in `class KTRef`
+                    // todo 2 cases might be able to merge into 1
+                    return;
+                }
+                const oldNode = node;
+                node = assureNode(newValue);
+                oldNode.replaceWith(node);
+            });
         }
         else {
             $append.call(element, c);
@@ -330,7 +386,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+     * @version 0.23.0 (Last Update: 2026.02.03 17:15:01.812)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -704,12 +760,14 @@ var __ktjs_core__ = (function (exports) {
         return result;
     }
 
+    exports.$modelOrRef = $modelOrRef;
     exports.Fragment = Fragment;
     exports.KTAsync = KTAsync;
     exports.KTFor = KTFor;
     exports.KTRef = KTRef;
     exports.createElement = h;
     exports.createRedrawable = createRedrawable;
+    exports.deref = deref;
     exports.h = h;
     exports.isKTRef = isKTRef;
     exports.jsx = jsx;

package/dist/index.legacy.js

@@ -8,6 +8,7 @@ var __ktjs_core__ = (function (exports) {
 
     // DOM manipulation utilities
     // # dom natives
+    const $isNode = (x) => x?.nodeType > 0;
     /**
      * & Remove `bind` because it is shockingly slower than wrapper
      * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -54,8 +55,9 @@ var __ktjs_core__ = (function (exports) {
     };
 
     // Shared utilities and cached native methods for kt.js framework
+    // import './misc/symbol-polyfill.js';
     // Re-export all utilities
-    Object.defineProperty(window, '__ktjs__', { value: '0.22.2' });
+    Object.defineProperty(window, '__ktjs__', { value: '0.22.3' });
 
     var KTRef = /** @class */ (function () {
         function KTRef(_value, _onChanges) {
@@ -93,7 +95,14 @@ var __ktjs_core__ = (function (exports) {
             enumerable: false,
             configurable: true
         });
+        /**
+         * Register a callback when the value changes
+         * @param callback (newValue, oldValue) => xxx
+         */
         KTRef.prototype.addOnChange = function (callback) {
+            if (typeof callback !== 'function') {
+                throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
+            }
             this._onChanges.push(callback);
         };
         KTRef.prototype.removeOnChange = function (callback) {
@@ -107,18 +116,26 @@ var __ktjs_core__ = (function (exports) {
         };
         return KTRef;
     }());
-    var isKTRef = function (obj) {
-        return typeof obj === 'object' && obj !== null && obj.isKT === true;
-    };
+    var isKTRef = function (obj) { return (obj === null || obj === void 0 ? void 0 : obj.isKT) === true; };
     /**
      * Reference to the created HTML element.
      * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
      * - can alse be used to store normal values, but it is not reactive.
+     * - if the value is already a `KTRef`, it will be returned **directly**.
      * @param value mostly an HTMLElement
      */
     function ref(value, onChange) {
+        if (isKTRef(value)) {
+            if (onChange) {
+                value.addOnChange(onChange);
+            }
+            return value;
+        }
         return new KTRef(value, onChange ? [onChange] : []);
     }
+    function deref(value) {
+        return isKTRef(value) ? value.value : value;
+    }
     function kcollect() {
         var newObj = {};
         var entries = $entries(this);
@@ -143,6 +160,21 @@ var __ktjs_core__ = (function (exports) {
         }
         return newObj;
     };
+    // # asserts
+    /**
+     * Assert k-model to be a ref object
+     */
+    var $modelOrRef = function (props, defaultValue) {
+        // & props is an object. Won't use it in any other place
+        if ('k-model' in props) {
+            var kmodel = props['k-model'];
+            if (!(kmodel === null || kmodel === void 0 ? void 0 : kmodel.isKT)) {
+                throw new Error("[kt.js error] k-model data must be a KTRef object, please use 'ref(...)' to wrap it.");
+            }
+            return kmodel;
+        }
+        return ref(defaultValue);
+    };
 
     var booleanHandler = function (element, key, value) {
         if (key in element) {
@@ -204,13 +236,24 @@ var __ktjs_core__ = (function (exports) {
                 }
             }
         }
+        if ('k-html' in attr) {
+            var html = attr['k-html'];
+            if (isKTRef(html)) {
+                element.innerHTML = html.value;
+                html.addOnChange(function (v) { return (element.innerHTML = v); });
+            }
+            else {
+                element.innerHTML = html;
+            }
+        }
         for (var key in attr) {
             if (key === 'class' ||
                 key === 'className' ||
                 key === 'style' ||
                 key === 'children' ||
                 key === 'k-if' ||
-                key.startsWith('k-model') ||
+                key === 'k-model' ||
+                key === 'k-html' ||
                 key === 'ref') {
                 continue;
             }
@@ -221,6 +264,7 @@ var __ktjs_core__ = (function (exports) {
             }
             // normal attributes
             else {
+                // todo 这里也可以绑定ref的
                 (handlers[key] || defaultHandler)(element, key, o);
             }
         }
@@ -237,13 +281,25 @@ var __ktjs_core__ = (function (exports) {
         }
     }
 
+    var assureNode = function (o) { return ($isNode(o) ? o : document.createTextNode(o)); };
     function apdSingle(element, c) {
         // & JSX should ignore false, undefined, and null
         if (c === false || c === undefined || c === null) {
             return;
         }
-        if (typeof c === 'object' && c !== null && 'isKT' in c) {
-            $append.call(element, c.value);
+        if (isKTRef(c)) {
+            var node_1 = assureNode(c.value);
+            $append.call(element, node_1);
+            c.addOnChange(function (newValue, oldValue) {
+                if ($isNode(newValue) && $isNode(oldValue)) {
+                    // & this case is handled automically in `class KTRef`
+                    // todo 2 cases might be able to merge into 1
+                    return;
+                }
+                var oldNode = node_1;
+                node_1 = assureNode(newValue);
+                oldNode.replaceWith(node_1);
+            });
         }
         else {
             $append.call(element, c);
@@ -332,7 +388,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+     * @version 0.23.0 (Last Update: 2026.02.03 17:15:01.812)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -713,12 +769,14 @@ var __ktjs_core__ = (function (exports) {
         return result;
     }
 
+    exports.$modelOrRef = $modelOrRef;
     exports.Fragment = Fragment;
     exports.KTAsync = KTAsync;
     exports.KTFor = KTFor;
     exports.KTRef = KTRef;
     exports.createElement = h;
     exports.createRedrawable = createRedrawable;
+    exports.deref = deref;
     exports.h = h;
     exports.isKTRef = isKTRef;
     exports.jsx = jsx;

package/dist/index.mjs

@@ -5,6 +5,7 @@ const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then
 
 // DOM manipulation utilities
 // # dom natives
+const $isNode = (x) => x?.nodeType > 0;
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
  * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -51,8 +52,9 @@ const applyModel = (element, valueRef, propName, eventName) => {
 };
 
 // Shared utilities and cached native methods for kt.js framework
+// import './misc/symbol-polyfill.js';
 // Re-export all utilities
-Object.defineProperty(window, '__ktjs__', { value: '0.22.2' });
+Object.defineProperty(window, '__ktjs__', { value: '0.22.3' });
 
 class KTRef {
     /**
@@ -94,7 +96,14 @@ class KTRef {
             this._onChanges[i](newValue, oldValue);
         }
     }
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback) {
+        if (typeof callback !== 'function') {
+            throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
+        }
         this._onChanges.push(callback);
     }
     removeOnChange(callback) {
@@ -107,18 +116,26 @@ class KTRef {
         return false;
     }
 }
-const isKTRef = (obj) => {
-    return typeof obj === 'object' && obj !== null && obj.isKT === true;
-};
+const isKTRef = (obj) => obj?.isKT === true;
 /**
  * Reference to the created HTML element.
  * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
  * - can alse be used to store normal values, but it is not reactive.
+ * - if the value is already a `KTRef`, it will be returned **directly**.
  * @param value mostly an HTMLElement
  */
 function ref(value, onChange) {
+    if (isKTRef(value)) {
+        if (onChange) {
+            value.addOnChange(onChange);
+        }
+        return value;
+    }
     return new KTRef(value, onChange ? [onChange] : []);
 }
+function deref(value) {
+    return isKTRef(value) ? value.value : value;
+}
 function kcollect() {
     const newObj = {};
     const entries = $entries(this);
@@ -143,6 +160,21 @@ const surfaceRef = (obj) => {
     }
     return newObj;
 };
+// # asserts
+/**
+ * Assert k-model to be a ref object
+ */
+const $modelOrRef = (props, defaultValue) => {
+    // & props is an object. Won't use it in any other place
+    if ('k-model' in props) {
+        const kmodel = props['k-model'];
+        if (!kmodel?.isKT) {
+            throw new Error(`[kt.js error] k-model data must be a KTRef object, please use 'ref(...)' to wrap it.`);
+        }
+        return kmodel;
+    }
+    return ref(defaultValue);
+};
 
 const booleanHandler = (element, key, value) => {
     if (key in element) {
@@ -202,13 +234,24 @@ function attrIsObject(element, attr) {
             }
         }
     }
+    if ('k-html' in attr) {
+        const html = attr['k-html'];
+        if (isKTRef(html)) {
+            element.innerHTML = html.value;
+            html.addOnChange((v) => (element.innerHTML = v));
+        }
+        else {
+            element.innerHTML = html;
+        }
+    }
     for (const key in attr) {
         if (key === 'class' ||
             key === 'className' ||
             key === 'style' ||
             key === 'children' ||
             key === 'k-if' ||
-            key.startsWith('k-model') ||
+            key === 'k-model' ||
+            key === 'k-html' ||
             key === 'ref') {
             continue;
         }
@@ -219,6 +262,7 @@ function attrIsObject(element, attr) {
         }
         // normal attributes
         else {
+            // todo 这里也可以绑定ref的
             (handlers[key] || defaultHandler)(element, key, o);
         }
     }
@@ -235,13 +279,25 @@ function applyAttr(element, attr) {
     }
 }
 
+const assureNode = (o) => ($isNode(o) ? o : document.createTextNode(o));
 function apdSingle(element, c) {
     // & JSX should ignore false, undefined, and null
     if (c === false || c === undefined || c === null) {
         return;
     }
-    if (typeof c === 'object' && c !== null && 'isKT' in c) {
-        $append.call(element, c.value);
+    if (isKTRef(c)) {
+        let node = assureNode(c.value);
+        $append.call(element, node);
+        c.addOnChange((newValue, oldValue) => {
+            if ($isNode(newValue) && $isNode(oldValue)) {
+                // & this case is handled automically in `class KTRef`
+                // todo 2 cases might be able to merge into 1
+                return;
+            }
+            const oldNode = node;
+            node = assureNode(newValue);
+            oldNode.replaceWith(node);
+        });
     }
     else {
         $append.call(element, c);
@@ -327,7 +383,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.23.0 (Last Update: 2026.02.03 17:15:01.812)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -701,4 +757,4 @@ function getSequence(arr) {
     return result;
 }
 
-export { Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, h, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
+export { $modelOrRef, Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, deref, h, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };

package/dist/jsx/index.d.ts

@@ -19,6 +19,10 @@ declare class KTRef<T> {
      */
     get value(): T;
     set value(newValue: T);
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback: RefChangeHandler<T>): void;
     removeOnChange(callback: RefChangeHandler<T>): boolean;
 }
@@ -27,9 +31,11 @@ declare const isKTRef: <T = any>(obj: any) => obj is KTRef<T>;
  * Reference to the created HTML element.
  * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
  * - can alse be used to store normal values, but it is not reactive.
+ * - if the value is already a `KTRef`, it will be returned **directly**.
  * @param value mostly an HTMLElement
  */
-declare function ref<T = JSX.Element>(value?: T, onChange?: RefChangeHandler<T>): KTRef<T>;
+declare function ref<T = JSX.Element>(value?: T | KTRef<T>, onChange?: RefChangeHandler<T>): KTRef<T>;
+declare function deref<T = JSX.Element>(value: T | KTRef<T>): T;
 type KTSurfaceRef<T extends Object> = {
     [K in keyof T]: KTRef<T[K]>;
 } & {
@@ -43,6 +49,10 @@ type KTSurfaceRef<T extends Object> = {
  * - `obj.a.b` is not reactive
  */
 declare const surfaceRef: <T extends Object>(obj: T) => KTSurfaceRef<T>;
+/**
+ * Assert k-model to be a ref object
+ */
+declare const $modelOrRef: <T = any>(props: any, defaultValue?: T) => KTRef<T>;
 
 type HTML<T extends (HTMLTag | SVGTag | MathMLTag) & otherstring> = T extends SVGTag
   ? SVGElementTagNameMap[T]
@@ -77,6 +87,12 @@ interface KTBaseAttribute {
    */
   'k-model'?: KTRef<any>;
 
+  /**
+   * Directly apply html string to `innerHTML`.
+   * - Would be reactive if `KTRef` instance is provided
+   */
+  'k-html'?: any;
+
   // # normal HTML attributes
   id?: string;
   class?: string;
@@ -146,7 +162,7 @@ type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.23.0 (Last Update: 2026.02.03 17:15:01.812)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -1425,5 +1441,5 @@ declare global {
   }
 }
 
-export { Fragment, KTRef, h as createElement, createRedrawable, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
+export { $modelOrRef, Fragment, KTRef, h as createElement, createRedrawable, deref, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
 export type { KTSurfaceRef };

package/dist/jsx/index.mjs

@@ -5,6 +5,7 @@ const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then
 
 // DOM manipulation utilities
 // # dom natives
+const $isNode = (x) => x?.nodeType > 0;
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
  * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -51,8 +52,9 @@ const applyModel = (element, valueRef, propName, eventName) => {
 };
 
 // Shared utilities and cached native methods for kt.js framework
+// import './misc/symbol-polyfill.js';
 // Re-export all utilities
-Object.defineProperty(window, '__ktjs__', { value: '0.22.2' });
+Object.defineProperty(window, '__ktjs__', { value: '0.22.3' });
 
 class KTRef {
     /**
@@ -94,7 +96,14 @@ class KTRef {
             this._onChanges[i](newValue, oldValue);
         }
     }
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback) {
+        if (typeof callback !== 'function') {
+            throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
+        }
         this._onChanges.push(callback);
     }
     removeOnChange(callback) {
@@ -107,18 +116,26 @@ class KTRef {
         return false;
     }
 }
-const isKTRef = (obj) => {
-    return typeof obj === 'object' && obj !== null && obj.isKT === true;
-};
+const isKTRef = (obj) => obj?.isKT === true;
 /**
  * Reference to the created HTML element.
  * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
  * - can alse be used to store normal values, but it is not reactive.
+ * - if the value is already a `KTRef`, it will be returned **directly**.
  * @param value mostly an HTMLElement
  */
 function ref(value, onChange) {
+    if (isKTRef(value)) {
+        if (onChange) {
+            value.addOnChange(onChange);
+        }
+        return value;
+    }
     return new KTRef(value, onChange ? [onChange] : []);
 }
+function deref(value) {
+    return isKTRef(value) ? value.value : value;
+}
 function kcollect() {
     const newObj = {};
     const entries = $entries(this);
@@ -143,6 +160,21 @@ const surfaceRef = (obj) => {
     }
     return newObj;
 };
+// # asserts
+/**
+ * Assert k-model to be a ref object
+ */
+const $modelOrRef = (props, defaultValue) => {
+    // & props is an object. Won't use it in any other place
+    if ('k-model' in props) {
+        const kmodel = props['k-model'];
+        if (!kmodel?.isKT) {
+            throw new Error(`[kt.js error] k-model data must be a KTRef object, please use 'ref(...)' to wrap it.`);
+        }
+        return kmodel;
+    }
+    return ref(defaultValue);
+};
 
 const booleanHandler = (element, key, value) => {
     if (key in element) {
@@ -202,13 +234,24 @@ function attrIsObject(element, attr) {
             }
         }
     }
+    if ('k-html' in attr) {
+        const html = attr['k-html'];
+        if (isKTRef(html)) {
+            element.innerHTML = html.value;
+            html.addOnChange((v) => (element.innerHTML = v));
+        }
+        else {
+            element.innerHTML = html;
+        }
+    }
     for (const key in attr) {
         if (key === 'class' ||
             key === 'className' ||
             key === 'style' ||
             key === 'children' ||
             key === 'k-if' ||
-            key.startsWith('k-model') ||
+            key === 'k-model' ||
+            key === 'k-html' ||
             key === 'ref') {
             continue;
         }
@@ -219,6 +262,7 @@ function attrIsObject(element, attr) {
         }
         // normal attributes
         else {
+            // todo 这里也可以绑定ref的
             (handlers[key] || defaultHandler)(element, key, o);
         }
     }
@@ -235,13 +279,25 @@ function applyAttr(element, attr) {
     }
 }
 
+const assureNode = (o) => ($isNode(o) ? o : document.createTextNode(o));
 function apdSingle(element, c) {
     // & JSX should ignore false, undefined, and null
     if (c === false || c === undefined || c === null) {
         return;
     }
-    if (typeof c === 'object' && c !== null && 'isKT' in c) {
-        $append.call(element, c.value);
+    if (isKTRef(c)) {
+        let node = assureNode(c.value);
+        $append.call(element, node);
+        c.addOnChange((newValue, oldValue) => {
+            if ($isNode(newValue) && $isNode(oldValue)) {
+                // & this case is handled automically in `class KTRef`
+                // todo 2 cases might be able to merge into 1
+                return;
+            }
+            const oldNode = node;
+            node = assureNode(newValue);
+            oldNode.replaceWith(node);
+        });
     }
     else {
         $append.call(element, c);
@@ -327,7 +383,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.23.0 (Last Update: 2026.02.03 17:15:01.812)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -477,4 +533,4 @@ function createRedrawable(creator) {
     return elRef;
 }
 
-export { Fragment, KTRef, h as createElement, createRedrawable, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
+export { $modelOrRef, Fragment, KTRef, h as createElement, createRedrawable, deref, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };

package/dist/jsx/jsx-runtime.d.ts

@@ -19,6 +19,10 @@ declare class KTRef<T> {
      */
     get value(): T;
     set value(newValue: T);
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback: RefChangeHandler<T>): void;
     removeOnChange(callback: RefChangeHandler<T>): boolean;
 }
@@ -56,6 +60,12 @@ interface KTBaseAttribute {
    */
   'k-model'?: KTRef<any>;
 
+  /**
+   * Directly apply html string to `innerHTML`.
+   * - Would be reactive if `KTRef` instance is provided
+   */
+  'k-html'?: any;
+
   // # normal HTML attributes
   id?: string;
   class?: string;
@@ -125,7 +135,7 @@ type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.23.0 (Last Update: 2026.02.03 17:15:01.812)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/dist/jsx/jsx-runtime.mjs

@@ -4,6 +4,7 @@ const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then
 
 // DOM manipulation utilities
 // # dom natives
+const $isNode = (x) => x?.nodeType > 0;
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
  * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -50,8 +51,9 @@ const applyModel = (element, valueRef, propName, eventName) => {
 };
 
 // Shared utilities and cached native methods for kt.js framework
+// import './misc/symbol-polyfill.js';
 // Re-export all utilities
-Object.defineProperty(window, '__ktjs__', { value: '0.22.2' });
+Object.defineProperty(window, '__ktjs__', { value: '0.22.3' });
 
 class KTRef {
     /**
@@ -93,7 +95,14 @@ class KTRef {
             this._onChanges[i](newValue, oldValue);
         }
     }
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback) {
+        if (typeof callback !== 'function') {
+            throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
+        }
         this._onChanges.push(callback);
     }
     removeOnChange(callback) {
@@ -106,16 +115,18 @@ class KTRef {
         return false;
     }
 }
-const isKTRef = (obj) => {
-    return typeof obj === 'object' && obj !== null && obj.isKT === true;
-};
+const isKTRef = (obj) => obj?.isKT === true;
 /**
  * Reference to the created HTML element.
  * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
  * - can alse be used to store normal values, but it is not reactive.
+ * - if the value is already a `KTRef`, it will be returned **directly**.
  * @param value mostly an HTMLElement
  */
 function ref(value, onChange) {
+    if (isKTRef(value)) {
+        return value;
+    }
     return new KTRef(value, []);
 }
 
@@ -177,13 +188,24 @@ function attrIsObject(element, attr) {
             }
         }
     }
+    if ('k-html' in attr) {
+        const html = attr['k-html'];
+        if (isKTRef(html)) {
+            element.innerHTML = html.value;
+            html.addOnChange((v) => (element.innerHTML = v));
+        }
+        else {
+            element.innerHTML = html;
+        }
+    }
     for (const key in attr) {
         if (key === 'class' ||
             key === 'className' ||
             key === 'style' ||
             key === 'children' ||
             key === 'k-if' ||
-            key.startsWith('k-model') ||
+            key === 'k-model' ||
+            key === 'k-html' ||
             key === 'ref') {
             continue;
         }
@@ -194,6 +216,7 @@ function attrIsObject(element, attr) {
         }
         // normal attributes
         else {
+            // todo 这里也可以绑定ref的
             (handlers[key] || defaultHandler)(element, key, o);
         }
     }
@@ -210,13 +233,25 @@ function applyAttr(element, attr) {
     }
 }
 
+const assureNode = (o) => ($isNode(o) ? o : document.createTextNode(o));
 function apdSingle(element, c) {
     // & JSX should ignore false, undefined, and null
     if (c === false || c === undefined || c === null) {
         return;
     }
-    if (typeof c === 'object' && c !== null && 'isKT' in c) {
-        $append.call(element, c.value);
+    if (isKTRef(c)) {
+        let node = assureNode(c.value);
+        $append.call(element, node);
+        c.addOnChange((newValue, oldValue) => {
+            if ($isNode(newValue) && $isNode(oldValue)) {
+                // & this case is handled automically in `class KTRef`
+                // todo 2 cases might be able to merge into 1
+                return;
+            }
+            const oldNode = node;
+            node = assureNode(newValue);
+            oldNode.replaceWith(node);
+        });
     }
     else {
         $append.call(element, c);
@@ -302,7 +337,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.23.0 (Last Update: 2026.02.03 17:15:01.812)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ktjs/core",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "description": "Core functionality for kt.js - DOM manipulation utilities with JSX/TSX support",
   "type": "module",
   "module": "./dist/index.mjs",
@@ -44,7 +44,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ktjs/shared": "0.22.2"
+    "@ktjs/shared": "0.22.3"
   },
   "scripts": {
     "build": "rollup -c rollup.config.mjs",