tina4-nodejs 3.13.51 → 3.13.53

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.50)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.53)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.27 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.53 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.51",
+  "version": "3.13.53",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - 54 built-in features, zero dependencies",
   "keywords": [

package/packages/core/public/js/frond.js

@@ -558,6 +558,132 @@ var _frondModule = (() => {
       }
     });
   }
+  function _liveKey(el) {
+    const d = el.dataset;
+    return d && d.key ? d.key : null;
+  }
+  function _liveSyncAttrs(oldNode, newNode) {
+    const na = newNode.attributes;
+    for (let i = 0; i < na.length; i++) {
+      const a = na[i];
+      if (oldNode.getAttribute(a.name) !== a.value) oldNode.setAttribute(a.name, a.value);
+    }
+    const oa = Array.prototype.slice.call(oldNode.attributes);
+    oa.forEach(function(a) {
+      if (!newNode.hasAttribute(a.name)) oldNode.removeAttribute(a.name);
+    });
+  }
+  function _liveMorphNode(oldNode, newNode) {
+    const tag = newNode.tagName;
+    if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return;
+    _liveSyncAttrs(oldNode, newNode);
+    if (oldNode.children.length || newNode.children.length) {
+      _liveReconcile(oldNode, newNode);
+    } else if (oldNode.innerHTML !== newNode.innerHTML) {
+      oldNode.innerHTML = newNode.innerHTML;
+    }
+  }
+  function _liveReconcile(parent, next) {
+    const oldKids = Array.prototype.slice.call(parent.children);
+    const newKids = Array.prototype.slice.call(next.children);
+    const oldByKey = {};
+    oldKids.forEach(function(c) {
+      const k = _liveKey(c);
+      if (k) oldByKey[k] = c;
+    });
+    const order = [];
+    for (let i = 0; i < newKids.length; i++) {
+      const nk = newKids[i];
+      const k = _liveKey(nk);
+      let match = null;
+      if (k && oldByKey[k]) {
+        match = oldByKey[k];
+      } else if (!k && oldKids[i] && !_liveKey(oldKids[i]) && oldKids[i].tagName === nk.tagName) {
+        match = oldKids[i];
+      }
+      if (match && match.tagName === nk.tagName) {
+        _liveMorphNode(match, nk);
+        reused.push(match);
+        order.push(match);
+      } else {
+        order.push(nk);
+      }
+    }
+    let cursor = parent.firstElementChild;
+    for (let i = 0; i < order.length; i++) {
+      const node = order[i];
+      if (node === cursor) {
+        cursor = cursor.nextElementSibling;
+      } else {
+        parent.insertBefore(node, cursor);
+      }
+    }
+    oldKids.forEach(function(c) {
+      if (order.indexOf(c) === -1 && c.parentNode === parent) parent.removeChild(c);
+    });
+    void reused;
+  }
+  function _liveSwap(container, html) {
+    const tmp = document.createElement("div");
+    tmp.innerHTML = html;
+    if (!tmp.children.length || !container.children.length) {
+      container.innerHTML = html;
+      return;
+    }
+    _liveReconcile(container, tmp);
+  }
+  function _liveWsUrl(path) {
+    if (/^wss?:\/\//.test(path)) return path;
+    const proto = typeof location !== "undefined" && location.protocol === "https:" ? "wss" : "ws";
+    return proto + "://" + location.host + path;
+  }
+  function _liveExtract(msg, name) {
+    if (msg && typeof msg === "object") {
+      if (msg.type === "live") {
+        if (name && msg.name && msg.name !== name) return null;
+        return msg.html != null ? String(msg.html) : null;
+      }
+      return null;
+    }
+    return typeof msg === "string" ? msg : null;
+  }
+  function liveInit(root) {
+    if (typeof document === "undefined") return;
+    const scope = root || document;
+    const blocks = scope.querySelectorAll("[data-frond-live]");
+    Array.prototype.slice.call(blocks).forEach(function(el) {
+      if (el.__frondLive) return;
+      el.__frondLive = true;
+      const mode = el.getAttribute("data-mode");
+      const name = el.getAttribute("data-frond-live");
+      if (mode === "poll") {
+        const src = el.getAttribute("data-src");
+        const interval = (parseInt(el.getAttribute("data-interval"), 10) || 5) * 1e3;
+        const timer = setInterval(function() {
+          if (typeof document !== "undefined" && document.hidden) return;
+          request(src, { method: "GET", onSuccess: function(data) {
+            _liveSwap(el, typeof data === "string" ? data : String(data));
+          } });
+        }, interval);
+        el.__frondLiveStop = function() {
+          clearInterval(timer);
+        };
+      } else if (mode === "ws") {
+        const sock = wsConnect(_liveWsUrl(el.getAttribute("data-ws")));
+        sock.on("message", function(msg) {
+          const h = _liveExtract(msg, name);
+          if (h !== null) _liveSwap(el, h);
+        });
+        el.__frondLiveStop = function() {
+          sock.close();
+        };
+      } else if (mode === "sse") {
+        if (typeof console !== "undefined" && console.warn) {
+          console.warn("[frond.live] sse transport is not wired yet (v1 supports poll and ws); block '" + name + "' shows first paint only. Use poll or ws.");
+        }
+      }
+    });
+  }
   var frond = {
     /** Core HTTP request. */
     request,
@@ -573,6 +699,8 @@ var _frondModule = (() => {
     ws: wsConnect,
     /** Server-Sent Events with auto-reconnect. */
     sse: sseConnect,
+    /** Wire {% live %} blocks (poll/ws) with keyed morph. Auto-runs on DOMContentLoaded. */
+    live: liveInit,
     /** Cookie helpers: get, set, remove. */
     cookie,
     /** Display alert message in #message element. */
@@ -593,8 +721,17 @@ var _frondModule = (() => {
   };
   if (typeof window !== "undefined") {
     window.frond = frond;
+    if (typeof document !== "undefined") {
+      if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", function() {
+          liveInit();
+        });
+      } else {
+        liveInit();
+      }
+    }
   }
   return __toCommonJS(frond_exports);
 })();
-/* Frond v2.1.3 — tina4.com */
+/* Frond v2.2.0 - tina4.com */
 //# sourceMappingURL=frond.js.map

package/packages/core/public/js/frond.min.js

@@ -1,2 +1,2 @@
-var _frondModule=(()=>{var b=Object.defineProperty;var k=Object.getOwnPropertyDescriptor;var x=Object.getOwnPropertyNames;var C=Object.prototype.hasOwnProperty;var O=(o,s)=>{for(var e in s)b(o,e,{get:s[e],enumerable:!0})},M=(o,s,e,t)=>{if(s&&typeof s=="object"||typeof s=="function")for(let n of x(s))!C.call(o,n)&&n!==e&&b(o,n,{get:()=>s[n],enumerable:!(t=k(s,n))||t.enumerable});return o};var q=o=>M(b({},"__esModule",{value:!0}),o);var j={};O(j,{frond:()=>R});var g=null;function w(o,s){let e;typeof s=="function"?e={onSuccess:s}:e=s||{};let t=(e.method||"GET").toUpperCase(),n=new XMLHttpRequest;if(n.open(t,o,!0),g!==null&&n.setRequestHeader("Authorization","Bearer "+g),e.headers)for(let r in e.headers)Object.prototype.hasOwnProperty.call(e.headers,r)&&n.setRequestHeader(r,e.headers[r]);let i=null;e.body!==void 0&&e.body!==null&&(e.body instanceof FormData?i=e.body:typeof e.body=="object"?(i=JSON.stringify(e.body),n.setRequestHeader("Content-Type","application/json; charset=UTF-8")):typeof e.body=="string"&&(i=e.body,n.setRequestHeader("Content-Type","text/plain; charset=UTF-8"))),n.onload=function(){let r=n.getResponseHeader("FreshToken");r&&r!==""&&(g=r);let u=n.response;try{u=JSON.parse(u)}catch{}if(n.responseURL){let c=new URL(o,window.location.href).href;if(n.responseURL!==c){window.location.href=n.responseURL;return}}n.status>=200&&n.status<400?e.onSuccess&&e.onSuccess(u,n.status,n):e.onError&&e.onError(n.status,n)},n.onerror=function(){e.onError&&e.onError(n.status,n)},n.send(i)}function h(o,s){if(!o)return"";let e=new DOMParser,t=o.includes("<html>")?o:"<body>"+o+"</body></html>",i=e.parseFromString(t,"text/html").querySelector("body"),r=i.querySelectorAll("script");if(r.forEach(function(u){u.remove()}),s!==null){let u=document.getElementById(s);return u&&(i.children.length>0?u.replaceChildren.apply(u,Array.from(i.children)):u.innerHTML=i.innerHTML,r.forEach(function(c){let d=document.createElement("script");d.type="text/javascript",d.async=!0,c.src?d.src=c.src:d.textContent=c.textContent,u.appendChild(d)})),""}return r.forEach(function(u){let c=document.createElement("script");c.type="text/javascript",c.async=!0,c.textContent=u.textContent,document.body.appendChild(c)}),i.innerHTML}function H(o,s,e){let t=s||"content";w(o,{method:"GET",onSuccess:function(n,i){if(document.getElementById(t)){let r=h(n,t);e&&e(r,n)}else e&&e(n)}})}function S(o,s,e,t){let n=e||"content";w(o,{method:"POST",body:s,onSuccess:function(i){let r="";if(i&&i.message!==void 0)r=h(i.message,n);else if(document.getElementById(n))r=h(i,n);else{t&&t(i);return}t&&t(r,i)}})}var T={collect:function(o){let s=new FormData,e=document.querySelectorAll("#"+o+" select, #"+o+" input, #"+o+" textarea");for(let t=0;t<e.length;t++){let n=e[t];if(n.name==="formToken"&&g!==null&&(n.value=g),!!n.name)if(n.type==="file"){let i=n.files;if(i)for(let r=0;r<i.length;r++){let u=i[r];if(u!==void 0){let c=n.name;i.length>1&&!c.includes("[")&&(c=c+"[]"),s.append(c,u,u.name)}}}else n.type==="checkbox"||n.type==="radio"?n.checked?s.append(n.name,n.value):n.type!=="radio"&&s.append(n.name,"0"):s.append(n.name,n.value===""?"":n.value)}return s},submit:function(o,s,e,t){let n=T.collect(o);S(s,n,e||"message",t)},show:function(o,s,e,t){let n=o.toUpperCase();(o==="create"||o==="edit")&&(n="GET"),o==="delete"&&(n="DELETE");let i=e||"form";w(s,{method:n,onSuccess:function(r){let u="";if(r&&r.message!==void 0)u=h(r.message,i);else if(document.getElementById(i))u=h(r,i);else{t&&t(r);return}t&&t(u)}})}};function L(o,s){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,protocols:[],onOpen:function(){},onClose:function(){},onError:function(){},...s||{}},t=null,n=!1,i=e.reconnectDelay,r=0,u=null,c={message:[],open:[],close:[],error:[]},d={status:"connecting",send:function(l){if(!t||t.readyState!==WebSocket.OPEN)throw new Error("[frond] WebSocket is not connected");t.send(typeof l=="string"?l:JSON.stringify(l))},on:function(l,a){return c[l]||(c[l]=[]),c[l].push(a),function(){let f=c[l],m=f.indexOf(a);m>=0&&f.splice(m,1)}},close:function(l,a){n=!0,u&&(clearTimeout(u),u=null),t&&t.close(l||1e3,a||""),d.status="closed"}};function y(l){if(typeof l!="string")return l;try{return JSON.parse(l)}catch{return l}}function p(){!e.reconnect||r>=e.maxReconnectAttempts||(r++,d.status="reconnecting",u=setTimeout(function(){u=null,v()},i),i=Math.min(i*2,e.maxReconnectDelay))}function v(){d.status=r>0?"reconnecting":"connecting";try{t=new WebSocket(o,e.protocols)}catch{d.status="closed";return}t.onopen=function(){d.status="open",r=0,i=e.reconnectDelay,e.onOpen();for(let l of c.open)l()},t.onmessage=function(l){let a=y(l.data);for(let f of c.message)f(a)},t.onclose=function(l){d.status="closed",e.onClose(l.code,l.reason);for(let a of c.close)a(l.code,l.reason);n||p()},t.onerror=function(l){e.onError(l);for(let a of c.error)a(l)}}return v(),d}function D(o,s){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,events:[],json:!0,onOpen:function(){},onClose:function(){},onError:function(){},...s||{}},t=null,n=!1,i=e.reconnectDelay,r=0,u=null,c={message:[],open:[],close:[],error:[]},d={status:"connecting",on:function(a,f){return c[a]||(c[a]=[]),c[a].push(f),function(){let m=c[a],E=m.indexOf(f);E>=0&&m.splice(E,1)}},close:function(){n=!0,u&&(clearTimeout(u),u=null),t&&(t.close(),t=null),d.status="closed"}};function y(a){if(!e.json)return a;try{return JSON.parse(a)}catch{return a}}function p(a,f){for(let m of c.message)m(a,f||void 0)}function v(){!e.reconnect||r>=e.maxReconnectAttempts||(r++,d.status="reconnecting",u=setTimeout(function(){u=null,l()},i),i=Math.min(i*2,e.maxReconnectDelay))}function l(){d.status=r>0?"reconnecting":"connecting";try{t=new EventSource(o)}catch{d.status="closed";return}t.onopen=function(){d.status="open",r=0,i=e.reconnectDelay,e.onOpen();for(let a of c.open)a(null)},t.onmessage=function(a){p(y(a.data),null)};for(let a of e.events)t.addEventListener(a,function(f){p(y(f.data),a)});t.onerror=function(a){e.onError(a);for(let f of c.error)f(a);if(t&&t.readyState===2){t=null,d.status="closed",e.onClose();for(let f of c.close)f(null);n||v()}}}return l(),d}var W={set:function(o,s,e){let t="";if(e){let n=new Date;n.setTime(n.getTime()+e*24*60*60*1e3),t="; expires="+n.toUTCString()}document.cookie=o+"="+(s||"")+t+"; path=/"},get:function(o){let s=o+"=",e=document.cookie.split(";");for(let t=0;t<e.length;t++){let n=e[t];for(;n.charAt(0)===" ";)n=n.substring(1);if(n.indexOf(s)===0)return n.substring(s.length)}return null},remove:function(o){document.cookie=o+"=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/"}};function A(o,s){let e=document.getElementById("message");if(!e)return;let t=s||"info";e.innerHTML='<div class="alert alert-'+t+' alert-dismissible">'+o+'<button type="button" class="btn-close" data-t4-dismiss="alert">&times;</button></div>'}function I(o,s,e,t){let n=window.screenLeft!==void 0?window.screenLeft:window.screenX,i=window.screenTop!==void 0?window.screenTop:window.screenY,r=window.innerWidth||document.documentElement.clientWidth||screen.width,u=window.innerHeight||document.documentElement.clientHeight||screen.height,c=r/window.screen.availWidth,d=(r-e)/2/c+n,y=(u-t)/2/c+i,p=window.open(o,s,"directories=no,toolbar=no,location=no,status=no,menubar=no,scrollbars=yes,resizable=yes,width="+e/c+",height="+t/c+",top="+y+",left="+d);return window.focus&&p&&p.focus(),p}function N(o){if(o.indexOf("No data available")>=0){window.alert("No data available for this report.");return}window.open(o,"_blank","toolbar=no,scrollbars=yes,resizable=yes,width=800,height=600,top=0,left=0")}function U(o,s,e,t){w(o,{method:"POST",body:{query:s,variables:e||{}},onSuccess:function(n){t&&t(n.data||null,n.errors||void 0)},onError:function(n){t&&t(null,[{message:"GraphQL request failed with status "+n}])}})}var R={request:w,load:H,post:S,inject:h,form:T,ws:L,sse:D,cookie:W,message:A,popup:I,report:N,graphql:U,get token(){return g},set token(o){g=o}};typeof window<"u"&&(window.frond=R);return q(j);})();
-/* Frond v2.1.3 — tina4.com */
+var _frondModule=(()=>{var E=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var H=Object.prototype.hasOwnProperty;var q=(t,s)=>{for(var e in s)E(t,e,{get:s[e],enumerable:!0})},D=(t,s,e,o)=>{if(s&&typeof s=="object"||typeof s=="function")for(let n of A(s))!H.call(t,n)&&n!==e&&E(t,n,{get:()=>s[n],enumerable:!(o=O(s,n))||o.enumerable});return t};var W=t=>D(E({},"__esModule",{value:!0}),t);var z={};q(z,{frond:()=>L});var y=null;function v(t,s){let e;typeof s=="function"?e={onSuccess:s}:e=s||{};let o=(e.method||"GET").toUpperCase(),n=new XMLHttpRequest;if(n.open(o,t,!0),y!==null&&n.setRequestHeader("Authorization","Bearer "+y),e.headers)for(let u in e.headers)Object.prototype.hasOwnProperty.call(e.headers,u)&&n.setRequestHeader(u,e.headers[u]);let c=null;e.body!==void 0&&e.body!==null&&(e.body instanceof FormData?c=e.body:typeof e.body=="object"?(c=JSON.stringify(e.body),n.setRequestHeader("Content-Type","application/json; charset=UTF-8")):typeof e.body=="string"&&(c=e.body,n.setRequestHeader("Content-Type","text/plain; charset=UTF-8"))),n.onload=function(){let u=n.getResponseHeader("FreshToken");u&&u!==""&&(y=u);let r=n.response;try{r=JSON.parse(r)}catch{}if(n.responseURL){let i=new URL(t,window.location.href).href;if(n.responseURL!==i){window.location.href=n.responseURL;return}}n.status>=200&&n.status<400?e.onSuccess&&e.onSuccess(r,n.status,n):e.onError&&e.onError(n.status,n)},n.onerror=function(){e.onError&&e.onError(n.status,n)},n.send(c)}function h(t,s){if(!t)return"";let e=new DOMParser,o=t.includes("<html>")?t:"<body>"+t+"</body></html>",c=e.parseFromString(o,"text/html").querySelector("body"),u=c.querySelectorAll("script");if(u.forEach(function(r){r.remove()}),s!==null){let r=document.getElementById(s);return r&&(c.children.length>0?r.replaceChildren.apply(r,Array.from(c.children)):r.innerHTML=c.innerHTML,u.forEach(function(i){let l=document.createElement("script");l.type="text/javascript",l.async=!0,i.src?l.src=i.src:l.textContent=i.textContent,r.appendChild(l)})),""}return u.forEach(function(r){let i=document.createElement("script");i.type="text/javascript",i.async=!0,i.textContent=r.textContent,document.body.appendChild(i)}),c.innerHTML}function _(t,s,e){let o=s||"content";v(t,{method:"GET",onSuccess:function(n,c){if(document.getElementById(o)){let u=h(n,o);e&&e(u,n)}else e&&e(n)}})}function R(t,s,e,o){let n=e||"content";v(t,{method:"POST",body:s,onSuccess:function(c){let u="";if(c&&c.message!==void 0)u=h(c.message,n);else if(document.getElementById(n))u=h(c,n);else{o&&o(c);return}o&&o(u,c)}})}var x={collect:function(t){let s=new FormData,e=document.querySelectorAll("#"+t+" select, #"+t+" input, #"+t+" textarea");for(let o=0;o<e.length;o++){let n=e[o];if(n.name==="formToken"&&y!==null&&(n.value=y),!!n.name)if(n.type==="file"){let c=n.files;if(c)for(let u=0;u<c.length;u++){let r=c[u];if(r!==void 0){let i=n.name;c.length>1&&!i.includes("[")&&(i=i+"[]"),s.append(i,r,r.name)}}}else n.type==="checkbox"||n.type==="radio"?n.checked?s.append(n.name,n.value):n.type!=="radio"&&s.append(n.name,"0"):s.append(n.name,n.value===""?"":n.value)}return s},submit:function(t,s,e,o){let n=x.collect(t);R(s,n,e||"message",o)},show:function(t,s,e,o){let n=t.toUpperCase();(t==="create"||t==="edit")&&(n="GET"),t==="delete"&&(n="DELETE");let c=e||"form";v(s,{method:n,onSuccess:function(u){let r="";if(u&&u.message!==void 0)r=h(u.message,c);else if(document.getElementById(c))r=h(u,c);else{o&&o(u);return}o&&o(r)}})}};function M(t,s){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,protocols:[],onOpen:function(){},onClose:function(){},onError:function(){},...s||{}},o=null,n=!1,c=e.reconnectDelay,u=0,r=null,i={message:[],open:[],close:[],error:[]},l={status:"connecting",send:function(f){if(!o||o.readyState!==WebSocket.OPEN)throw new Error("[frond] WebSocket is not connected");o.send(typeof f=="string"?f:JSON.stringify(f))},on:function(f,a){return i[f]||(i[f]=[]),i[f].push(a),function(){let d=i[f],g=d.indexOf(a);g>=0&&d.splice(g,1)}},close:function(f,a){n=!0,r&&(clearTimeout(r),r=null),o&&o.close(f||1e3,a||""),l.status="closed"}};function p(f){if(typeof f!="string")return f;try{return JSON.parse(f)}catch{return f}}function m(){!e.reconnect||u>=e.maxReconnectAttempts||(u++,l.status="reconnecting",r=setTimeout(function(){r=null,w()},c),c=Math.min(c*2,e.maxReconnectDelay))}function w(){l.status=u>0?"reconnecting":"connecting";try{o=new WebSocket(t,e.protocols)}catch{l.status="closed";return}o.onopen=function(){l.status="open",u=0,c=e.reconnectDelay,e.onOpen();for(let f of i.open)f()},o.onmessage=function(f){let a=p(f.data);for(let d of i.message)d(a)},o.onclose=function(f){l.status="closed",e.onClose(f.code,f.reason);for(let a of i.close)a(f.code,f.reason);n||m()},o.onerror=function(f){e.onError(f);for(let a of i.error)a(f)}}return w(),l}function I(t,s){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,events:[],json:!0,onOpen:function(){},onClose:function(){},onError:function(){},...s||{}},o=null,n=!1,c=e.reconnectDelay,u=0,r=null,i={message:[],open:[],close:[],error:[]},l={status:"connecting",on:function(a,d){return i[a]||(i[a]=[]),i[a].push(d),function(){let g=i[a],T=g.indexOf(d);T>=0&&g.splice(T,1)}},close:function(){n=!0,r&&(clearTimeout(r),r=null),o&&(o.close(),o=null),l.status="closed"}};function p(a){if(!e.json)return a;try{return JSON.parse(a)}catch{return a}}function m(a,d){for(let g of i.message)g(a,d||void 0)}function w(){!e.reconnect||u>=e.maxReconnectAttempts||(u++,l.status="reconnecting",r=setTimeout(function(){r=null,f()},c),c=Math.min(c*2,e.maxReconnectDelay))}function f(){l.status=u>0?"reconnecting":"connecting";try{o=new EventSource(t)}catch{l.status="closed";return}o.onopen=function(){l.status="open",u=0,c=e.reconnectDelay,e.onOpen();for(let a of i.open)a(null)},o.onmessage=function(a){m(p(a.data),null)};for(let a of e.events)o.addEventListener(a,function(d){m(p(d.data),a)});o.onerror=function(a){e.onError(a);for(let d of i.error)d(a);if(o&&o.readyState===2){o=null,l.status="closed",e.onClose();for(let d of i.close)d(null);n||w()}}}return f(),l}var U={set:function(t,s,e){let o="";if(e){let n=new Date;n.setTime(n.getTime()+e*24*60*60*1e3),o="; expires="+n.toUTCString()}document.cookie=t+"="+(s||"")+o+"; path=/"},get:function(t){let s=t+"=",e=document.cookie.split(";");for(let o=0;o<e.length;o++){let n=e[o];for(;n.charAt(0)===" ";)n=n.substring(1);if(n.indexOf(s)===0)return n.substring(s.length)}return null},remove:function(t){document.cookie=t+"=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/"}};function j(t,s){let e=document.getElementById("message");if(!e)return;let o=s||"info";e.innerHTML='<div class="alert alert-'+o+' alert-dismissible">'+t+'<button type="button" class="btn-close" data-t4-dismiss="alert">&times;</button></div>'}function B(t,s,e,o){let n=window.screenLeft!==void 0?window.screenLeft:window.screenX,c=window.screenTop!==void 0?window.screenTop:window.screenY,u=window.innerWidth||document.documentElement.clientWidth||screen.width,r=window.innerHeight||document.documentElement.clientHeight||screen.height,i=u/window.screen.availWidth,l=(u-e)/2/i+n,p=(r-o)/2/i+c,m=window.open(t,s,"directories=no,toolbar=no,location=no,status=no,menubar=no,scrollbars=yes,resizable=yes,width="+e/i+",height="+o/i+",top="+p+",left="+l);return window.focus&&m&&m.focus(),m}function P(t){if(t.indexOf("No data available")>=0){window.alert("No data available for this report.");return}window.open(t,"_blank","toolbar=no,scrollbars=yes,resizable=yes,width=800,height=600,top=0,left=0")}function F(t,s,e,o){v(t,{method:"POST",body:{query:s,variables:e||{}},onSuccess:function(n){o&&o(n.data||null,n.errors||void 0)},onError:function(n){o&&o(null,[{message:"GraphQL request failed with status "+n}])}})}function b(t){let s=t.dataset;return s&&s.key?s.key:null}function X(t,s){let e=s.attributes;for(let n=0;n<e.length;n++){let c=e[n];t.getAttribute(c.name)!==c.value&&t.setAttribute(c.name,c.value)}Array.prototype.slice.call(t.attributes).forEach(function(n){s.hasAttribute(n.name)||t.removeAttribute(n.name)})}function G(t,s){let e=s.tagName;e==="INPUT"||e==="TEXTAREA"||e==="SELECT"||(X(t,s),t.children.length||s.children.length?C(t,s):t.innerHTML!==s.innerHTML&&(t.innerHTML=s.innerHTML))}function C(t,s){let e=Array.prototype.slice.call(t.children),o=Array.prototype.slice.call(s.children),n={};e.forEach(function(r){let i=b(r);i&&(n[i]=r)});let c=[];for(let r=0;r<o.length;r++){let i=o[r],l=b(i),p=null;l&&n[l]?p=n[l]:!l&&e[r]&&!b(e[r])&&e[r].tagName===i.tagName&&(p=e[r]),p&&p.tagName===i.tagName?(G(p,i),reused.push(p),c.push(p)):c.push(i)}let u=t.firstElementChild;for(let r=0;r<c.length;r++){let i=c[r];i===u?u=u.nextElementSibling:t.insertBefore(i,u)}e.forEach(function(r){c.indexOf(r)===-1&&r.parentNode===t&&t.removeChild(r)}),reused}function k(t,s){let e=document.createElement("div");if(e.innerHTML=s,!e.children.length||!t.children.length){t.innerHTML=s;return}C(t,e)}function J(t){return/^wss?:\/\//.test(t)?t:(typeof location<"u"&&location.protocol==="https:"?"wss":"ws")+"://"+location.host+t}function N(t,s){return t&&typeof t=="object"?t.type==="live"?s&&t.name&&t.name!==s?null:t.html!=null?String(t.html):null:null:typeof t=="string"?t:null}function S(t){if(typeof document>"u")return;let e=(t||document).querySelectorAll("[data-frond-live]");Array.prototype.slice.call(e).forEach(function(o){if(o.__frondLive)return;o.__frondLive=!0;let n=o.getAttribute("data-mode"),c=o.getAttribute("data-frond-live");if(n==="poll"){let u=o.getAttribute("data-src"),r=(parseInt(o.getAttribute("data-interval"),10)||5)*1e3,i=setInterval(function(){typeof document<"u"&&document.hidden||v(u,{method:"GET",onSuccess:function(l){k(o,typeof l=="string"?l:String(l))}})},r);o.__frondLiveStop=function(){clearInterval(i)}}else if(n==="ws"){let u=M(J(o.getAttribute("data-ws")));u.on("message",function(r){let i=N(r,c);i!==null&&k(o,i)}),o.__frondLiveStop=function(){u.close()}}else n==="sse"&&typeof console<"u"&&console.warn&&console.warn("[frond.live] sse transport is not wired yet (v1 supports poll and ws); block '"+c+"' shows first paint only. Use poll or ws.")})}var L={request:v,load:_,post:R,inject:h,form:x,ws:M,sse:I,live:S,cookie:U,message:j,popup:B,report:P,graphql:F,get token(){return y},set token(t){y=t}};typeof window<"u"&&(window.frond=L,typeof document<"u"&&(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){S()}):S()));return W(z);})();
+/* Frond v2.2.0 - tina4.com */

package/packages/core/src/scss.ts

@@ -131,6 +131,10 @@ function compileString(
   // 7. Evaluate basic math in property values
   scss = evalMath(scss);
 
+  // 7.5. Resolve color functions (lighten/darken/rgba/rgb/mix) — after variable
+  // substitution so a $colour arg is already a hex literal (issue #124).
+  scss = resolveColorFunctions(scss);
+
   // 8. Flatten nested rules
   const css = flattenNesting(scss);
 
@@ -340,6 +344,99 @@ function evalMath(scss: string): string {
   });
 }
 
+// ── Color Functions ──────────────────────────────────────────────
+
+/**
+ * Resolve lighten(), darken(), rgba()/rgb(), and mix() color functions.
+ *
+ * rgba(<hex>, <alpha>) is the damaging case (issue #124): the functional rgba()
+ * notation cannot take a hex, so rgba(#0f3460, 0.12) is invalid CSS and browsers
+ * drop the whole declaration. Convert the hex to its r,g,b components. Runs after
+ * variable substitution so a $colour arg is already a hex literal.
+ */
+function resolveColorFunctions(scss: string): string {
+  scss = scss.replace(/lighten\(\s*([^,]+)\s*,\s*([^)]+)\s*\)/g, (_m, color: string, amt: string) =>
+    adjustLightness(color.trim(), parseFloat(amt.trim().replace(/%$/, "")) / 100)
+  );
+  scss = scss.replace(/darken\(\s*([^,]+)\s*,\s*([^)]+)\s*\)/g, (_m, color: string, amt: string) =>
+    adjustLightness(color.trim(), -(parseFloat(amt.trim().replace(/%$/, "")) / 100))
+  );
+  // rgba(<hex>, <alpha>) — only the two-arg hex form; leave rgba(r,g,b,a) alone.
+  scss = scss.replace(/rgba\(\s*(#[0-9a-fA-F]{3,8})\s*,\s*([\d.]+)\s*\)/g, (whole, hex: string, alpha: string) => {
+    const rgb = hexToRgb(hex);
+    return rgb === null ? whole : `rgba(${rgb[0]}, ${rgb[1]}, ${rgb[2]}, ${alpha.trim()})`;
+  });
+  scss = scss.replace(/rgb\(\s*(#[0-9a-fA-F]{3,8})\s*\)/g, (whole, hex: string) => {
+    const rgb = hexToRgb(hex);
+    return rgb === null ? whole : `rgb(${rgb[0]}, ${rgb[1]}, ${rgb[2]})`;
+  });
+  // mix(<c1>, <c2>[, <weight>]) — Sass weight is c1's proportion (default 50%).
+  scss = scss.replace(
+    /mix\(\s*(#[0-9a-fA-F]{3,8})\s*,\s*(#[0-9a-fA-F]{3,8})\s*(?:,\s*([\d.]+%?)\s*)?\)/g,
+    (whole, h1: string, h2: string, weight?: string) => {
+      const c1 = hexToRgb(h1);
+      const c2 = hexToRgb(h2);
+      if (c1 === null || c2 === null) return whole;
+      const w = weight ? parseFloat(weight.replace(/%$/, "")) / 100 : 0.5;
+      const mixed = [0, 1, 2].map((i) => Math.round(c1[i] * w + c2[i] * (1 - w)));
+      return `#${mixed.map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+    }
+  );
+  return scss;
+}
+
+/** Parse a #rgb / #rrggbb hex string into an [r, g, b] tuple, or null. */
+function hexToRgb(color: string): [number, number, number] | null {
+  let c = color.trim().replace(/^#/, "");
+  if (c.length === 3) {
+    c = c.split("").map((ch) => ch + ch).join("");
+  }
+  if (!/^[0-9a-fA-F]{6}$/.test(c)) return null;
+  return [parseInt(c.slice(0, 2), 16), parseInt(c.slice(2, 4), 16), parseInt(c.slice(4, 6), 16)];
+}
+
+/** Adjust the HSL lightness of a hex color by `amount` (-1..1), return hex.
+ * Truncates (Math.trunc) to match the Python master's int(x*255) byte-for-byte. */
+function adjustLightness(color: string, amount: number): string {
+  const rgb = hexToRgb(color);
+  if (rgb === null) return color;
+  let [r, g, b] = rgb.map((v) => v / 255) as [number, number, number];
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  let l = (max + min) / 2;
+  const d = max - min;
+  let h = 0;
+  let s = 0;
+  if (d !== 0) {
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+    else if (max === g) h = (b - r) / d + 2;
+    else h = (r - g) / d + 4;
+    h /= 6;
+  }
+  l = Math.max(0, Math.min(1, l + amount));
+  if (s === 0) {
+    r = g = b = l;
+  } else {
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    r = hueToRgb(p, q, h + 1 / 3);
+    g = hueToRgb(p, q, h);
+    b = hueToRgb(p, q, h - 1 / 3);
+  }
+  const hex = (v: number): string => Math.trunc(v * 255).toString(16).padStart(2, "0");
+  return `#${hex(r)}${hex(g)}${hex(b)}`;
+}
+
+function hueToRgb(p: number, q: number, t: number): number {
+  if (t < 0) t += 1;
+  if (t > 1) t -= 1;
+  if (t < 1 / 6) return p + (q - p) * 6 * t;
+  if (t < 1 / 2) return q;
+  if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+  return p;
+}
+
 // ── Nesting Flattener ────────────────────────────────────────────
 
 function flattenNesting(scss: string): string {

package/packages/core/src/server.ts

@@ -867,6 +867,30 @@ ${reset}
   try {
     const { Frond } = await import("../../frond/src/engine.js");
     frondEngine = new Frond(templatesDir);
+
+    // Always-on Frond {% live %} refresh endpoint. Re-renders a server-rendered
+    // live block on demand (poll / sse), re-running its provider with the live
+    // request so auth re-applies. Parity with Python/PHP/Ruby /__frond/live/{name}.
+    router.addRoute({
+      method: "GET",
+      pattern: "/__frond/live/{name}",
+      handler: (req: any, res: any) => {
+        const { status, body } = Frond.respondLive(req, String(req.params?.name ?? ""));
+        return res.html(body, status);
+      },
+      meta: {
+        summary: "Frond live block refresh",
+        description: "Re-render a server-rendered {% live %} block by name.",
+        tags: ["System"],
+      },
+    });
+
+    // Wire the WebSocket broadcaster so Frond.pushLive can push live-block
+    // updates to connected clients (best-effort). Broadcasts to the block's
+    // declared data-ws path, else falls back to a path named after the block.
+    Frond.setLiveBroadcaster((wsPath: string | null, name: string, envelope: string) => {
+      wsRouteManager.broadcastPath(wsPath || name, envelope);
+    });
   } catch {
     // Frond not available
   }

package/packages/frond/src/engine.ts

@@ -13,6 +13,21 @@ import { join, resolve } from "node:path";
 export type FilterFn = (value: unknown, ...args: unknown[]) => unknown;
 export type TestFn = (value: unknown) => boolean;
 
+/** A minimal request shape a {% live %} data provider receives. */
+export interface LiveRequest {
+  headers?: Record<string, unknown>;
+  params?: Record<string, string>;
+}
+/** A {% live %} data provider — re-runs with the live request each refresh. */
+export type LiveProvider = (req: LiveRequest) => Record<string, unknown>;
+/** Result of respondLive — a pure {status, body} descriptor a route applies. */
+export interface LiveResponse {
+  status: number;
+  body: string;
+}
+/** WebSocket broadcaster hook wired by @tina4/core so pushLive can broadcast. */
+export type LiveBroadcaster = (wsPath: string | null, name: string, envelope: string) => void;
+
 /** Marker class for strings that should not be auto-escaped. */
 class SafeString {
   constructor(public value: string) {}
@@ -163,6 +178,21 @@ const FORMAT_RE = /%%|%([-+ 0]*)(\d+)?(?:\.(\d+))?([sdifFeEgGxXob])/g;
 const LEADING_WS_RE = /^\s+/;
 const TRAILING_WS_RE = /\s+$/;
 const THOUSANDS_RE = /\B(?=(\d{3})+(?!\d))/g;
+// {% live "name" poll N | sse | ws "path" [src "url"] %}
+const LIVE_RE = /^live\s+["']([^"']+)["']([\s\S]*)$/;
+const LIVE_WS_RE = /ws\s+["']([^"']+)["']/;
+const LIVE_SRC_RE = /src\s+["']([^"']+)["']/;
+
+/** Escape a value for a live-marker HTML attribute. Byte-identical order to
+ * the Python master / PHP liveAttr / Ruby live_attr so the emitted marker
+ * element matches across all four frameworks (& " < > — no apostrophe). */
+function liveAttr(value: unknown): string {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
 
 // ── Caches (module level) ─────────────────────────────────────
 
@@ -1374,6 +1404,24 @@ export class Frond {
   private static classGlobals: Map<string, unknown> = new Map();
   private static classTests: Map<string, TestFn> = new Map();
 
+  // ── Live-block registries (server-rendered {% live %} regions) ──
+  // A {% live %} block registers three things when its page first renders:
+  //   liveFragments[name] -> the raw body source, re-rendered on every
+  //                          refresh by GET /__frond/live/<name> or pushLive
+  //   liveSources[name]   -> an optional data provider (liveSource) that
+  //                          re-runs with the LIVE request each refresh, so
+  //                          auth re-applies (IDOR guard)
+  //   liveWsPaths[name]   -> the ws path a `ws "path"` block declared, the
+  //                          pushLive broadcast target
+  // Static so they persist across requests in the long-lived server. Mirrors
+  // the Python master's class-level dicts and PHP/Ruby static registries.
+  private static liveFragments: Map<string, string> = new Map();
+  private static liveSources: Map<string, LiveProvider> = new Map();
+  private static liveWsPaths: Map<string, string> = new Map();
+  // Best-effort WebSocket broadcaster wired by @tina4/core at boot (frond is a
+  // zero-dep leaf package and cannot import core). pushLive calls it if set.
+  private static liveBroadcaster: LiveBroadcaster | null = null;
+
   /**
    * Register a custom filter at the class level — available to every
    * future ``new Frond()`` instance. Callable as ``Frond.addFilter()``
@@ -1412,6 +1460,9 @@ export class Frond {
     Frond.classFilters.clear();
     Frond.classGlobals.clear();
     Frond.classTests.clear();
+    Frond.liveFragments.clear();
+    Frond.liveSources.clear();
+    Frond.liveWsPaths.clear();
   }
 
   private templateDir: string;
@@ -1850,6 +1901,10 @@ export class Frond {
           const [result, skip] = this.handleCache(tokens, i, context);
           output.push(result);
           i = skip;
+        } else if (tag === "live") {
+          const [result, skip] = this.handleLive(tokens, i, context);
+          output.push(result);
+          i = skip;
         } else if (tag === "spaceless") {
           const [result, skip] = this.handleSpaceless(tokens, i, context);
           output.push(result);
@@ -2502,6 +2557,175 @@ export class Frond {
     return [rendered, i];
   }
 
+  /**
+   * Handle {% live "name" poll N | sse | ws "path" [src "url"] %}...{% endlive %}.
+   *
+   * Server-rendered live region. The body renders once for first paint, is
+   * registered under <name> so GET /__frond/live/<name> (or a liveSource
+   * provider) can re-render it, and is wrapped in a marker element that
+   * frond.js wires to the chosen transport (poll / sse / ws). Mirrors the
+   * Python master's _handle_live and PHP/Ruby handleLive.
+   */
+  private handleLive(tokens: Token[], start: number, context: Record<string, unknown>): [string, number] {
+    const [content] = stripTag(tokens[start][1]);
+    const m = content.match(LIVE_RE);
+    if (!m) {
+      throw new Error('live: expected {% live "name" poll N | sse | ws "path" %}');
+    }
+    const name = m[1];
+    const rest = (m[2] || "").trim();
+    const parts = rest.split(/\s+/).filter(Boolean);
+    const mode = parts[0] || "";
+
+    const sm = rest.match(LIVE_SRC_RE);
+    const src = sm ? sm[1] : null;
+    if (src && (src.startsWith("http://") || src.startsWith("https://") || src.startsWith("//"))) {
+      throw new Error("live: src must be a same-origin path, not an absolute URL");
+    }
+
+    let interval: number | null = null;
+    let wsPath: string | null = null;
+    if (mode === "poll") {
+      if (!parts[1] || !/^\d+$/.test(parts[1])) {
+        throw new Error('live: poll requires seconds, e.g. {% live "x" poll 5 %}');
+      }
+      interval = parseInt(parts[1], 10);
+    } else if (mode === "sse") {
+      // no extra config
+    } else if (mode === "ws") {
+      const wm = rest.match(LIVE_WS_RE);
+      if (!wm) {
+        throw new Error('live: ws requires a path, e.g. {% live "x" ws "/ws/x" %}');
+      }
+      wsPath = wm[1];
+    } else {
+      throw new Error(`live: unknown transport "${mode}" (use poll N, sse, or ws "path")`);
+    }
+
+    // Collect body tokens up to {% endlive %}. Nested live is unsupported.
+    const bodyTokens: Token[] = [];
+    let i = start + 1;
+    while (i < tokens.length) {
+      if (tokens[i][0] === "BLOCK") {
+        const [tagContent] = stripTag(tokens[i][1]);
+        const tag = tagContent.split(/\s+/)[0] || "";
+        if (tag === "live") throw new Error("live: nested live blocks are not supported");
+        if (tag === "endlive") {
+          i++;
+          break;
+        }
+        bodyTokens.push(tokens[i]);
+      } else {
+        bodyTokens.push(tokens[i]);
+      }
+      i++;
+    }
+
+    // Register the raw body source so the auto endpoint can re-render it.
+    Frond.liveFragments.set(name, bodyTokens.map((t) => t[1]).join(""));
+
+    const endpoint = src || `/__frond/live/${name}`;
+    const attrs = [`data-frond-live="${liveAttr(name)}"`, `id="live-${liveAttr(name)}"`];
+    if (mode === "poll") {
+      attrs.push('data-mode="poll"', `data-interval="${interval}"`, `data-src="${liveAttr(endpoint)}"`);
+    } else if (mode === "sse") {
+      attrs.push('data-mode="sse"', `data-src="${liveAttr(endpoint)}"`);
+    } else if (mode === "ws") {
+      Frond.liveWsPaths.set(name, wsPath as string);
+      attrs.push('data-mode="ws"', `data-ws="${liveAttr(wsPath)}"`);
+    }
+
+    const firstPaint = this.renderTokens([...bodyTokens], context);
+    return [`<div ${attrs.join(" ")}>${firstPaint}</div>`, i];
+  }
+
+  // ── Live-block class API (mirrors Python master + PHP/Ruby facades) ──
+
+  /**
+   * Re-render a registered {% live %} fragment by name with fresh data.
+   * Returns the rendered HTML, or null if no fragment is registered under that
+   * name yet (its page has not rendered). GET /__frond/live/<name> calls this
+   * after resolving the provider data.
+   */
+  static renderLive(name: string, data?: Record<string, unknown>): string | null {
+    const source = Frond.liveFragments.get(name);
+    if (source === undefined) return null;
+    return new Frond().renderString(source, data || {});
+  }
+
+  /** Register a data provider for a {% live %} block. Invoked with the live
+   * request on every refresh so auth re-applies. Mirrors Python's @live_source. */
+  static liveSource(name: string, fn: LiveProvider): void {
+    Frond.liveSources.set(name, fn);
+  }
+
+  /** The provider registered for a live block, or null. */
+  static getLiveSource(name: string): LiveProvider | null {
+    return Frond.liveSources.get(name) ?? null;
+  }
+
+  /** Whether a live fragment has been registered (its page rendered). */
+  static hasLiveFragment(name: string): boolean {
+    return Frond.liveFragments.has(name);
+  }
+
+  /** The ws path a live block declared (data-ws), or null. */
+  static getLiveWsPath(name: string): string | null {
+    return Frond.liveWsPaths.get(name) ?? null;
+  }
+
+  /**
+   * Resolve GET /__frond/live/{name}: run the provider with the live request
+   * (auth re-applies), re-render the fragment, and return a pure {status, body}
+   * descriptor the route handler applies to the response. 404 for an unknown
+   * name / unrendered fragment. Mirrors Python's live_endpoint / PHP respondLive.
+   */
+  static respondLive(req: LiveRequest, name: string): LiveResponse {
+    const provider = Frond.liveSources.get(name);
+    if (!Frond.liveFragments.has(name) && provider === undefined) {
+      return { status: 404, body: `live block not found: ${name}` };
+    }
+    let context: Record<string, unknown> = {};
+    if (provider !== undefined) {
+      const result = provider(req);
+      context = result && typeof result === "object" ? result : {};
+    }
+    const html = Frond.renderLive(name, context);
+    if (html === null) {
+      return { status: 404, body: `live fragment not registered yet: ${name}` };
+    }
+    return { status: 200, body: html };
+  }
+
+  /** Wire the WebSocket broadcaster used by pushLive. Called once by @tina4/core
+   * at server boot (frond is a zero-dep leaf and cannot import core). */
+  static setLiveBroadcaster(fn: LiveBroadcaster | null): void {
+    Frond.liveBroadcaster = fn;
+  }
+
+  /**
+   * Re-render the '<name>' live fragment and push it to connected clients.
+   * Broadcasts a {type,name,html} envelope over WebSocket to the block's
+   * declared data-ws path (else a room named <name>). Returns the rendered
+   * HTML, or null if the fragment is not registered. Mirrors Python push_live
+   * / PHP pushLive. The broadcast is best-effort — a missing/failed broadcaster
+   * never throws into the caller.
+   */
+  static pushLive(name: string, data?: Record<string, unknown>): string | null {
+    const html = Frond.renderLive(name, data);
+    if (html === null) return null;
+
+    if (Frond.liveBroadcaster) {
+      try {
+        const envelope = JSON.stringify({ type: "live", name, html });
+        Frond.liveBroadcaster(Frond.getLiveWsPath(name), name, envelope);
+      } catch {
+        // best-effort — never let a broadcast failure escape pushLive
+      }
+    }
+    return html;
+  }
+
   private handleSpaceless(tokens: Token[], start: number, context: Record<string, unknown>): [string, number] {
     const bodyTokens: Token[] = [];
     let i = start + 1;

package/packages/frond/src/index.ts

@@ -1,2 +1,2 @@
 export { Frond } from "./engine.js";
-export type { FilterFn, TestFn } from "./engine.js";
+export type { FilterFn, TestFn, LiveProvider, LiveRequest, LiveResponse, LiveBroadcaster } from "./engine.js";

package/packages/orm/src/adapters/firebird.ts

@@ -486,10 +486,12 @@ export class FirebirdAdapter implements DatabaseAdapter {
 
       if (def.primaryKey && !def.autoIncrement) parts.push("PRIMARY KEY");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") {
+      // A json column carries no DDL DEFAULT (parity with the Python master): an
+      // object/array default is applied per instance, not a portable SQL literal.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") {
         parts.push(`DEFAULT ${sqlDefault(def.default)}`);
       }
-      if (def.default === "now") {
+      if (def.type !== "json" && def.default === "now") {
         parts.push("DEFAULT CURRENT_TIMESTAMP");
       }
 
@@ -548,6 +550,8 @@ function fieldTypeToFirebird(def: FieldDefinition): string {
       return "TIMESTAMP";
     case "text":
       return "BLOB SUB_TYPE TEXT";
+    case "json":
+      return "BLOB SUB_TYPE TEXT";   // Firebird has no TEXT/JSON type; store JSON in a text BLOB
     case "string":
       return def.maxLength ? `VARCHAR(${def.maxLength})` : "VARCHAR(255)";
     default:

package/packages/orm/src/adapters/mssql.ts

@@ -467,10 +467,12 @@ export class MssqlAdapter implements DatabaseAdapter {
 
       if (def.primaryKey && !def.autoIncrement) parts.push("PRIMARY KEY");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") {
+      // A json column carries no DDL DEFAULT (parity with the Python master): an
+      // object/array default is applied per instance, not a portable SQL literal.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") {
         parts.push(`DEFAULT ${sqlDefault(def.default)}`);
       }
-      if (def.default === "now") {
+      if (def.type !== "json" && def.default === "now") {
         parts.push("DEFAULT GETDATE()");
       }
 
@@ -499,6 +501,8 @@ function fieldTypeToMssql(def: FieldDefinition): string {
       return "DATETIME";
     case "text":
       return "NTEXT";
+    case "json":
+      return "NVARCHAR(MAX)";   // MSSQL stores JSON text; its JSON functions read NVARCHAR
     case "string":
       return def.maxLength ? `NVARCHAR(${def.maxLength})` : "NVARCHAR(255)";
     default:

package/packages/orm/src/adapters/mysql.ts

@@ -364,10 +364,13 @@ export class MysqlAdapter implements DatabaseAdapter {
 
       if (def.primaryKey && !def.autoIncrement) parts.push("PRIMARY KEY");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") {
+      // A json column carries no DDL DEFAULT (parity with the Python master; and
+      // MySQL's native JSON type rejects a literal DEFAULT anyway). The instance
+      // still gets its object/array default at construction.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") {
         parts.push(`DEFAULT ${sqlDefault(def.default)}`);
       }
-      if (def.default === "now") {
+      if (def.type !== "json" && def.default === "now") {
         parts.push("DEFAULT CURRENT_TIMESTAMP");
       }
 
@@ -395,6 +398,8 @@ function fieldTypeToMysql(def: FieldDefinition): string {
       return "DATETIME";
     case "text":
       return "TEXT";
+    case "json":
+      return "JSON";
     case "string":
       return def.maxLength ? `VARCHAR(${def.maxLength})` : "VARCHAR(255)";
     default:

package/packages/orm/src/adapters/odbc.ts

@@ -353,10 +353,12 @@ export class OdbcAdapter implements DatabaseAdapter {
       if (def.primaryKey) parts.push("PRIMARY KEY");
       if (def.autoIncrement) parts.push("GENERATED ALWAYS AS IDENTITY"); // ANSI SQL
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") {
+      // A json column carries no DDL DEFAULT (parity with the Python master): an
+      // object/array default is applied per instance, not a portable SQL literal.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") {
         parts.push(`DEFAULT ${sqlDefault(def.default)}`);
       }
-      if (def.default === "now") parts.push("DEFAULT CURRENT_TIMESTAMP");
+      if (def.type !== "json" && def.default === "now") parts.push("DEFAULT CURRENT_TIMESTAMP");
       colDefs.push(parts.join(" "));
     }
     await this.connection.query(`CREATE TABLE IF NOT EXISTS "${name}" (${colDefs.join(", ")})`);
@@ -405,6 +407,7 @@ function fieldTypeToOdbc(type: string): string {
     case "boolean": return "SMALLINT";
     case "datetime": return "TIMESTAMP";
     case "text": return "CLOB";
+    case "json": return "CLOB";   // store JSON text in a CLOB
     case "string":
     default: return "VARCHAR(255)";
   }

package/packages/orm/src/adapters/postgres.ts

@@ -423,10 +423,12 @@ export class PostgresAdapter implements DatabaseAdapter {
 
       if (def.primaryKey && !def.autoIncrement) parts.push("PRIMARY KEY");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") {
+      // A json column carries no DDL DEFAULT (parity with the Python master): an
+      // object/array default is applied per instance, not a portable SQL literal.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") {
         parts.push(`DEFAULT ${sqlDefault(def.default)}`);
       }
-      if (def.default === "now") {
+      if (def.type !== "json" && def.default === "now") {
         parts.push("DEFAULT CURRENT_TIMESTAMP");
       }
 
@@ -460,6 +462,8 @@ function fieldTypeToPostgres(def: FieldDefinition): string {
       return "TIMESTAMP";
     case "text":
       return "TEXT";
+    case "json":
+      return "JSONB";
     case "string":
       return def.maxLength ? `VARCHAR(${def.maxLength})` : "VARCHAR(255)";
     default:

package/packages/orm/src/adapters/sqlite.ts

@@ -366,8 +366,10 @@ export class SQLiteAdapter implements DatabaseAdapter {
       if (def.primaryKey) parts.push("PRIMARY KEY");
       if (def.autoIncrement) parts.push("AUTOINCREMENT");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") parts.push(`DEFAULT ${sqlDefault(def.default)}`);
-      if (def.default === "now") parts.push("DEFAULT CURRENT_TIMESTAMP");
+      // A json column carries no DDL DEFAULT (parity with the Python master): an
+      // object/array default is applied per instance, not a portable SQL literal.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") parts.push(`DEFAULT ${sqlDefault(def.default)}`);
+      if (def.type !== "json" && def.default === "now") parts.push("DEFAULT CURRENT_TIMESTAMP");
       colDefs.push(parts.join(" "));
     }
     this.db.exec(`CREATE TABLE IF NOT EXISTS "${name}" (${colDefs.join(", ")})`);
@@ -393,6 +395,7 @@ function fieldTypeToSQLite(type: string): string {
     case "boolean": return "INTEGER";
     case "datetime": return "TEXT";
     case "text": return "TEXT";
+    case "json": return "TEXT";   // no native JSON type; queryable via json1
     case "string": default: return "TEXT";
   }
 }

package/packages/orm/src/baseModel.ts

@@ -26,6 +26,41 @@ export function camelToSnake(name: string): string {
   return name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
 }
 
+/**
+ * Convert an in-memory field value to its database representation.
+ * A "json" field serialises its object/array to a JSON string for the driver
+ * (parity with the Python master's JSONField.to_db). A value that can't be
+ * serialised (e.g. a circular reference or a BigInt) throws — save() builds
+ * the row inside its try/catch, so it fails loud (rolls back, returns false,
+ * records the cause). null/undefined and an already-serialised string pass
+ * through untouched. Every other field type is returned as-is.
+ */
+export function toDbFieldValue(def: FieldDefinition | undefined, value: unknown): unknown {
+  if (def?.type === "json" && value !== null && value !== undefined && typeof value !== "string") {
+    return JSON.stringify(value);
+  }
+  return value;
+}
+
+/**
+ * Convert a database value to its in-memory representation for a field.
+ * A "json" column comes back from the driver as a JSON string (SQLite TEXT,
+ * MySQL JSON, PostgreSQL JSONB via the text protocol, MSSQL NVARCHAR); decode
+ * it to the object/array the property expects (parity with the Python master's
+ * JSONField parse-on-read). A value already an object/array is left untouched;
+ * null stays null; a non-decodable string keeps its raw form.
+ */
+export function fromDbFieldValue(def: FieldDefinition | undefined, value: unknown): unknown {
+  if (def?.type === "json" && typeof value === "string") {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value; // leave the raw string in place
+    }
+  }
+  return value;
+}
+
 /**
  * Check whether TINA4_ORM_PLURAL_TABLE_NAMES is enabled in .env.
  * When true, hasMany relationship keys get an "s" suffix (e.g. "posts" instead of "post").
@@ -130,9 +165,15 @@ export class BaseModel {
     const fields0 = ModelClass0.fields ?? {};
     for (const [name, def] of Object.entries(fields0)) {
       if (def.default === undefined) continue;
-      this[name] = typeof def.default === "function"
+      let dv = typeof def.default === "function"
         ? (def.default as () => unknown)()
         : def.default;
+      // Deep-clone a mutable object/array default so two instances never alias
+      // the same object (e.g. a json field `default: {}` — mutating a.meta must
+      // not leak into b.meta). Parity with the Python master's per-instance
+      // deepcopy and Ruby's Marshal round-trip.
+      if (dv !== null && typeof dv === "object") dv = structuredClone(dv);
+      this[name] = dv;
     }
 
     if (data) {
@@ -153,7 +194,10 @@ export class BaseModel {
       for (const [key, value] of Object.entries(data)) {
         // Lowercase the DB column key so UPPERCASE columns (Firebird/Oracle) match the mapping
         const jsProp = reverseMapping[key] ?? reverseMapping[key.toLowerCase()] ?? key;
-        this[jsProp] = value;
+        // A json column arrives as a JSON string from the driver (or as a raw
+        // string a caller passed); decode it to the object/array the property
+        // holds. A value already an object is left as-is.
+        this[jsProp] = fromDbFieldValue(fields0[jsProp], value);
       }
     }
   }
@@ -176,7 +220,7 @@ export class BaseModel {
     for (const key of Object.keys(ModelClass.fields)) {
       if (this[key] !== undefined) {
         const dbCol = ModelClass.getDbColumn(key);
-        result[dbCol] = this[key];
+        result[dbCol] = toDbFieldValue(ModelClass.fields[key], this[key]);
       }
     }
     return result;
@@ -649,7 +693,7 @@ export class BaseModel {
         if (updateFields.length === 0) { await adapterCommit(db); return this; }
 
         const setClause = updateFields.map(([k]) => `"${ModelClass.getDbColumn(k)}" = ?`).join(", ");
-        const values = [...updateFields.map(([k]) => this[k]), pkValue];
+        const values = [...updateFields.map(([k, def]) => toDbFieldValue(def, this[k])), pkValue];
 
         await adapterExecute(db, `UPDATE "${ModelClass.tableName}" SET ${setClause} WHERE "${pkCol}" = ?`, values);
       } else {
@@ -660,7 +704,7 @@ export class BaseModel {
 
         const columns = insertFields.map(([k]) => `"${ModelClass.getDbColumn(k)}"`).join(", ");
         const placeholders = insertFields.map(() => "?").join(", ");
-        const values = insertFields.map(([k]) => this[k]);
+        const values = insertFields.map(([k, def]) => toDbFieldValue(def, this[k]));
 
         // For auto-increment PKs on engines that need it (PostgreSQL),
         // RETURNING the PK column lets us read the engine-assigned id back.

package/packages/orm/src/database.ts

@@ -393,9 +393,10 @@ export function parseDatabaseUrl(url: string, username?: string, password?: stri
       database,
     };
   } else {
-    // Normalize postgres:// to postgresql:// for URL parsing
-    const normalizedUrl = url.startsWith("postgres://")
-      ? url.replace(/^postgres:\/\//, "postgresql://")
+    // Normalize postgres:// and pgsql:// (the PDO/Laravel/Doctrine scheme
+    // name, issue #58) to postgresql:// for URL parsing.
+    const normalizedUrl = /^(postgres|pgsql):\/\//.test(url)
+      ? url.replace(/^(postgres|pgsql):\/\//, "postgresql://")
       : url;
 
     let parsed: URL;

package/packages/orm/src/types.ts

@@ -1,4 +1,4 @@
-export type FieldType = "string" | "integer" | "number" | "numeric" | "boolean" | "datetime" | "text" | "foreignKey";
+export type FieldType = "string" | "integer" | "number" | "numeric" | "boolean" | "datetime" | "text" | "json" | "foreignKey";
 
 export interface FieldDefinition {
   type: FieldType;

package/packages/orm/src/validation.ts

@@ -87,6 +87,15 @@ export function validate(
         }
         break;
 
+      case "json":
+        // A JSON column holds an object/array (or a pre-serialised JSON
+        // string); reject a bare scalar. A value that can't be JSON-encoded
+        // (a circular reference, a BigInt) fails loud at save time.
+        if (value !== null && typeof value !== "object" && typeof value !== "string") {
+          errors.push({ field: name, message: "must be a JSON object or array" });
+        }
+        break;
+
       case "foreignKey": {
         // Outlier D: previously there was no foreignKey case, so ANY value
         // passed validation silently. A foreign key references another model's

package/packages/swagger/src/generator.ts

@@ -446,6 +446,11 @@ function fieldToSchemaProperty(def: FieldDefinition): Record<string, unknown> {
       // and produced an empty {} schema (audit P2).
       prop.type = "integer";
       break;
+    case "json":
+      // A JSON document column — an object or array. OpenAPI 3.0 can't express
+      // "object OR array" in one type, so advertise the common object shape.
+      prop.type = "object";
+      break;
     default:
       prop.type = "string";
   }