@trebor/buildhtml 1.0.0 → 1.0.2

package/index.js

@@ -1,18 +1,67 @@
-// ======================================================
-// ULTRA-PERFORMANCE SSR BUILDER v1.0.1 (FIXED)
-// ======================================================
-
 'use strict';
 
 /* ---------------- CONFIG ---------------- */
-const CONFIG = {
+const CONFIG = Object.freeze({
   mode: process.env.NODE_ENV === "production" ? "prod" : "dev",
   poolSize: 150,
   cacheLimit: 2000,
-  maxCssCache: 1000,
   maxKebabCache: 500,
-  compression: true
-};
+  compression: true,
+  enableMetrics: process.env.ENABLE_METRICS === 'true',
+  cspNonce: process.env.CSP_NONCE_ENABLED === 'true',
+  maxComputedFnSize: 10000,
+  maxEventFnSize: 5000,
+  sanitizeCss: true
+});
+
+/* ---------------- METRICS (Optional) ---------------- */
+class Metrics {
+  constructor() {
+    this.enabled = CONFIG.enableMetrics;
+    this.counters = new Map();
+    this.timings = new Map();
+  }
+
+  increment(key, value = 1) {
+    if (!this.enabled) return;
+    this.counters.set(key, (this.counters.get(key) || 0) + value);
+  }
+
+  timing(key, duration) {
+    if (!this.enabled) return;
+    if (!this.timings.has(key)) this.timings.set(key, []);
+    this.timings.get(key).push(duration);
+  }
+
+  getStats() {
+    const stats = { counters: {}, timings: {} };
+    
+    for (const [key, value] of this.counters) {
+      stats.counters[key] = value;
+    }
+    
+    for (const [key, values] of this.timings) {
+      const sorted = values.sort((a, b) => a - b);
+      const len = sorted.length;
+      stats.timings[key] = {
+        count: len,
+        avg: values.reduce((a, b) => a + b, 0) / len,
+        p50: sorted[Math.floor(len * 0.5)],
+        p95: sorted[Math.floor(len * 0.95)],
+        p99: sorted[Math.floor(len * 0.99)]
+      };
+    }
+    
+    return stats;
+  }
+
+  reset() {
+    this.counters.clear();
+    this.timings.clear();
+  }
+}
+
+const metrics = new Metrics();
 
 /* ---------------- OBJECT POOLS ---------------- */
 const pools = {
@@ -25,6 +74,8 @@ function getPooled(type, ...args) {
   const pool = pools[type];
   if (pool && pool.length > 0) {
     const item = pool.pop();
+    metrics.increment('pool.reuse.' + type);
+    
     if (type === 'elements') {
       resetElement(item, ...args);
     } else if (type === 'arrays') {
@@ -33,8 +84,15 @@ function getPooled(type, ...args) {
     return item;
   }
   
+  metrics.increment('pool.new.' + type);
+  
   switch (type) {
-    case 'elements': return new Element(...args);
+    case 'elements': {
+      const [tag, ridGen, stateStore, document] = args;
+      const el = new Element(tag, ridGen, stateStore);
+      el._document = document;
+      return el;
+    }
     case 'arrays': return [];
     case 'objects': return {};
     default: return null;
@@ -43,54 +101,62 @@ function getPooled(type, ...args) {
 
 function recycle(type, item) {
   const pool = pools[type];
-  if (!pool || pool.length >= CONFIG.poolSize) return;
+  if (!pool || pool.length >= CONFIG.poolSize) {
+    metrics.increment('pool.overflow.' + type);
+    return;
+  }
   
   if (type === 'elements' && item instanceof Element) {
-    // FIX: Recursive recycling to prevent memory leaks and orphaned children
     for (let i = 0; i < item.children.length; i++) {
       const child = item.children[i];
       if (child instanceof Element) {
         recycle('elements', child);
       }
     }
+    
+    item.children.length = 0;
+    item.events.length = 0;
+    item._stateBindings.length = 0;
+    item.cssText = "";
+    item._state = null;
+    item._computed = null;
+    
+    for (const key in item.attrs) delete item.attrs[key];
+    
     pool.push(item);
+    metrics.increment('pool.recycled.elements');
+    
   } else if (type === 'arrays' && Array.isArray(item)) {
     item.length = 0;
     pool.push(item);
-  } else if (type === 'objects' && typeof item === 'object') {
-    for (const key in item) delete item[key];
-    pool.push(item);
+    metrics.increment('pool.recycled.arrays');
   }
 }
 
-function resetElement(el, tag, ridGen, stateStore) {
+function resetElement(el, tag, ridGen, stateStore, document) {
   el.tag = toKebab(tag);
+  el._ridGen = ridGen;
+  el._stateStore = stateStore;
+  el._document = document;
   
-  // Clear attrs object properties instead of replacing to reduce GC
-  for (const key in el.attrs) delete el.attrs[key];
-  
-  // Reset arrays
+  if (!el.attrs) el.attrs = {};
   if (!el.children) el.children = [];
-  else el.children.length = 0;
-  
   if (!el.events) el.events = [];
-  else el.events.length = 0;
+  if (!el._stateBindings) el._stateBindings = [];
   
   el.cssText = "";
   el._state = null;
   el.hydrate = false;
   el._computed = null;
-  el._ridGen = ridGen;
-  el._stateStore = stateStore;
 }
 
 /* ---------------- UTILITIES ---------------- */
 let ridCounter = 0;
-const ridPrefix = Date.now().toString(36);
+const ridPrefix = Date.now().toString(36) + Math.random().toString(36).substring(2, 7);
 
 const createRidGenerator = () => () => `id-${ridPrefix}${(++ridCounter).toString(36)}`;
 
-// Simple 32-bit hash (for scoped class names)
+// FNV-1a hash
 const hash = (str) => {
   let h = 2166136261;
   const len = str.length;
@@ -101,36 +167,120 @@ const hash = (str) => {
   return (h >>> 0).toString(36);
 };
 
-// Kebab-case conversion with LRU cache
-const kebabCache = new Map();
+// LRU Kebab-case conversion cache
+class KebabCache {
+  constructor(maxSize) {
+    this.maxSize = maxSize;
+    this.cache = new Map();
+  }
+
+  get(key) {
+    if (!this.cache.has(key)) return null;
+    const value = this.cache.get(key);
+    this.cache.delete(key);
+    this.cache.set(key, value);
+    return value;
+  }
+
+  set(key, value) {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(key, value);
+  }
+}
+
+const kebabCache = new KebabCache(CONFIG.maxKebabCache);
 const kebabRegex = /[A-Z]/g;
 
 function toKebab(str) {
   if (!str || typeof str !== 'string') return "";
   
   const cached = kebabCache.get(str);
-  if (cached) return cached;
-  
-  const result = str.replace(kebabRegex, m => "-" + m.toLowerCase());
-  
-  if (kebabCache.size >= CONFIG.maxKebabCache) {
-    const firstKey = kebabCache.keys().next().value;
-    kebabCache.delete(firstKey);
+  if (cached) {
+    metrics.increment('kebab.cache.hit');
+    return cached;
   }
   
+  metrics.increment('kebab.cache.miss');
+  const result = str.replace(kebabRegex, m => "-" + m.toLowerCase());
   kebabCache.set(str, result);
   return result;
 }
 
-// HTML minification
-const minHTML = (html) => html.replace(/>\s+</g, "><").replace(/\s{2,}/g, " ").trim();
+// HTML minification (Safer version to preserve inline layouts)
+const minHTML = (html) => {
+  return html
+    // Only remove whitespace if it includes a newline or is more than 3 spaces
+    .replace(/>\s+<|>\n+</g, (m) => {
+        return m.includes('\n') || m.length > 3 ? "><" : " > <";
+    })
+    .replace(/\s{2,}/g, " ")
+    .trim();
+};
 
 // XSS protection
 const escapeMap = Object.freeze({
-  '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#039;'
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#x27;',
+  '/': '&#x2F;'
 });
-const escapeRegex = /[&<>"']/g;
-const escapeHtml = (text) => String(text).replace(escapeRegex, m => escapeMap[m]);
+const escapeRegex = /[&<>"'\/]/g;
+const escapeHtml = (text) => {
+  if (text == null) return '';
+  return String(text).replace(escapeRegex, m => escapeMap[m]);
+};
+
+// HTML Entity Unescaping (For JSON transport optimization)
+const unescapeMap = Object.freeze({
+  '&amp;': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&quot;': '"',
+  '&#x27;': "'",
+  '&#x2F;': '/'
+});
+const unescapeRegex = /&(?:amp|lt|gt|quot|#x27|#x2F);/g;
+const unescapeHtml = (text) => {
+  if (text == null) return '';
+  return String(text).replace(unescapeRegex, m => unescapeMap[m]);
+};
+
+// CSS value sanitization
+const cssValueRegex = /[<>"'{}()]/g;
+const sanitizeCssValue = (value) => {
+  if (!CONFIG.sanitizeCss) return value;
+  return String(value)
+    .replace(cssValueRegex, '')
+    .replace(/\/\*/g, '')
+    .replace(/\*\//g, '')
+    .substring(0, 1000);
+};
+
+// Validate function source
+const sanitizeFunctionSource = (fn, maxSize) => {
+  if (typeof fn !== 'function') {
+    throw new TypeError('Expected a function');
+  }
+  
+  const source = fn.toString();
+  
+  if (source.length > maxSize) {
+    throw new Error(`Function source too large: ${source.length} > ${maxSize}`);
+  }
+  
+  if (source.includes('</script>') || source.includes('<script')) {
+    throw new Error('Function contains potentially malicious script tags');
+  }
+  
+  return source;
+};
 
 /* ---------------- ELEMENT ---------------- */
 class Element {
@@ -145,6 +295,31 @@ class Element {
     this._computed = null;
     this._ridGen = ridGen;
     this._stateStore = stateStore;
+    this._document = null;
+    this._stateBindings = [];
+  }
+
+  child(tag) {
+    if (!this._document) {
+      throw new Error('[Element] Cannot create child: element not associated with a document');
+    }
+    const childElement = getPooled('elements', tag, this._ridGen, this._stateStore, this._document);
+    // Automatically add to parent's children array
+    this.children.push(childElement);
+    return childElement;
+  }
+
+  create(tag) {
+    return this.child(tag);
+  }
+
+  attr(key, value) {
+    this.attrs[toKebab(key)] = value;
+    return this;
+  }
+
+  attribute(key, value) {
+    return this.attr(key, value);
   }
 
   id(v) {
@@ -153,24 +328,97 @@ class Element {
   }
 
   text(c) {
-    this.children.push(escapeHtml(c));
+    if (c != null) {
+      this.children.push(escapeHtml(c));
+    }
     return this;
   }
 
+  // Allow text to be set as a property
+  set textContent(c) {
+    if (c != null) {
+      this.children = [escapeHtml(c)];
+    }
+  }
+
   append(c) {
+    if (c == null) return this;
     this.children.push(c instanceof Element ? c : escapeHtml(c));
     return this;
   }
 
+  appendUnsafe(html) {
+    if (html != null) {
+      this.children.push(String(html));
+    }
+    return this;
+  }
+
   css(s) {
-    let cssStr = "";
+    if (!s || typeof s !== 'object') return this;
+    
+    const cssRules = [];
     for (const k in s) {
-      cssStr += toKebab(k) + ":" + s[k] + ";";
+      const key = toKebab(k);
+      const value = sanitizeCssValue(s[k]);
+      cssRules.push(`${key}:${value}`);
     }
     
+    if (cssRules.length === 0) return this;
+    
+    const cssStr = cssRules.join(';') + ';';
     const sc = "c" + hash(cssStr);
+    
     this.attrs.class = this.attrs.class ? `${this.attrs.class} ${sc}` : sc;
     this.cssText += `.${sc}{${cssStr}}`;
+    
+    return this;
+  }
+
+  uniqueClass(rules) {
+    if (!rules || typeof rules !== 'object') return this;
+    
+    const cssRules = [];
+    for (const k in rules) {
+      const key = toKebab(k);
+      const value = sanitizeCssValue(rules[k]);
+      cssRules.push(`${key}:${value}`);
+    }
+    
+    if (cssRules.length === 0) return this;
+    
+    const cssStr = cssRules.join(';') + ';';
+    const uniqueName = "_u" + Math.random().toString(36).substring(2, 9);
+    
+    this.attrs.class = this.attrs.class ? `${this.attrs.class} ${uniqueName}` : uniqueName;
+    this.cssText += `.${uniqueName}{${cssStr}}`;
+    
+    return this;
+  }
+
+  bind(stateKey, templateFn = (val) => val) {
+    if (!this.attrs.id) this.id();
+    
+    try {
+      const fnSource = typeof templateFn === 'function' 
+        ? sanitizeFunctionSource(templateFn, CONFIG.maxComputedFnSize)
+        : '(val) => val';
+      
+      // Store binding info for client-side rendering
+      if (!this._stateBindings) this._stateBindings = [];
+      this._stateBindings.push({
+        stateKey,
+        id: this.attrs.id,
+        templateFn: fnSource
+      });
+      
+      this.hydrate = true;
+    } catch (err) {
+      if (CONFIG.mode === 'dev') {
+        console.error('[Element] Invalid bind function:', err.message);
+      }
+    }
+    
     return this;
   }
 
@@ -183,24 +431,64 @@ class Element {
   }
 
   computed(fn) {
-    this._computed = fn;
-    if (!this.attrs.id) this.id();
-    this.hydrate = true;
+    try {
+      sanitizeFunctionSource(fn, CONFIG.maxComputedFnSize);
+      this._computed = fn;
+      if (!this.attrs.id) this.id();
+      this.hydrate = true;
+    } catch (err) {
+      if (CONFIG.mode === 'dev') {
+        console.error('Invalid computed function:', err);
+      }
+    }
     return this;
   }
 
   on(ev, fn) {
-    if (!this.attrs.id) this.id();
-    this.events.push({ event: ev, id: this.attrs.id, fn });
-    this.hydrate = true;
+    try {
+      const fnSource = sanitizeFunctionSource(fn, CONFIG.maxEventFnSize);
+      
+      // Warn about closures in dev mode
+      if (CONFIG.mode === 'dev') {
+        // Check for potential closure usage
+        const hasClosureRisk = /(?:let|const|var)\s+\w+/.test(fnSource) === false && 
+                               /\w+\s*[\+\-\*\/\=]/.test(fnSource) && 
+                               !fnSource.includes('State.');
+        
+        if (hasClosureRisk) {
+          console.warn('[Sculptor] Warning: Event handler may use closures. ' +
+                       'Closures won\'t work after serialization. Use State instead.');
+        }
+      }
+      
+      if (!this.attrs.id) this.id();
+      this.events.push({ event: ev, id: this.attrs.id, fn });
+      this.hydrate = true;
+    } catch (err) {
+      if (CONFIG.mode === 'dev') {
+        console.error('Invalid event handler:', err.message);
+      }
+    }
     return this;
   }
 
   bindState(target, ev, fn) {
-    if (!this.attrs.id) this.id();
-    if (!target.attrs.id) target.id();
-    this.events.push({ event: ev, id: this.attrs.id, targetId: target.attrs.id, fn });
-    this.hydrate = true;
+    try {
+      sanitizeFunctionSource(fn, CONFIG.maxEventFnSize);
+      if (!this.attrs.id) this.id();
+      if (!target.attrs.id) target.id();
+      this.events.push({ 
+        event: ev, 
+        id: this.attrs.id, 
+        targetId: target.attrs.id, 
+        fn 
+      });
+      this.hydrate = true;
+    } catch (err) {
+      if (CONFIG.mode === 'dev') {
+        console.error('Invalid state binding:', err.message);
+      }
+    }
     return this;
   }
 }
@@ -215,6 +503,12 @@ class Head {
     this.scripts = [];
     this.globalStyles = [];
     this.classStyles = {};
+    this.nonce = null;
+  }
+
+  setNonce(nonce) {
+    this.nonce = nonce;
+    return this;
   }
 
   setTitle(t) {
@@ -223,48 +517,75 @@ class Head {
   }
 
   addMeta(m) {
-    this.metas.push(m);
+    if (m && typeof m === 'object') {
+      this.metas.push(m);
+    }
     return this;
   }
 
   addLink(l) {
-    if (!this.links.includes(l)) this.links.push(l);
+    if (l && typeof l === 'string' && !this.links.includes(l)) {
+      this.links.push(l);
+    }
     return this;
   }
 
   addStyle(s) {
-    this.styles.push(s);
+    if (s && typeof s === 'string') {
+      this.styles.push(s);
+    }
     return this;
   }
 
   addScript(s) {
-    this.scripts.push(s);
+    if (s && typeof s === 'string') {
+      this.scripts.push(s);
+    }
     return this;
   }
 
   globalCss(selector, rules) {
-    let cssStr = selector + "{";
+    if (!selector || !rules || typeof rules !== 'object') return this;
+    
+    const cssRules = [];
     for (const k in rules) {
-      cssStr += toKebab(k) + ":" + rules[k] + ";";
+      const key = toKebab(k);
+      const value = sanitizeCssValue(rules[k]);
+      cssRules.push(`${key}:${value}`);
+    }
+    
+    if (cssRules.length > 0) {
+      const cssStr = `${selector}{${cssRules.join(';')};}`;
+      this.globalStyles.push(cssStr);
     }
-    cssStr += "}";
-    this.globalStyles.push(cssStr);
+    
     return this;
   }
 
   addClass(name, rules) {
-    let cssStr = "";
+    if (!name || !rules || typeof rules !== 'object') return this;
+    
+    const cssRules = [];
     for (const k in rules) {
-      cssStr += toKebab(k) + ":" + rules[k] + ";";
+      const key = toKebab(k);
+      const value = sanitizeCssValue(rules[k]);
+      cssRules.push(`${key}:${value}`);
+    }
+    
+    if (cssRules.length > 0) {
+      this.classStyles[name] = cssRules.join(';') + ';';
     }
-    this.classStyles[name] = cssStr;
+    
     return this;
   }
 
   render() {
-    const parts = ['<meta charset="UTF-8"><title>', this.title, '</title>'];
+    const parts = [];
+    const nonceAttr = this.nonce ? ` nonce="${escapeHtml(this.nonce)}"` : '';
+    
+    parts.push('<meta charset="UTF-8">');
+    parts.push('<title>', this.title, '</title>');
     
-    // Meta tags
     const metaLen = this.metas.length;
     for (let i = 0; i < metaLen; i++) {
       const m = this.metas[i];
@@ -275,38 +596,44 @@ class Head {
       parts.push('>');
     }
     
-    // Links
     const linkLen = this.links.length;
     for (let i = 0; i < linkLen; i++) {
       parts.push('<link rel="stylesheet" href="', escapeHtml(this.links[i]), '">');
     }
     
-    // Styles
-    parts.push('<style>');
-    for (const name in this.classStyles) {
-      parts.push('.', toKebab(name), '{', this.classStyles[name], '}');
-    }
-    
-    const globalLen = this.globalStyles.length;
-    for (let i = 0; i < globalLen; i++) {
-      parts.push(this.globalStyles[i]);
-    }
-    
-    const styleLen = this.styles.length;
-    for (let i = 0; i < styleLen; i++) {
-      parts.push(this.styles[i]);
+    if (this.hasStyles()) {
+      parts.push('<style', nonceAttr, '>');
+      
+      for (const name in this.classStyles) {
+        parts.push('.', toKebab(name), '{', this.classStyles[name], '}');
+      }
+      
+      const globalLen = this.globalStyles.length;
+      for (let i = 0; i < globalLen; i++) {
+        parts.push(this.globalStyles[i]);
+      }
+      
+      const styleLen = this.styles.length;
+      for (let i = 0; i < styleLen; i++) {
+        parts.push(this.styles[i]);
+      }
+      
+      parts.push('</style>');
     }
     
-    parts.push('</style>');
-    
-    // Scripts
     const scriptLen = this.scripts.length;
     for (let i = 0; i < scriptLen; i++) {
-      parts.push('<script src="', escapeHtml(this.scripts[i]), '"></script>');
+      parts.push('<script', nonceAttr, ' src="', escapeHtml(this.scripts[i]), '"></script>');
     }
     
     return parts.join('');
   }
+
+  hasStyles() {
+    return Object.keys(this.classStyles).length > 0 || 
+           this.globalStyles.length > 0 || 
+           this.styles.length > 0;
+  }
 }
 
 /* ---------------- LRU CACHE ---------------- */
@@ -317,7 +644,12 @@ class LRUCache {
   }
 
   get(key) {
-    if (!this.cache.has(key)) return null;
+    if (!this.cache.has(key)) {
+      metrics.increment('cache.miss');
+      return null;
+    }
+    
+    metrics.increment('cache.hit');
     const value = this.cache.get(key);
     this.cache.delete(key);
     this.cache.set(key, value);
@@ -330,8 +662,10 @@ class LRUCache {
     } else if (this.cache.size >= this.limit) {
       const firstKey = this.cache.keys().next().value;
       this.cache.delete(firstKey);
+      metrics.increment('cache.eviction');
     }
     this.cache.set(key, value);
+    metrics.increment('cache.set');
   }
 
   clear() {
@@ -339,17 +673,43 @@ class LRUCache {
   }
   
   delete(key) {
-    this.cache.delete(key);
+    return this.cache.delete(key);
   }
   
   has(key) {
     return this.cache.has(key);
   }
+
+  get size() {
+    return this.cache.size;
+  }
 }
 
 const responseCache = new LRUCache(CONFIG.cacheLimit);
 const inFlightCache = new Map();
 
+/* ---------------- ENCRYPTION ---------------- */
+// Simple Base64 obfuscation for JSON data
+// NOTE: This is obfuscation, NOT cryptographic security!
+function generateEncryptionKey() {
+  // Not needed for Base64, but kept for API compatibility
+  return 1;
+}
+
+function encryptString(str, key) {
+  // Simple Base64 is fast and sufficient for obfuscation.
+  // Reversing large strings is too expensive for the client.
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(str, 'utf-8').toString('base64');
+  }
+  return btoa(unescape(encodeURIComponent(str)));
+}
+
+function getDecryptScript() {
+  // Optimized decoder: Just decode Base64 (O(1) complexity relative to string ops)
+  return `var _d=function(e){return decodeURIComponent(escape(atob(e)));};`;
+}
+
 /* ---------------- DOCUMENT ---------------- */
 class Document {
   constructor(options = {}) {
@@ -357,8 +717,21 @@ class Document {
     this.head = new Head();
     this._ridGen = createRidGenerator();
     this._stateStore = {};
+    this._globalState = {};
     this._useResponseCache = options.cache ?? false;
     this._cacheKey = options.cacheKey || null;
+    this._nonce = options.nonce || null;
+    this._oncreateCallbacks = [];
+    this._lastRendered = "";
+    
+    if (this._nonce) {
+      this.head.setNonce(this._nonce);
+    }
+  }
+
+  state(key, value) {
+    this._globalState[key] = value;
+    return this;
   }
 
   title(t) {
@@ -386,31 +759,107 @@ class Document {
     return this;
   }
 
-  use(el) {
-    this.body.push(el);
+  globalStyle(selector, rules) {
+    this.head.globalCss(selector, rules);
+    return this;
+  }
+
+  sharedClass(name, rules) {
+    this.head.addClass(name, rules);
+    return this;
+  }
+
+  defineClass(selector, rules, isRawSelector = false) {
+    if (!rules || typeof rules !== 'object') return this;
+    
+    const cssRules = [];
+    for (const prop in rules) {
+      const key = toKebab(prop);
+      const val = sanitizeCssValue(rules[prop]);
+      cssRules.push(`${key}:${val}`);
+    }
+    
+    if (cssRules.length > 0) {
+      const cssString = cssRules.join(';') + ';';
+      const finalSelector = isRawSelector ? selector : `.${selector}`;
+      
+      if (isRawSelector) {
+        this.head.globalStyles.push(`${finalSelector}{${cssString}}`);
+      } else {
+        this.head.classStyles[selector] = cssString;
+      }
+    }
+    
+    return this;
+  }
+
+  oncreate(fn) {
+    if (typeof fn !== 'function') {
+      throw new Error('[Document] .oncreate() expects a function.');
+    }
+    
+    try {
+      sanitizeFunctionSource(fn, CONFIG.maxEventFnSize);
+      this._oncreateCallbacks.push(fn);
+    } catch (err) {
+      if (CONFIG.mode === 'dev') {
+        console.error('[Document] Invalid oncreate function:', err.message);
+      }
+    }
+    
     return this;
   }
 
-  /** Add multiple elements from a function (for composition/layouts). fn(doc) returns Element or Element[]. */
   useFragment(fn) {
-    const els = fn(this);
-    const arr = Array.isArray(els) ? els : [els];
-    for (let i = 0; i < arr.length; i++) {
-      const el = arr[i];
-      if (el != null && el instanceof Element) this.use(el);
+    if (typeof fn !== 'function') return this;
+    
+    try {
+      const els = fn(this);
+      const arr = Array.isArray(els) ? els : [els];
+      
+      for (let i = 0; i < arr.length; i++) {
+        const el = arr[i];
+        if (el != null && el instanceof Element) {
+          this.body.push(el);
+        }
+      }
+    } catch (err) {
+      if (CONFIG.mode === 'dev') {
+        console.error('Fragment function error:', err);
+      }
     }
+    
     return this;
   }
 
   createElement(tag) {
-    return getPooled('elements', tag, this._ridGen, this._stateStore);
+    if (!tag || typeof tag !== 'string') {
+      throw new TypeError('Element tag must be a non-empty string');
+    }
+    const element = getPooled('elements', tag, this._ridGen, this._stateStore, this);
+    // Automatically add to document body when created from document
+    this.body.push(element);
+    return element;
   }
 
-  /** Shorthand for createElement(tag). */
   create(tag) {
     return this.createElement(tag);
   }
 
+  child(tag) {
+    return this.createElement(tag);
+  }
+
+  output() {
+    return this._lastRendered;
+  }
+
+  save(path) {
+    const fs = require('fs');
+    fs.writeFileSync(path, this._lastRendered);
+    return this;
+  }
+
   clear() {
     const bodyLen = this.body.length;
     for (let i = 0; i < bodyLen; i++) {
@@ -419,14 +868,210 @@ class Document {
       }
     }
     this.body.length = 0;
-    this._stateStore = {};
+    
+    for (const key in this._stateStore) {
+      delete this._stateStore[key];
+    }
+  }
+
+  toJSON() {
+    const serializeElement = (el) => {
+      if (!(el instanceof Element)) {
+        // FIX: Unescape text here so client gets raw chars
+        return { type: 'text', content: unescapeHtml(String(el)) };
+      }
+
+      const serialized = {
+        type: 'element',
+        tag: el.tag,
+        attrs: { ...el.attrs },
+        children: el.children.map(serializeElement),
+        cssText: el.cssText,
+        hydrate: el.hydrate
+      };
+
+      if (el._state !== null) {
+        serialized.state = el._state;
+      }
+
+      if (el._stateBindings && el._stateBindings.length > 0) {
+        serialized.stateBindings = el._stateBindings;
+      }
+
+      if (el.events && el.events.length > 0) {
+        serialized.events = el.events.map(e => ({
+          event: e.event,
+          id: e.id,
+          targetId: e.targetId,
+          fn: e.fn.toString()
+        }));
+      }
+
+      if (el._computed) {
+        serialized.computed = el._computed.toString();
+      }
+
+      return serialized;
+    };
+
+    return {
+      version: '1.0',
+      title: this.head.title,
+      metas: this.head.metas,
+      links: this.head.links,
+      styles: this.head.styles,
+      scripts: this.head.scripts,
+      globalStyles: this.head.globalStyles,
+      classStyles: this.head.classStyles,
+      globalState: this._globalState,
+      oncreateCallbacks: this._oncreateCallbacks.map(fn => fn.toString()),
+      body: this.body.map(serializeElement)
+    };
+  }
+
+  static fromJSON(json) {
+    const doc = new Document();
+    
+    if (typeof json === 'string') {
+      try {
+        json = JSON.parse(json);
+      } catch (e) {
+        throw new Error('[Sculptor] Invalid JSON string provided to fromJSON');
+      }
+    }
+    
+    if (!json || typeof json !== 'object') {
+      throw new Error('[Sculptor] fromJSON requires a valid JSON object');
+    }
+    
+    // Validate minimum required fields
+    if (!json.version) {
+      throw new Error('[Sculptor] Invalid JSON: missing version field');
+    }
+    
+    if (!Array.isArray(json.body)) {
+      throw new Error('[Sculptor] Invalid JSON: body must be an array');
+    }
+
+    // Restore head
+    doc.head.title = json.title || 'Document';
+    doc.head.metas = json.metas || [];
+    doc.head.links = json.links || [];
+    doc.head.styles = json.styles || [];
+    doc.head.scripts = json.scripts || [];
+    doc.head.globalStyles = json.globalStyles || [];
+    doc.head.classStyles = json.classStyles || {};
+
+    // Restore global state
+    doc._globalState = json.globalState || {};
+
+    // Restore oncreate callbacks
+    if (json.oncreateCallbacks && Array.isArray(json.oncreateCallbacks)) {
+      for (const fnStr of json.oncreateCallbacks) {
+        try {
+          // eslint-disable-next-line no-eval
+          const fn = eval(`(${fnStr})`);
+          doc._oncreateCallbacks.push(fn);
+        } catch (err) {
+          if (CONFIG.mode === 'dev') {
+            console.error('Failed to restore oncreate callback:', err);
+          }
+        }
+      }
+    }
+
+    // Restore body
+    const deserializeElement = (node) => {
+      if (node.type === 'text') {
+        return node.content;
+      }
+
+      const el = getPooled('elements', node.tag, doc._ridGen, doc._stateStore, doc);
+      
+      if (node.attrs) {
+        for (const key in node.attrs) {
+          el.attrs[key] = node.attrs[key];
+        }
+      }
+
+      if (node.cssText) {
+        el.cssText = node.cssText;
+      }
+
+      if (node.state !== undefined) {
+        el._state = node.state;
+        if (el.attrs.id) {
+          doc._stateStore[el.attrs.id] = node.state;
+        }
+      }
+
+      if (node.stateBindings) {
+        el._stateBindings = node.stateBindings;
+      }
+
+      if (node.computed) {
+        try {
+          // eslint-disable-next-line no-eval
+          el._computed = eval(`(${node.computed})`);
+        } catch (err) {
+          if (CONFIG.mode === 'dev') {
+            console.error('Failed to restore computed function:', err);
+          }
+        }
+      }
+
+      if (node.events && Array.isArray(node.events)) {
+        for (const evt of node.events) {
+          try {
+            // eslint-disable-next-line no-eval
+            const fn = eval(`(${evt.fn})`);
+            el.events.push({
+              event: evt.event,
+              id: evt.id,
+              targetId: evt.targetId,
+              fn: fn
+            });
+          } catch (err) {
+            if (CONFIG.mode === 'dev') {
+              console.error('Failed to restore event handler:', err);
+            }
+          }
+        }
+      }
+
+      el.hydrate = node.hydrate || false;
+
+      if (node.children && Array.isArray(node.children)) {
+        for (const child of node.children) {
+          const childEl = deserializeElement(child);
+          el.children.push(childEl);
+        }
+      }
+
+      return el;
+    };
+
+    if (json.body && Array.isArray(json.body)) {
+      for (const node of json.body) {
+        const el = deserializeElement(node);
+        doc.body.push(el);
+      }
+    }
+
+    return doc;
   }
 
   render() {
+    const startTime = CONFIG.enableMetrics ? Date.now() : 0;
+    
     if (this._useResponseCache && this._cacheKey) {
       const cached = responseCache.get(this._cacheKey);
       if (cached) {
         this.clear();
+        if (CONFIG.enableMetrics) {
+          metrics.timing('render.cached', Date.now() - startTime);
+        }
+        this._lastRendered = cached;
         return cached;
       }
     }
@@ -435,34 +1080,242 @@ class Document {
       events: getPooled('arrays'),
       states: getPooled('arrays'),
       styles: [],
-      computed: getPooled('arrays')
+      computed: getPooled('arrays'),
+      stateBindings: getPooled('arrays'),
+      oncreates: this._oncreateCallbacks,
+      globalState: this._globalState,
+      nonce: this._nonce
     };
 
     const bodyParts = [];
     const bodyLen = this.body.length;
     for (let i = 0; i < bodyLen; i++) {
-      bodyParts.push(renderNode(this.body[i], ctx));
+      const rendered = renderNode(this.body[i], ctx);
+      if (rendered) bodyParts.push(rendered);
     }
 
     const bodyHTML = bodyParts.join('');
     const headHTML = this.head.render();
-    const stylesHTML = ctx.styles.length > 0 ? '<style>' + ctx.styles.join('') + '</style>' : '';
+    const stylesHTML = ctx.styles.length > 0 ? 
+      `<style${this._nonce ? ` nonce="${escapeHtml(this._nonce)}"` : ''}>${ctx.styles.join('')}</style>` : 
+       '';
     const clientJS = compileClient(ctx);
 
-    // FIX: clientJS is injected inside body, maintaining requirement.
-    const html = `<!DOCTYPE html><html lang="en"><head>${headHTML}${stylesHTML}</head><body>${bodyHTML}${clientJS ? '<script>' + clientJS + '</script>' : ''}</body></html>`;
+    const html = [
+      '<!DOCTYPE html><html lang="en"><head>',
+      headHTML,
+      stylesHTML,
+      '</head><body>',
+      bodyHTML,
+      clientJS ? `<script${this._nonce ? ` nonce="${escapeHtml(this._nonce)}"` : ''}>${clientJS}</script>` : '',
+      '</body></html>'
+    ].join('');
 
     recycle('arrays', ctx.events);
     recycle('arrays', ctx.states);
     recycle('arrays', ctx.computed);
+    recycle('arrays', ctx.stateBindings);
+
+    const result = CONFIG.mode === "prod" ? minHTML(html) : html;
+
+    if (this._useResponseCache && this._cacheKey) {
+      responseCache.set(this._cacheKey, result);
+    }
+
+    this._lastRendered = result;
+    this.clear();
+    
+    if (CONFIG.enableMetrics) {
+      metrics.timing('render.total', Date.now() - startTime);
+      metrics.increment('render.count');
+    }
+    
+    return result;
+  }
+
+  renderJSON(varNameOrOptions, options) {
+    let jsonVarName = '__SCULPTOR_DATA__';
+    let opts = {};
+    
+    if (typeof varNameOrOptions === 'string') {
+      jsonVarName = varNameOrOptions;
+      opts = options || {};
+    } else if (typeof varNameOrOptions === 'object' && varNameOrOptions !== null) {
+      opts = varNameOrOptions;
+      jsonVarName = opts.varName || '__SCULPTOR_DATA__';
+    }
+    
+    const startTime = CONFIG.enableMetrics ? Date.now() : 0;
+    
+    // Check Cache
+    if (this._useResponseCache && this._cacheKey) {
+      const cached = responseCache.get(this._cacheKey);
+      if (cached) {
+        this.clear();
+        if (CONFIG.enableMetrics) metrics.timing('render.cached', Date.now() - startTime);
+        this._lastRendered = cached;
+        return cached;
+      }
+    }
+
+    const jsonData = this.toJSON();
+    const eventHandlers = {};
+    
+    // Extract Event Handlers (Deduplication)
+    const extractHandlers = (node) => {
+      if (node.type === 'element') {
+        if (node.events && Array.isArray(node.events)) {
+          node.events = node.events.map(evt => {
+            const handlerId = '_h' + hash(evt.fn.toString() + evt.id + evt.event);
+            eventHandlers[handlerId] = evt.fn.toString();
+            return {
+              event: evt.event,
+              id: evt.id,
+              targetId: evt.targetId,
+              handlerId: handlerId
+            };
+          });
+        }
+        if (node.children) node.children.forEach(child => extractHandlers(child));
+      }
+    };
+    
+    jsonData.body.forEach(node => extractHandlers(node));
+    
+    const jsonStr = JSON.stringify(jsonData);
+    const obfuscate = opts.obfuscate === true;
+    const headHTML = this.head.render();
+    
+    const parts = [
+      '<!DOCTYPE html><html lang="en"><head>',
+      headHTML,
+      `<script${this._nonce ? ` nonce="${escapeHtml(this._nonce)}"` : ''}>`,
+    ];
+    
+    // Inject Event Handlers (Safe Scope)
+    if (Object.keys(eventHandlers).length > 0) {
+      parts.push('window.__HANDLERS__={');
+      const handlerEntries = Object.entries(eventHandlers);
+      for (let i = 0; i < handlerEntries.length; i++) {
+        const [id, fnStr] = handlerEntries[i];
+        parts.push(`"${id}":${fnStr}`);
+        if (i < handlerEntries.length - 1) parts.push(',');
+      }
+      parts.push('};');
+    }
+    
+    // Inject JSON Data (Fast Decode)
+    if (obfuscate) {
+      const obfuscated = encryptString(jsonStr, true);
+      parts.push(getDecryptScript(), `window.${jsonVarName}=JSON.parse(_d("${obfuscated}"));`);
+    } else {
+      parts.push(`window.${jsonVarName}=${jsonStr};`);
+    }
+    
+    parts.push('</script></head><body>');
+    
+    // ---------------- HYDRATION ENGINE (Client Side) ---------------- //
+    parts.push(
+      `<script${this._nonce ? ` nonce="${escapeHtml(this._nonce)}"` : ''}>`,
+      `(function(){`,
+      `var data=window.${jsonVarName};`,
+      `if(!data)return;`,
+      
+      // HELPER: Compiler (Performance: Compiles string -> Function ONCE)
+      `var compile=function(s){try{return new Function('return ('+s+')')();}catch(e){return function(){};}};`,
+
+      // 1. INJECT STYLES
+      `var css='';`,
+      `if(data.classStyles){for(var n in data.classStyles)css+='.'+n+'{'+data.classStyles[n]+'}';}`,
+      `if(data.globalStyles){data.globalStyles.forEach(function(s){css+=s;});}`,
+      `if(css){var s=document.createElement('style');s.textContent=css;document.head.appendChild(s);}`,
+      
+      // 2. DOM BUILDER (Recursion)
+      `var dynamicCss = '';`,
+      `function buildEl(node){`,
+      `if(node.type==='text') return document.createTextNode(node.content);`, // Safe: createTextNode handles escaping
+      `var el=document.createElement(node.tag);`,
+      `if(node.attrs){for(var k in node.attrs)el.setAttribute(k,node.attrs[k]);}`,
+      `if(node.cssText){ dynamicCss += node.cssText; }`,
+      `if(node.children){for(var i=0;i<node.children.length;i++){`,
+      `el.appendChild(buildEl(node.children[i]));`,
+      `}}`,
+      `return el;`,
+      `}`,
+      
+      // 3. REACTIVE STATE PROXY
+      `if(data.globalState){`,
+      `var _cbs={};`,
+      `window.watchState=function(k,f){(_cbs[k]=_cbs[k]||[]).push(f);};`,
+      `window.State=new Proxy(data.globalState,{`,
+      `set:function(t,k,v){if(t[k]===v)return true;t[k]=v;if(_cbs[k])_cbs[k].forEach(function(f){f(v);});return true;}`,
+      `});}`,
+      
+      // 4. RENDER BODY
+      `if(data.body){`,
+      `for(var i=0;i<data.body.length;i++){document.body.appendChild(buildEl(data.body[i]));}`,
+      `}`,
+
+      // 5. INJECT DYNAMIC CSS (Buffered)
+      `if(dynamicCss){var s=document.createElement('style');s.textContent=dynamicCss;document.head.appendChild(s);}`,
+      
+      // 6. HYDRATION (Events & Bindings)
+      `function hydrateNode(node){`,
+      `if(node.type!=='element')return;`,
+      `var el=node.attrs&&node.attrs.id?document.getElementById(node.attrs.id):null;`,
+      `if(el){`,
+      
+      // State Bindings (Optimized: Compile Once, Run Many)
+      `if(node.stateBindings){`,
+      `node.stateBindings.forEach(function(b){`,
+      `var fn=compile(b.templateFn);`, // Compile here
+      `window.watchState(b.stateKey,function(val){try{el.textContent=fn(val);}catch(e){}});`,
+      `if(window.State[b.stateKey]!==undefined){try{el.textContent=fn(window.State[b.stateKey]);}catch(e){}}`,
+      `});`,
+      `}`,
+      `}`,
+      
+      // Events (Delegated via Handlers)
+      `if(node.events){`,
+      `node.events.forEach(function(evt){`,
+      `var tid=evt.targetId||evt.id;`,
+      `var te=document.getElementById(tid);`,
+      `if(te&&evt.handlerId&&window.__HANDLERS__[evt.handlerId]){`,
+      `try{te.addEventListener(evt.event,window.__HANDLERS__[evt.handlerId]);}catch(e){}`,
+      `}`,
+      `});`,
+      `}`,
+      
+      // Recurse Children
+      `if(node.children){node.children.forEach(function(c){hydrateNode(c);});}`,
+      `}`,
+      
+      `if(data.body){data.body.forEach(function(n){hydrateNode(n);});}`,
+      
+      // OnCreate Callbacks
+      `if(data.oncreateCallbacks){`,
+      `data.oncreateCallbacks.forEach(function(f){try{compile(f)();}catch(e){console.error(e);}});`,
+      `}`,
+      `})();`,
+      '</script></body></html>'
+    );
 
+    const html = parts.join('');
+    // Use safer minification
     const result = CONFIG.mode === "prod" ? minHTML(html) : html;
 
     if (this._useResponseCache && this._cacheKey) {
       responseCache.set(this._cacheKey, result);
     }
 
+    this._lastRendered = result;
     this.clear();
+    
+    if (CONFIG.enableMetrics) {
+      metrics.timing('render.total', Date.now() - startTime);
+      metrics.increment('render.count');
+    }
+    
     return result;
   }
 }
@@ -475,12 +1328,15 @@ const voidElements = new Set([
 
 function renderNode(n, ctx) {
   if (n == null) return '';
-  if (!(n instanceof Element)) return n;
+  if (!(n instanceof Element)) return String(n);
 
   const parts = ['<', n.tag];
 
   for (const k in n.attrs) {
-    parts.push(' ', toKebab(k), '="', escapeHtml(n.attrs[k]), '"');
+    const value = n.attrs[k];
+    if (value != null) {
+      parts.push(' ', toKebab(k), '="', escapeHtml(value), '"');
+    }
   }
 
   parts.push('>');
@@ -492,14 +1348,26 @@ function renderNode(n, ctx) {
   }
 
   if (n._computed) {
-    ctx.computed.push({ id: n.attrs.id, fn: n._computed.toString() });
+    try {
+      const fnSource = sanitizeFunctionSource(n._computed, CONFIG.maxComputedFnSize);
+      ctx.computed.push({ id: n.attrs.id, fn: fnSource });
+    } catch (err) {
+      if (CONFIG.mode === 'dev') {
+        console.error('Computed function validation failed:', err);
+      }
+    }
+  }
+
+  // Collect state bindings
+  if (n._stateBindings && n._stateBindings.length > 0) {
+    ctx.stateBindings.push(...n._stateBindings);
   }
 
-  // FIX: Properly skip children for void elements to avoid illegal HTML
   if (!voidElements.has(n.tag)) {
     const childLen = n.children.length;
     for (let i = 0; i < childLen; i++) {
-      parts.push(renderNode(n.children[i], ctx));
+      const rendered = renderNode(n.children[i], ctx);
+      if (rendered) parts.push(rendered);
     }
     parts.push('</', n.tag, '>');
   }
@@ -517,102 +1385,247 @@ function compileClient(ctx) {
   const hasStates = ctx.states.length > 0;
   const hasComputed = ctx.computed.length > 0;
   const hasEvents = ctx.events.length > 0;
+  const hasOncreates = ctx.oncreates && ctx.oncreates.length > 0;
+  const hasGlobalState = ctx.globalState && Object.keys(ctx.globalState).length > 0;
+  const hasStateBindings = ctx.stateBindings && ctx.stateBindings.length > 0;
 
-  if (!hasStates && !hasComputed && !hasEvents) {
+  if (!hasStates && !hasComputed && !hasEvents && !hasOncreates && !hasGlobalState && !hasStateBindings) {
     return '';
   }
 
-  // FIX: Moved helper functions inside the scope to prevent global pollution
+  const namespace = '_ssr' + Date.now().toString(36);
+  
   const parts = [
-    'window.state={};',
-    'document.addEventListener("DOMContentLoaded",function(){',
-    'const getById=id=>document.getElementById(id);'
+    '(function(){',
+    `var ${namespace}={state:{}};`,
+    'var getById=function(id){return document.getElementById(id);};'
   ];
 
-  // States (use .value for input/textarea, .textContent for others)
-  const stateLen = ctx.states.length;
-  const valueProp = (tag) => (tag === 'input' || tag === 'textarea' ? 'value' : 'textContent');
-  for (let i = 0; i < stateLen; i++) {
-    const s = ctx.states[i];
-    const prop = valueProp(s.tag || '');
+  // Initialize global reactive state with callbacks
+  if (hasGlobalState || hasStateBindings) {
     parts.push(
-      'window.state["', s.id, '"]=', JSON.stringify(s.value), ';',
-      '(function(){var _el=getById("', s.id, '");if(_el)_el.', prop, '=window.state["', s.id, '"];})();'
+      'var _cbs={};',
+      'window.watchState=function(k,f){(_cbs[k]=_cbs[k]||[]).push(f);};',
+      'window.State=new Proxy(' + JSON.stringify(ctx.globalState || {}) + ',{',
+      'set:function(t,k,v){',
+      'if(t[k]===v)return true;',
+      't[k]=v;',
+      'if(_cbs[k])_cbs[k].forEach(function(f){f(v);});',
+      'return true;',
+      '}',
+      '});'
     );
   }
 
-  // Computed
+  const stateLen = ctx.states.length;
+  if (stateLen > 0) {
+    parts.push('var initStates=function(){');
+    
+    for (let i = 0; i < stateLen; i++) {
+      const s = ctx.states[i];
+      const prop = (s.tag === 'input' || s.tag === 'textarea') ? 'value' : 'textContent';
+      const safeValue = JSON.stringify(s.value);
+      
+      parts.push(
+        `${namespace}.state["${s.id}"]=${safeValue};`,
+        `(function(){var el=getById("${s.id}");if(el)el.${prop}=${namespace}.state["${s.id}"];})();`
+      );
+    }
+    
+    parts.push('};');
+  }
+
   const computedLen = ctx.computed.length;
-  for (let i = 0; i < computedLen; i++) {
-    const c = ctx.computed[i];
-    parts.push('(function(){var _el=getById("', c.id, '");if(_el)_el.textContent=(', c.fn, ')(window.state);})();');
+  if (computedLen > 0) {
+    parts.push('var initComputed=function(){');
+    
+    for (let i = 0; i < computedLen; i++) {
+      const c = ctx.computed[i];
+      parts.push(
+        `(function(){var el=getById("${c.id}");`,
+        `if(el)try{el.textContent=(${c.fn})(${namespace}.state);}catch(e){console.error("Computed error:",e);}`,
+        '})();'
+      );
+    }
+    
+    parts.push('};');
+  }
+
+  // State bindings - use watchState
+  if (hasStateBindings) {
+    parts.push('var initBindings=function(){');
+    
+    for (let i = 0; i < ctx.stateBindings.length; i++) {
+      const b = ctx.stateBindings[i];
+      parts.push(
+        `window.watchState('${b.stateKey}',function(val){`,
+        `var el=getById('${b.id}');`,
+        `if(el)try{el.textContent=(${b.templateFn})(val);}catch(e){console.error('Binding error:',e);}`,
+        '});'
+      );
+      
+      // Initialize with current value
+      parts.push(
+        `(function(){`,
+        `var el=getById('${b.id}');`,
+        `if(el&&window.State['${b.stateKey}']!==undefined)`,
+        `try{el.textContent=(${b.templateFn})(window.State['${b.stateKey}']);}catch(e){}`,
+        '})();'
+      );
+    }
+    
+    parts.push('};');
   }
 
-  // Events
   const eventLen = ctx.events.length;
-  for (let i = 0; i < eventLen; i++) {
-    const e = ctx.events[i];
-    let f = e.fn.toString();
-    if (e.targetId) {
-      f = f.replace(/__STATE_ID__/g, e.targetId);
+  if (eventLen > 0) {
+    parts.push('var initEvents=function(){');
+    
+    for (let i = 0; i < eventLen; i++) {
+      const e = ctx.events[i];
+      let fnSource = e.fn.toString();
+      
+      if (e.targetId) {
+        fnSource = fnSource.replace(/__STATE_ID__/g, e.targetId);
+      }
+      
+      parts.push(
+        `(function(){var el=getById("${e.id}");`,
+        `if(el)try{el.addEventListener("${e.event}",${fnSource});}catch(err){console.error("Event handler error:",err);}`,
+        '})();'
+      );
     }
-    parts.push('(function(){var _el=getById("', e.id, '");if(_el)_el.addEventListener("', e.event, '",', f, ');})();');
+    
+    parts.push('};');
   }
 
-  parts.push('});');
+  // Add oncreate callbacks
+  if (hasOncreates) {
+    parts.push('var initOncreate=function(){');
+    
+    for (let i = 0; i < ctx.oncreates.length; i++) {
+      const fn = ctx.oncreates[i];
+      try {
+        const fnSource = sanitizeFunctionSource(fn, CONFIG.maxEventFnSize);
+        parts.push(`(${fnSource})();`);
+      } catch (err) {
+        if (CONFIG.mode === 'dev') {
+          console.error('Oncreate validation failed:', err);
+        }
+      }
+    }
+    
+    parts.push('};');
+  }
+
+  parts.push(
+    'if(document.readyState==="loading"){',
+    'document.addEventListener("DOMContentLoaded",function(){'
+  );
+  
+  if (stateLen > 0) parts.push('initStates();');
+  if (computedLen > 0) parts.push('initComputed();');
+  if (hasStateBindings) parts.push('initBindings();');
+  if (eventLen > 0) parts.push('initEvents();');
+  if (hasOncreates) parts.push('initOncreate();');
+  
+  parts.push(
+    '});',
+    '}else{'
+  );
+  
+  if (stateLen > 0) parts.push('initStates();');
+  if (computedLen > 0) parts.push('initComputed();');
+  if (hasStateBindings) parts.push('initBindings();');
+  if (eventLen > 0) parts.push('initEvents();');
+  if (hasOncreates) parts.push('initOncreate();');
+  
+  parts.push('}');
+  parts.push(`window.${namespace}=${namespace};`);
+  parts.push('})();');
+
   return parts.join('');
 }
 
 /* ---------------- MIDDLEWARE HELPERS ---------------- */
-function createCachedRenderer(builderFn, cacheKeyOrFn) {
-  return (req, res, next) => {
-    const key = typeof cacheKeyOrFn === 'function' ? cacheKeyOrFn(req) : cacheKeyOrFn;
+function createCachedRenderer(builderFn, cacheKeyOrFn, options = {}) {
+  if (typeof builderFn !== 'function') {
+    throw new TypeError('Builder function is required');
+  }
 
-    if (key == null || key === '') {
-      try {
-        const doc = builderFn(req);
+  return async (req, res, next) => {
+    try {
+      const key = typeof cacheKeyOrFn === 'function' ? cacheKeyOrFn(req) : cacheKeyOrFn;
+
+      if (key == null || key === '') {
+        const doc = await Promise.resolve(builderFn(req));
+        
         if (!doc || !(doc instanceof Document)) {
           return res.status(500).send('Internal Server Error');
         }
+        
         return res.send(doc.render());
-      } catch (err) {
-        return next(err);
       }
-    }
 
-    const cached = responseCache.get(key);
-    if (cached) {
-      return res.send(cached);
-    }
+      const cached = responseCache.get(key);
+      if (cached) {
+        metrics.increment('middleware.cache.hit');
+        return res.send(cached);
+      }
 
-    let promise = inFlightCache.get(key);
-    if (!promise) {
-      promise = Promise.resolve().then(() => {
-        const doc = builderFn(req);
-        if (!doc || !(doc instanceof Document)) {
-          const err = new Error('Builder function must return a Document instance');
-          err.status = 500;
-          throw err;
-        }
-        doc._useResponseCache = true;
-        doc._cacheKey = key;
-        return doc.render();
-      });
-      inFlightCache.set(key, promise);
-      promise.then((html) => {
-        responseCache.set(key, html);
-      }).finally(() => {
-        inFlightCache.delete(key);
-      });
-    }
+      metrics.increment('middleware.cache.miss');
+
+      let promise = inFlightCache.get(key);
+      
+      if (!promise) {
+        promise = Promise.resolve()
+          .then(() => builderFn(req))
+          .then((doc) => {
+            if (!doc || !(doc instanceof Document)) {
+              const err = new Error('Builder function must return a Document instance');
+              err.status = 500;
+              throw err;
+            }
+            
+            doc._useResponseCache = true;
+            doc._cacheKey = key;
+            
+            if (options.nonce && typeof options.nonce === 'function') {
+              doc._nonce = options.nonce(req);
+            }
+            
+            return doc.render();
+          });
+        
+        inFlightCache.set(key, promise);
+        
+        promise
+          .then((html) => {
+            responseCache.set(key, html);
+            metrics.increment('middleware.cache.set');
+          })
+          .catch((err) => {
+            if (CONFIG.mode === 'dev') {
+              console.error('Render error:', err);
+            }
+          })
+          .finally(() => {
+            inFlightCache.delete(key);
+          });
+      } else {
+        metrics.increment('middleware.stampede.prevented');
+      }
 
-    promise.then((html) => res.send(html)).catch((err) => {
+      const html = await promise;
+      res.send(html);
+      
+    } catch (err) {
       if (err.status === 500) {
         res.status(500).send('Internal Server Error');
       } else {
         next(err);
       }
-    });
+    }
   };
 }
 
@@ -620,66 +1633,132 @@ function clearCache(pattern) {
   if (!pattern) {
     responseCache.clear();
     inFlightCache.clear();
+    metrics.increment('cache.clear.all');
     return;
   }
 
-  const keysToDelete = [];
+  const keysToDelete = new Set();
+  
   for (const [key] of responseCache.cache) {
-    if (key.includes(pattern)) keysToDelete.push(key);
+    if (key.includes(pattern)) {
+      keysToDelete.add(key);
+    }
   }
+  
   for (const key of inFlightCache.keys()) {
-    if (key.includes(pattern) && !keysToDelete.includes(key)) keysToDelete.push(key);
+    if (key.includes(pattern)) {
+      keysToDelete.add(key);
+    }
   }
-  const len = keysToDelete.length;
-  for (let i = 0; i < len; i++) {
-    responseCache.delete(keysToDelete[i]);
-    inFlightCache.delete(keysToDelete[i]);
+  
+  for (const key of keysToDelete) {
+    responseCache.delete(key);
+    inFlightCache.delete(key);
   }
+  
+  metrics.increment('cache.clear.pattern', keysToDelete.size);
 }
 
-// Compression middleware
 function enableCompression() {
   return (req, res, next) => {
     const acceptEncoding = req.headers['accept-encoding'];
     
-    if (acceptEncoding && acceptEncoding.includes('gzip')) {
-      const originalSend = res.send;
-      res.send = function(data) {
-        if (typeof data === 'string' && data.length > 1024) {
-          try {
-            const zlib = require('zlib');
-            const compressed = zlib.gzipSync(data);
+    if (!acceptEncoding || !acceptEncoding.includes('gzip')) {
+      return next();
+    }
+    
+    const originalSend = res.send;
+    
+    res.send = function(data) {
+      res.send = originalSend;
+      
+      const contentType = this.getHeader('Content-Type') || '';
+      const isCompressible = 
+        contentType.includes('text/html') || 
+        contentType.includes('text/css') ||
+        contentType.includes('text/javascript') ||
+        contentType.includes('application/javascript') ||
+        contentType.includes('application/json');
+      
+      const shouldCompress = 
+        typeof data === 'string' && 
+        data.length > 1024 && 
+        isCompressible;
+      
+      if (shouldCompress) {
+        try {
+          const zlib = require('zlib');
+          
+          zlib.gzip(data, (err, compressed) => {
+            if (err) {
+              metrics.increment('compression.error');
+              return originalSend.call(this, data);
+            }
+            
             this.setHeader('Content-Encoding', 'gzip');
             this.setHeader('Content-Length', compressed.length);
+            this.setHeader('Vary', 'Accept-Encoding');
+            metrics.increment('compression.success');
+            metrics.increment('compression.bytes.saved', data.length - compressed.length);
+            
             return originalSend.call(this, compressed);
-          } catch (err) {
-            return originalSend.call(this, data);
-          }
+          });
+          
+          return;
+          
+        } catch (err) {
+          metrics.increment('compression.error');
+          return originalSend.call(this, data);
         }
-        return originalSend.call(this, data);
-      };
-    }
+      }
+      
+      return originalSend.call(this, data);
+    };
     
     next();
   };
 }
 
-// Warmup cache helper
-function warmupCache(routes) {
+async function warmupCache(routes) {
+  if (!Array.isArray(routes)) {
+    throw new TypeError('Routes must be an array');
+  }
+  
   const results = [];
   
   for (const route of routes) {
+    if (!route || typeof route !== 'object') {
+      results.push({ error: 'Invalid route object', success: false });
+      continue;
+    }
+    
     const { key, builder } = route;
+    
+    if (!key || !builder) {
+      results.push({ key, error: 'Missing key or builder', success: false });
+      continue;
+    }
+    
     try {
-      const doc = builder();
+      const doc = await Promise.resolve(builder());
+      
       if (!doc || !(doc instanceof Document)) {
         results.push({ key, error: 'Builder must return a Document instance', success: false });
         continue;
       }
+      
       doc._useResponseCache = true;
       doc._cacheKey = key;
+      
       const html = doc.render();
-      results.push({ key, size: html.length, success: true });
+      
+      results.push({ 
+        key, 
+        size: html.length, 
+        compressed: Math.floor(html.length * 0.3),
+        success: true 
+      });
+      
     } catch (err) {
       results.push({ key, error: err.message, success: false });
     }
@@ -688,18 +1767,44 @@ function warmupCache(routes) {
   return results;
 }
 
-// Stats helper
 function getCacheStats() {
   return {
-    size: responseCache.cache.size,
-    limit: CONFIG.cacheLimit,
-    usage: ((responseCache.cache.size / CONFIG.cacheLimit) * 100).toFixed(2) + '%',
-    keys: Array.from(responseCache.cache.keys()),
-    poolStats: {
+    cache: {
+      size: responseCache.size,
+      limit: CONFIG.cacheLimit,
+      usage: ((responseCache.size / CONFIG.cacheLimit) * 100).toFixed(2) + '%',
+      keys: Array.from(responseCache.cache.keys())
+    },
+    inFlight: {
+      size: inFlightCache.size,
+      keys: Array.from(inFlightCache.keys())
+    },
+    pools: {
       elements: pools.elements.length,
       arrays: pools.arrays.length,
       objects: pools.objects.length
-    }
+    },
+    metrics: CONFIG.enableMetrics ? metrics.getStats() : null
+  };
+}
+
+function resetPools() {
+  pools.elements.length = 0;
+  pools.arrays.length = 0;
+  pools.objects.length = 0;
+  metrics.increment('pools.reset');
+}
+
+function healthCheck() {
+  return {
+    status: 'ok',
+    timestamp: Date.now(),
+    config: {
+      mode: CONFIG.mode,
+      poolSize: CONFIG.poolSize,
+      cacheLimit: CONFIG.cacheLimit
+    },
+    stats: getCacheStats()
   };
 }
 
@@ -714,5 +1819,8 @@ module.exports = {
   enableCompression,
   responseCache,
   warmupCache,
-  getCacheStats
+  getCacheStats,
+  resetPools,
+  healthCheck,
+  metrics
 };