@ktjs/core 0.22.0 → 0.22.5

package/dist/index.d.ts

@@ -7,6 +7,8 @@ type HTMLTag = keyof HTMLElementTagNameMap;
 type SVGTag = keyof SVGElementTagNameMap;
 type MathMLTag = keyof MathMLElementTagNameMap;
 
+type InputElementTag = 'input' | 'select' | 'textarea';
+
 type RefChangeHandler<T> = (newValue: T, oldValue: T) => void;
 declare class KTRef<T> {
     /**
@@ -19,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;
 }
@@ -27,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]>;
 } & {
@@ -43,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]
@@ -160,7 +172,7 @@ type KTComponent = (
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.0 (Last Update: 2026.02.02 17:11:04.703)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -1465,5 +1477,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 type { EventHandler, HTMLTag, KTAttribute, KTForElement, KTForProps, KTRawAttr, KTRawContent, KTRawContents, KTSurfaceRef };
+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

@@ -6,10 +6,8 @@ var __ktjs_core__ = (function (exports) {
     const $entries = Object.entries;
     const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then === 'function';
 
-    // Error handling utilities
-    const $throw = (message) => {
-        throw new Error('@ktjs/shared: ' + message);
-    };
+    // DOM manipulation utilities
+    // # dom natives
     /**
      * & Remove `bind` because it is shockingly slower than wrapper
      * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -46,10 +44,18 @@ var __ktjs_core__ = (function (exports) {
             }
         };
     const { get: $buttonDisabledGetter, set: $buttonDisabledSetter } = Object.getOwnPropertyDescriptor(HTMLButtonElement.prototype, 'disabled');
+    /**
+     * Used for `k-model`
+     */
+    const applyModel = (element, valueRef, propName, eventName) => {
+        element[propName] = valueRef.value; // initialize
+        valueRef.addOnChange((newValue) => (element[propName] = newValue));
+        element.addEventListener(eventName, () => (valueRef.value = element[propName]));
+    };
 
     // Shared utilities and cached native methods for kt.js framework
     // Re-export all utilities
-    Object.defineProperty(window, '@ktjs/shared', { value: '0.20.2' });
+    Object.defineProperty(window, '__ktjs__', { value: '0.22.2' });
 
     class KTRef {
         /**
@@ -91,7 +97,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) {
@@ -104,18 +117,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);
@@ -140,6 +161,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) {
@@ -228,7 +264,7 @@ var __ktjs_core__ = (function (exports) {
             attrIsObject(element, attr);
         }
         else {
-            throw new Error('kt.js: attr must be an object.');
+            throw new Error('[kt.js error] attr must be an object.');
         }
     }
 
@@ -283,27 +319,28 @@ var __ktjs_core__ = (function (exports) {
         }
     }
 
-    function register(element, valueRef, propName, eventName) {
-        element[propName] = valueRef.value; // initialize
-        valueRef.addOnChange((newValue) => (element[propName] = newValue));
-        element.addEventListener(eventName, () => (valueRef.value = element[propName]));
-    }
-    function applyModel(element, valueRef) {
+    function applyKModel(element, valueRef) {
+        if (!isKTRef(valueRef)) {
+            console.warn('[kt.js warn] k-model value must be a KTRef.');
+            return;
+        }
         if (element instanceof HTMLInputElement) {
             if (element.type === 'radio' || element.type === 'checkbox') {
-                register(element, valueRef, 'checked', 'change');
+                applyModel(element, valueRef, 'checked', 'change');
             }
             else {
-                register(element, valueRef, 'value', 'input');
+                applyModel(element, valueRef, 'value', 'input');
             }
         }
         else if (element instanceof HTMLSelectElement) {
-            register(element, valueRef, 'value', 'change');
+            applyModel(element, valueRef, 'value', 'change');
         }
         else if (element instanceof HTMLTextAreaElement) {
-            register(element, valueRef, 'value', 'input');
+            applyModel(element, valueRef, 'value', 'input');
+        }
+        else {
+            console.warn('[kt.js warn] not supported element for k-model:');
         }
-        console.warn('[kt.js warn] not supported element for k-model:', element.tagName);
     }
 
     const htmlCreator = (tag) => document.createElement(tag);
@@ -323,7 +360,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.22.0 (Last Update: 2026.02.02 17:11:04.703)
+     * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -332,7 +369,7 @@ var __ktjs_core__ = (function (exports) {
      */
     const h = (tag, attr, content) => {
         if (typeof tag !== 'string') {
-            $throw('tagName must be a string.');
+            throw new Error('[kt.js error] tagName must be a string.');
         }
         if (attr) {
             if (SVG_ATTR_FLAG in attr) {
@@ -355,10 +392,10 @@ var __ktjs_core__ = (function (exports) {
         if (typeof attr === 'object' && attr !== null && 'k-model' in attr) {
             const kmodel = attr['k-model'];
             if (isKTRef(kmodel)) {
-                applyModel(element, kmodel);
+                applyKModel(element, kmodel);
             }
             else {
-                $throw('k-model value must be a KTRef.');
+                throw new Error('[kt.js error] k-model value must be a KTRef.');
             }
         }
         return element;
@@ -413,7 +450,7 @@ var __ktjs_core__ = (function (exports) {
      * Note: kt.js doesn't have a real Fragment concept,
      */
     function Fragment(_props) {
-        throw new Error("kt.js doesn't have a Fragment concept");
+        throw new Error("[kt.js error] doesn't have a Fragment concept");
         // const { children } = props ?? {};
         // if (!children) {
         //   return ;
@@ -697,12 +734,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

@@ -6,10 +6,8 @@ var __ktjs_core__ = (function (exports) {
     const $entries = Object.entries;
     const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then === 'function';
 
-    // Error handling utilities
-    const $throw = (message) => {
-        throw new Error('@ktjs/shared: ' + message);
-    };
+    // DOM manipulation utilities
+    // # dom natives
     /**
      * & Remove `bind` because it is shockingly slower than wrapper
      * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -46,10 +44,18 @@ var __ktjs_core__ = (function (exports) {
             }
         };
     const { get: $buttonDisabledGetter, set: $buttonDisabledSetter } = Object.getOwnPropertyDescriptor(HTMLButtonElement.prototype, 'disabled');
+    /**
+     * Used for `k-model`
+     */
+    const applyModel = (element, valueRef, propName, eventName) => {
+        element[propName] = valueRef.value; // initialize
+        valueRef.addOnChange((newValue) => (element[propName] = newValue));
+        element.addEventListener(eventName, () => (valueRef.value = element[propName]));
+    };
 
     // Shared utilities and cached native methods for kt.js framework
     // Re-export all utilities
-    Object.defineProperty(window, '@ktjs/shared', { value: '0.20.2' });
+    Object.defineProperty(window, '__ktjs__', { value: '0.22.2' });
 
     var KTRef = /** @class */ (function () {
         function KTRef(_value, _onChanges) {
@@ -87,7 +93,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) {
@@ -101,18 +114,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);
@@ -137,6 +158,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) {
@@ -227,7 +263,7 @@ var __ktjs_core__ = (function (exports) {
             attrIsObject(element, attr);
         }
         else {
-            throw new Error('kt.js: attr must be an object.');
+            throw new Error('[kt.js error] attr must be an object.');
         }
     }
 
@@ -285,27 +321,28 @@ var __ktjs_core__ = (function (exports) {
         }
     }
 
-    function register(element, valueRef, propName, eventName) {
-        element[propName] = valueRef.value; // initialize
-        valueRef.addOnChange(function (newValue) { return (element[propName] = newValue); });
-        element.addEventListener(eventName, function () { return (valueRef.value = element[propName]); });
-    }
-    function applyModel(element, valueRef) {
+    function applyKModel(element, valueRef) {
+        if (!isKTRef(valueRef)) {
+            console.warn('[kt.js warn] k-model value must be a KTRef.');
+            return;
+        }
         if (element instanceof HTMLInputElement) {
             if (element.type === 'radio' || element.type === 'checkbox') {
-                register(element, valueRef, 'checked', 'change');
+                applyModel(element, valueRef, 'checked', 'change');
             }
             else {
-                register(element, valueRef, 'value', 'input');
+                applyModel(element, valueRef, 'value', 'input');
             }
         }
         else if (element instanceof HTMLSelectElement) {
-            register(element, valueRef, 'value', 'change');
+            applyModel(element, valueRef, 'value', 'change');
         }
         else if (element instanceof HTMLTextAreaElement) {
-            register(element, valueRef, 'value', 'input');
+            applyModel(element, valueRef, 'value', 'input');
+        }
+        else {
+            console.warn('[kt.js warn] not supported element for k-model:');
         }
-        console.warn('[kt.js warn] not supported element for k-model:', element.tagName);
     }
 
     var htmlCreator = function (tag) { return document.createElement(tag); };
@@ -325,7 +362,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.22.0 (Last Update: 2026.02.02 17:11:04.703)
+     * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -334,7 +371,7 @@ var __ktjs_core__ = (function (exports) {
      */
     var h = function (tag, attr, content) {
         if (typeof tag !== 'string') {
-            $throw('tagName must be a string.');
+            throw new Error('[kt.js error] tagName must be a string.');
         }
         if (attr) {
             if (SVG_ATTR_FLAG in attr) {
@@ -357,10 +394,10 @@ var __ktjs_core__ = (function (exports) {
         if (typeof attr === 'object' && attr !== null && 'k-model' in attr) {
             var kmodel = attr['k-model'];
             if (isKTRef(kmodel)) {
-                applyModel(element, kmodel);
+                applyKModel(element, kmodel);
             }
             else {
-                $throw('k-model value must be a KTRef.');
+                throw new Error('[kt.js error] k-model value must be a KTRef.');
             }
         }
         return element;
@@ -415,7 +452,7 @@ var __ktjs_core__ = (function (exports) {
      * Note: kt.js doesn't have a real Fragment concept,
      */
     function Fragment(_props) {
-        throw new Error("kt.js doesn't have a Fragment concept");
+        throw new Error("[kt.js error] doesn't have a Fragment concept");
         // const { children } = props ?? {};
         // if (!children) {
         //   return ;
@@ -706,12 +743,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

@@ -3,10 +3,8 @@ const $isArray = Array.isArray;
 const $entries = Object.entries;
 const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then === 'function';
 
-// Error handling utilities
-const $throw = (message) => {
-    throw new Error('@ktjs/shared: ' + message);
-};
+// DOM manipulation utilities
+// # dom natives
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
  * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -43,10 +41,18 @@ const $append = // for ie 9/10/11
         }
     };
 const { get: $buttonDisabledGetter, set: $buttonDisabledSetter } = Object.getOwnPropertyDescriptor(HTMLButtonElement.prototype, 'disabled');
+/**
+ * Used for `k-model`
+ */
+const applyModel = (element, valueRef, propName, eventName) => {
+    element[propName] = valueRef.value; // initialize
+    valueRef.addOnChange((newValue) => (element[propName] = newValue));
+    element.addEventListener(eventName, () => (valueRef.value = element[propName]));
+};
 
 // Shared utilities and cached native methods for kt.js framework
 // Re-export all utilities
-Object.defineProperty(window, '@ktjs/shared', { value: '0.20.2' });
+Object.defineProperty(window, '__ktjs__', { value: '0.22.2' });
 
 class KTRef {
     /**
@@ -88,7 +94,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) {
@@ -101,18 +114,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);
@@ -137,6 +158,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) {
@@ -225,7 +261,7 @@ function applyAttr(element, attr) {
         attrIsObject(element, attr);
     }
     else {
-        throw new Error('kt.js: attr must be an object.');
+        throw new Error('[kt.js error] attr must be an object.');
     }
 }
 
@@ -280,27 +316,28 @@ function applyContent(element, content) {
     }
 }
 
-function register(element, valueRef, propName, eventName) {
-    element[propName] = valueRef.value; // initialize
-    valueRef.addOnChange((newValue) => (element[propName] = newValue));
-    element.addEventListener(eventName, () => (valueRef.value = element[propName]));
-}
-function applyModel(element, valueRef) {
+function applyKModel(element, valueRef) {
+    if (!isKTRef(valueRef)) {
+        console.warn('[kt.js warn] k-model value must be a KTRef.');
+        return;
+    }
     if (element instanceof HTMLInputElement) {
         if (element.type === 'radio' || element.type === 'checkbox') {
-            register(element, valueRef, 'checked', 'change');
+            applyModel(element, valueRef, 'checked', 'change');
         }
         else {
-            register(element, valueRef, 'value', 'input');
+            applyModel(element, valueRef, 'value', 'input');
         }
     }
     else if (element instanceof HTMLSelectElement) {
-        register(element, valueRef, 'value', 'change');
+        applyModel(element, valueRef, 'value', 'change');
     }
     else if (element instanceof HTMLTextAreaElement) {
-        register(element, valueRef, 'value', 'input');
+        applyModel(element, valueRef, 'value', 'input');
+    }
+    else {
+        console.warn('[kt.js warn] not supported element for k-model:');
     }
-    console.warn('[kt.js warn] not supported element for k-model:', element.tagName);
 }
 
 const htmlCreator = (tag) => document.createElement(tag);
@@ -320,7 +357,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.0 (Last Update: 2026.02.02 17:11:04.703)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -329,7 +366,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  */
 const h = (tag, attr, content) => {
     if (typeof tag !== 'string') {
-        $throw('tagName must be a string.');
+        throw new Error('[kt.js error] tagName must be a string.');
     }
     if (attr) {
         if (SVG_ATTR_FLAG in attr) {
@@ -352,10 +389,10 @@ const h = (tag, attr, content) => {
     if (typeof attr === 'object' && attr !== null && 'k-model' in attr) {
         const kmodel = attr['k-model'];
         if (isKTRef(kmodel)) {
-            applyModel(element, kmodel);
+            applyKModel(element, kmodel);
         }
         else {
-            $throw('k-model value must be a KTRef.');
+            throw new Error('[kt.js error] k-model value must be a KTRef.');
         }
     }
     return element;
@@ -410,7 +447,7 @@ function jsx(tag, props) {
  * Note: kt.js doesn't have a real Fragment concept,
  */
 function Fragment(_props) {
-    throw new Error("kt.js doesn't have a Fragment concept");
+    throw new Error("[kt.js error] doesn't have a Fragment concept");
     // const { children } = props ?? {};
     // if (!children) {
     //   return ;
@@ -694,4 +731,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]
@@ -146,7 +156,7 @@ type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.0 (Last Update: 2026.02.02 17:11:04.703)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -1425,5 +1435,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

@@ -3,10 +3,8 @@ const $isArray = Array.isArray;
 const $entries = Object.entries;
 const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then === 'function';
 
-// Error handling utilities
-const $throw = (message) => {
-    throw new Error('@ktjs/shared: ' + message);
-};
+// DOM manipulation utilities
+// # dom natives
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
  * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -43,10 +41,18 @@ const $append = // for ie 9/10/11
         }
     };
 const { get: $buttonDisabledGetter, set: $buttonDisabledSetter } = Object.getOwnPropertyDescriptor(HTMLButtonElement.prototype, 'disabled');
+/**
+ * Used for `k-model`
+ */
+const applyModel = (element, valueRef, propName, eventName) => {
+    element[propName] = valueRef.value; // initialize
+    valueRef.addOnChange((newValue) => (element[propName] = newValue));
+    element.addEventListener(eventName, () => (valueRef.value = element[propName]));
+};
 
 // Shared utilities and cached native methods for kt.js framework
 // Re-export all utilities
-Object.defineProperty(window, '@ktjs/shared', { value: '0.20.2' });
+Object.defineProperty(window, '__ktjs__', { value: '0.22.2' });
 
 class KTRef {
     /**
@@ -88,7 +94,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) {
@@ -101,18 +114,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);
@@ -137,6 +158,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) {
@@ -225,7 +261,7 @@ function applyAttr(element, attr) {
         attrIsObject(element, attr);
     }
     else {
-        throw new Error('kt.js: attr must be an object.');
+        throw new Error('[kt.js error] attr must be an object.');
     }
 }
 
@@ -280,27 +316,28 @@ function applyContent(element, content) {
     }
 }
 
-function register(element, valueRef, propName, eventName) {
-    element[propName] = valueRef.value; // initialize
-    valueRef.addOnChange((newValue) => (element[propName] = newValue));
-    element.addEventListener(eventName, () => (valueRef.value = element[propName]));
-}
-function applyModel(element, valueRef) {
+function applyKModel(element, valueRef) {
+    if (!isKTRef(valueRef)) {
+        console.warn('[kt.js warn] k-model value must be a KTRef.');
+        return;
+    }
     if (element instanceof HTMLInputElement) {
         if (element.type === 'radio' || element.type === 'checkbox') {
-            register(element, valueRef, 'checked', 'change');
+            applyModel(element, valueRef, 'checked', 'change');
         }
         else {
-            register(element, valueRef, 'value', 'input');
+            applyModel(element, valueRef, 'value', 'input');
         }
     }
     else if (element instanceof HTMLSelectElement) {
-        register(element, valueRef, 'value', 'change');
+        applyModel(element, valueRef, 'value', 'change');
     }
     else if (element instanceof HTMLTextAreaElement) {
-        register(element, valueRef, 'value', 'input');
+        applyModel(element, valueRef, 'value', 'input');
+    }
+    else {
+        console.warn('[kt.js warn] not supported element for k-model:');
     }
-    console.warn('[kt.js warn] not supported element for k-model:', element.tagName);
 }
 
 const htmlCreator = (tag) => document.createElement(tag);
@@ -320,7 +357,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.0 (Last Update: 2026.02.02 17:11:04.703)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -329,7 +366,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  */
 const h = (tag, attr, content) => {
     if (typeof tag !== 'string') {
-        $throw('tagName must be a string.');
+        throw new Error('[kt.js error] tagName must be a string.');
     }
     if (attr) {
         if (SVG_ATTR_FLAG in attr) {
@@ -352,10 +389,10 @@ const h = (tag, attr, content) => {
     if (typeof attr === 'object' && attr !== null && 'k-model' in attr) {
         const kmodel = attr['k-model'];
         if (isKTRef(kmodel)) {
-            applyModel(element, kmodel);
+            applyKModel(element, kmodel);
         }
         else {
-            $throw('k-model value must be a KTRef.');
+            throw new Error('[kt.js error] k-model value must be a KTRef.');
         }
     }
     return element;
@@ -410,7 +447,7 @@ function jsx(tag, props) {
  * Note: kt.js doesn't have a real Fragment concept,
  */
 function Fragment(_props) {
-    throw new Error("kt.js doesn't have a Fragment concept");
+    throw new Error("[kt.js error] doesn't have a Fragment concept");
     // const { children } = props ?? {};
     // if (!children) {
     //   return ;
@@ -470,4 +507,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;
 }
@@ -125,7 +129,7 @@ type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.0 (Last Update: 2026.02.02 17:11:04.703)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/dist/jsx/jsx-runtime.mjs

@@ -2,10 +2,8 @@
 const $isArray = Array.isArray;
 const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then === 'function';
 
-// Error handling utilities
-const $throw = (message) => {
-    throw new Error('@ktjs/shared: ' + message);
-};
+// DOM manipulation utilities
+// # dom natives
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
  * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -42,10 +40,18 @@ const $append = // for ie 9/10/11
         }
     };
 const { get: $buttonDisabledGetter, set: $buttonDisabledSetter } = Object.getOwnPropertyDescriptor(HTMLButtonElement.prototype, 'disabled');
+/**
+ * Used for `k-model`
+ */
+const applyModel = (element, valueRef, propName, eventName) => {
+    element[propName] = valueRef.value; // initialize
+    valueRef.addOnChange((newValue) => (element[propName] = newValue));
+    element.addEventListener(eventName, () => (valueRef.value = element[propName]));
+};
 
 // Shared utilities and cached native methods for kt.js framework
 // Re-export all utilities
-Object.defineProperty(window, '@ktjs/shared', { value: '0.20.2' });
+Object.defineProperty(window, '__ktjs__', { value: '0.22.2' });
 
 class KTRef {
     /**
@@ -87,7 +93,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) {
@@ -100,16 +113,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, []);
 }
 
@@ -200,7 +215,7 @@ function applyAttr(element, attr) {
         attrIsObject(element, attr);
     }
     else {
-        throw new Error('kt.js: attr must be an object.');
+        throw new Error('[kt.js error] attr must be an object.');
     }
 }
 
@@ -255,27 +270,28 @@ function applyContent(element, content) {
     }
 }
 
-function register(element, valueRef, propName, eventName) {
-    element[propName] = valueRef.value; // initialize
-    valueRef.addOnChange((newValue) => (element[propName] = newValue));
-    element.addEventListener(eventName, () => (valueRef.value = element[propName]));
-}
-function applyModel(element, valueRef) {
+function applyKModel(element, valueRef) {
+    if (!isKTRef(valueRef)) {
+        console.warn('[kt.js warn] k-model value must be a KTRef.');
+        return;
+    }
     if (element instanceof HTMLInputElement) {
         if (element.type === 'radio' || element.type === 'checkbox') {
-            register(element, valueRef, 'checked', 'change');
+            applyModel(element, valueRef, 'checked', 'change');
         }
         else {
-            register(element, valueRef, 'value', 'input');
+            applyModel(element, valueRef, 'value', 'input');
         }
     }
     else if (element instanceof HTMLSelectElement) {
-        register(element, valueRef, 'value', 'change');
+        applyModel(element, valueRef, 'value', 'change');
     }
     else if (element instanceof HTMLTextAreaElement) {
-        register(element, valueRef, 'value', 'input');
+        applyModel(element, valueRef, 'value', 'input');
+    }
+    else {
+        console.warn('[kt.js warn] not supported element for k-model:');
     }
-    console.warn('[kt.js warn] not supported element for k-model:', element.tagName);
 }
 
 const htmlCreator = (tag) => document.createElement(tag);
@@ -295,7 +311,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.0 (Last Update: 2026.02.02 17:11:04.703)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -304,7 +320,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  */
 const h = (tag, attr, content) => {
     if (typeof tag !== 'string') {
-        $throw('tagName must be a string.');
+        throw new Error('[kt.js error] tagName must be a string.');
     }
     if (attr) {
         if (SVG_ATTR_FLAG in attr) {
@@ -327,10 +343,10 @@ const h = (tag, attr, content) => {
     if (typeof attr === 'object' && attr !== null && 'k-model' in attr) {
         const kmodel = attr['k-model'];
         if (isKTRef(kmodel)) {
-            applyModel(element, kmodel);
+            applyKModel(element, kmodel);
         }
         else {
-            $throw('k-model value must be a KTRef.');
+            throw new Error('[kt.js error] k-model value must be a KTRef.');
         }
     }
     return element;
@@ -385,7 +401,7 @@ function jsx(tag, props) {
  * Note: kt.js doesn't have a real Fragment concept,
  */
 function Fragment(_props) {
-    throw new Error("kt.js doesn't have a Fragment concept");
+    throw new Error("[kt.js error] doesn't have a Fragment concept");
     // const { children } = props ?? {};
     // if (!children) {
     //   return ;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ktjs/core",
-  "version": "0.22.0",
+  "version": "0.22.5",
   "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.20.2"
+    "@ktjs/shared": "0.22.2"
   },
   "scripts": {
     "build": "rollup -c rollup.config.mjs",