npm - @trebor/buildhtml - Versions diffs - 1.0.0 - Mend

@trebor/buildhtml 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/LICENSE.txt ADDED Viewed

@@ -0,0 +1,15 @@
+Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)
+Copyright 2026 0trebor0
+You are free to:
+- Share — copy and redistribute the material in any medium or format
+- Adapt — remix, transform, and build upon the material
+Under the following terms:
+- Attribution — You must give appropriate credit to 0trebor0, provide a link to the license, and indicate if changes were made.
+- NonCommercial — You may not use the material for commercial purposes.
+Full license text: https://creativecommons.org/licenses/by-nc/4.0/

package/README.md ADDED Viewed

@@ -0,0 +1,329 @@
+````markdown
+# BuildHTML
+**Zero-dependency, ultra-fast server-side rendering (SSR) compiler.**
+*“Compile your HTML at lightning speed, without the bloat.”*
+---
+## Overview
+BuildHTML is a lightweight SSR compiler for Node.js. It allows you to build HTML on the server with minimal memory usage and blazing-fast performance—without relying on heavy frameworks. Perfect for custom Node servers, static site generators, or optimized Express apps.
+- **Zero dependencies** – Only Node.js required.
+- **Ultra-fast** – Optimized rendering and memory reuse.
+- **SSR-ready** – Easily manage state, computed values, and client-side hydration.
+- **Customizable** – Create elements, set styles, attach events, and more.
+---
+## Installation
+```bash
+npm install @trebor/buildhtml
+````
+or via GitHub:
+```bash
+npm install github:0trebor0/buildhtml
+```
+---
+## Quick Start
+```javascript
+const { Document } = require('@trebor/buildhtml');
+// Create a new document
+const doc = new Document();
+// Add elements (use __STATE_ID__ + bindState so the handler works on the client)
+const counter = doc.create('div').text('0').state(0);
+const button = doc.create('button').text('Increment');
+button.bindState(counter, 'click', function() {
+  const id = '__STATE_ID__';
+  const el = document.getElementById(id);
+  const val = parseInt(window.state[id] || 0, 10) + 1;
+  window.state[id] = val;
+  el.textContent = val;
+});
+// Add to document
+doc.use(counter).use(button);
+// Render HTML
+const html = doc.render();
+console.log(html);
+```
+---
+## Features
+* **Element creation**: `doc.create('div')` or `doc.createElement('div')`, `text()`, `append()`, `css()`.
+* **Composition**: `doc.useFragment(fn)` – `fn(doc)` returns one or more elements to reuse layouts/headers/footers.
+* **State management**: `.state(value)` for server-generated state (hydrates `textContent` on normal elements, `value` on `<input>`/`<textarea>`).
+* **Computed values**: `.computed(fn)` for dynamic content.
+* **Event binding**: `.on(event, fn)` and `.bindState(target, event, fn)`.
+* **Optimized rendering**: Object pools, LRU caching, in-flight deduplication for cached routes, minified output in production.
+* **Client-side hydration**: Automatically generates JS to update states and events in the browser.
+---
+## API Guide
+### Exports
+```javascript
+const {
+  Document,
+  Element,
+  Head,
+  CONFIG,
+  createCachedRenderer,
+  clearCache,
+  enableCompression,
+  responseCache,
+  warmupCache,
+  getCacheStats
+} = require('@trebor/buildhtml');
+```
+---
+### Document
+Root HTML builder. Create with `new Document(options)`.
+| Method | Description |
+|--------|-------------|
+| `title(t)` | Set page title (escaped). Returns `this`. |
+| `addMeta(m)` | Add meta tag; `m` is an object, e.g. `{ name: 'description', content: '...' }`. |
+| `addLink(href)` | Add `<link rel="stylesheet" href="...">` (deduplicated). |
+| `addStyle(css)` | Add inline CSS string to `<head>`. |
+| `addScript(src)` | Add `<script src="...">` to `<head>`. |
+| `use(el)` | Append one element to the body. Returns `this`. |
+| `useFragment(fn)` | Append multiple elements; `fn(doc)` returns a single `Element` or an array of `Element`s. Ignores `null`/non-Element. Returns `this`. |
+| `create(tag)` | Create a pooled element (e.g. `'div'`, `'input'`). Tag is normalized to kebab-case. Shorthand for `createElement(tag)`. |
+| `createElement(tag)` | Same as `create(tag)`. |
+| `clear()` | Clear body and state store; recycle elements. |
+| `render()` | Return full HTML string. If cache options are set, may return cached result or populate cache. Clears the document after render. |
+**Constructor options**
+| Option | Type | Description |
+|--------|------|-------------|
+| `cache` | `boolean` | If `true`, use response cache when `cacheKey` is set (e.g. by `createCachedRenderer`). |
+| `cacheKey` | `string` | Key for response cache. |
+**Example**
+```javascript
+const doc = new Document({ cache: true, cacheKey: 'home' });
+doc.title('Home').addMeta({ charset: 'UTF-8' });
+doc.use(doc.create('main').append(doc.create('p').text('Hello')));
+const html = doc.render();
+```
+---
+### Element
+Created with `doc.create(tag)` or `doc.createElement(tag)`. All mutating methods return `this` for chaining.
+| Method | Description |
+|--------|-------------|
+| `id(v?)` | Set `id` attribute. If `v` is omitted, assigns a unique id (required for state/events/computed). |
+| `text(c)` | Append escaped text as a child. |
+| `append(c)` | Append child: `Element` (rendered as subtree) or string (escaped). |
+| `css(styles)` | Add scoped inline styles; `styles` is an object, e.g. `{ marginTop: '10px' }`. Keys are kebab-cased. Adds a hashed class and injects a `<style>` block. |
+| `state(v)` | Set initial state for hydration. Element gets an id if missing. Hydration sets `textContent` (or `value` for `input`/`textarea`). |
+| `computed(fn)` | Hydrate with `fn(window.state)`; `fn` is serialized and run in the browser. Element gets an id if missing. |
+| `on(ev, fn)` | Attach client-side event; `ev` is event name (e.g. `'click'`). `fn` is serialized and run in the browser. Element gets an id if missing. |
+| `bindState(target, ev, fn)` | Like `on(ev, fn)` but for updating another element’s state. In `fn`, use the literal string `'__STATE_ID__'` where you need the target’s id; it is replaced at compile time with `target`’s id. |
+**Read-only**
+- `el.attrs` – Object of attributes (e.g. `el.attrs.id`, `el.attrs.class`).
+- `el.tag` – Normalized tag name (kebab-case).
+**Example**
+```javascript
+const div = doc.create('div').id('root').css({ padding: '1rem' }).text('Hello');
+const btn = doc.create('button').text('Click').on('click', function() { console.log('ok'); });
+div.append(btn);
+```
+---
+### Head
+Accessed as `doc.head`. Usually configured via `Document` methods (`title`, `addMeta`, etc.). Advanced usage:
+| Method | Description |
+|--------|-------------|
+| `setTitle(t)` | Set title (escaped). |
+| `addMeta(m)` | Add one meta object. |
+| `addLink(href)` | Add stylesheet link (no duplicates). |
+| `addStyle(css)` | Add raw CSS string. |
+| `addScript(src)` | Add script tag src. |
+| `globalCss(selector, rules)` | Add a rule like `selector { ... }`; `rules` is an object (keys kebab-cased). |
+| `addClass(name, rules)` | Define a class `.name` with `rules` object. |
+---
+### CONFIG
+Global config object (read/write). Used by the compiler and caches.
+| Property | Default | Description |
+|----------|---------|-------------|
+| `mode` | `'prod'` if `NODE_ENV=== 'production'`, else `'dev'` | `'prod'` minifies HTML. |
+| `poolSize` | `150` | Max pooled items per type (elements, arrays, objects). |
+| `cacheLimit` | `2000` | Max entries in response LRU cache. |
+| `maxCssCache` | `1000` | Reserved. |
+| `maxKebabCache` | `500` | Max kebab-case conversions cached. |
+| `compression` | `true` | Used by `enableCompression` middleware. |
+---
+### createCachedRenderer(builderFn, cacheKeyOrFn)
+Returns a middleware function `(req, res, next) => ...`.
+- **builderFn**: `(req) => Document`. Must return a `Document` instance. The middleware sets cache options on it and calls `doc.render()`.
+- **cacheKeyOrFn**: `string` or `(req) => string`. Cache key for the response. If it is `null`/`undefined`/`''`, caching is skipped and the document is built and sent once per request.
+- Concurrent requests with the same key share one render (in-flight deduplication); the result is cached and sent to all waiters.
+---
+### clearCache(pattern?)
+- **No argument**: Clears entire response cache and all in-flight keys.
+- **`pattern` (string)**: Deletes every cache key that includes `pattern` (response cache and in-flight).
+---
+### enableCompression()
+Returns a middleware that, when `Accept-Encoding` includes `gzip`, patches `res.send` to gzip string bodies longer than 1024 bytes. Call `next()` so the route still runs.
+---
+### responseCache
+LRU cache instance used for full HTML responses. Methods: `get(key)`, `set(key, value)`, `has(key)`, `delete(key)`, `clear()`. Property `responseCache.cache` is the underlying `Map` (for iteration).
+---
+### warmupCache(routes)
+Pre-renders routes to fill the response cache.
+- **routes**: `Array<{ key: string, builder: () => Document }>`. `builder()` is called with no arguments and must return a `Document`.
+- **Returns**: `Array<{ key, success: boolean, size?: number, error?: string }>`.
+---
+### getCacheStats()
+Returns an object: `{ size, limit, usage, keys, poolStats }` for the response cache and pool counts.
+---
+## Quick BuildHTML Examples
+Here’s how to use **BuildHTML** in an Express server for fast SSR.
+```javascript
+const express = require('express');
+const { Document, createCachedRenderer, clearCache, enableCompression } = require('@trebor/buildhtml');
+const app = express();
+// -----------------------------------------------------------------------------
+// 1️⃣ Basic Route (No Cache)
+// -----------------------------------------------------------------------------
+app.get('/', (req, res) => {
+  const doc = new Document();
+  doc.title('Home Page');
+  const heading = doc.create('h1').text('Welcome to BuildHTML!');
+  const subtitle = doc.create('p').text('Ultra-fast server-side rendering');
+  doc.use(heading).use(subtitle);
+  res.send(doc.render());
+});
+// -----------------------------------------------------------------------------
+// 2️⃣ Cached Static Route
+// -----------------------------------------------------------------------------
+app.get('/about', createCachedRenderer(() => {
+  const doc = new Document({ cache: true, cacheKey: 'about' });
+  doc.title('About Us');
+  const content = doc.create('p').text('This page is cached for performance.');
+  doc.use(content);
+  return doc;
+}, 'about'));
+// -----------------------------------------------------------------------------
+// 3️⃣ Dynamic Route with Params (Cached per User)
+// -----------------------------------------------------------------------------
+app.get('/user/:name', createCachedRenderer((req) => {
+  const doc = new Document({ cache: true, cacheKey: `user-${req.params.name}` });
+  doc.title(`Profile - ${req.params.name}`);
+  const greeting = doc.create('h1').text(`Hello, ${req.params.name}!`);
+  doc.use(greeting);
+  return doc;
+}, (req) => `user-${req.params.name}`));
+// -----------------------------------------------------------------------------
+// 4️⃣ Interactive Counter (No Cache, With State)
+// -----------------------------------------------------------------------------
+app.get('/counter', (req, res) => {
+  const doc = new Document();
+  doc.title('Counter App');
+  const counter = doc.create('div').state(0);
+  const incBtn = doc.create('button').text('+');
+  incBtn.bindState(counter, 'click', function() {
+    const id = '__STATE_ID__';
+    window.state[id] = parseInt(window.state[id]) + 1;
+    document.getElementById(id).textContent = window.state[id];
+  });
+  doc.use(counter).use(incBtn);
+  res.send(doc.render());
+});
+// Start server
+app.listen(3000, () => console.log('Server running on http://localhost:3000'));
+````
+### Key Points
+* **`Document`** – Core HTML builder.
+* **`createCachedRenderer`** – Cache static or dynamic pages for ultra-fast responses.
+* **Stateful elements** – `.state()` allows dynamic, interactive content.
+* **Express-friendly** – Integrates with your server routes seamlessly.
+* **`clearCache()`** – Manually clear cached pages when content changes.
+### Limitations
+* **Hydration** – Event and computed handlers are serialized with `.toString()` and run in the browser. Don’t rely on closures over server-side variables; use `__STATE_ID__` with `bindState()` for target elements.
+* **State display** – `.state()` hydrates `textContent` on normal elements and `value` on `<input>`/`<textarea>`. For form inputs, use `.value` in your event handler when updating from user input.
+* **Caching** – Concurrent requests for the same key share one render (in-flight deduplication); `clearCache()` also clears in-flight entries.
+---
+## License
+**[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/)** – You are free to use and modify BuildHTML **for non-commercial projects**, as long as you give credit to the original author (0trebor0).
+---

package/index.js ADDED Viewed

@@ -0,0 +1,718 @@
+// ======================================================
+// ULTRA-PERFORMANCE SSR BUILDER v1.0.1 (FIXED)
+// ======================================================
+'use strict';
+/* ---------------- CONFIG ---------------- */
+const CONFIG = {
+  mode: process.env.NODE_ENV === "production" ? "prod" : "dev",
+  poolSize: 150,
+  cacheLimit: 2000,
+  maxCssCache: 1000,
+  maxKebabCache: 500,
+  compression: true
+};
+/* ---------------- OBJECT POOLS ---------------- */
+const pools = {
+  elements: [],
+  arrays: [],
+  objects: []
+};
+function getPooled(type, ...args) {
+  const pool = pools[type];
+  if (pool && pool.length > 0) {
+    const item = pool.pop();
+    if (type === 'elements') {
+      resetElement(item, ...args);
+    } else if (type === 'arrays') {
+      item.length = 0;
+    }
+    return item;
+  }
+  switch (type) {
+    case 'elements': return new Element(...args);
+    case 'arrays': return [];
+    case 'objects': return {};
+    default: return null;
+  }
+}
+function recycle(type, item) {
+  const pool = pools[type];
+  if (!pool || pool.length >= CONFIG.poolSize) 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);
+      }
+    }
+    pool.push(item);
+  } 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);
+  }
+}
+function resetElement(el, tag, ridGen, stateStore) {
+  el.tag = toKebab(tag);
+  // Clear attrs object properties instead of replacing to reduce GC
+  for (const key in el.attrs) delete el.attrs[key];
+  // Reset arrays
+  if (!el.children) el.children = [];
+  else el.children.length = 0;
+  if (!el.events) el.events = [];
+  else el.events.length = 0;
+  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 createRidGenerator = () => () => `id-${ridPrefix}${(++ridCounter).toString(36)}`;
+// Simple 32-bit hash (for scoped class names)
+const hash = (str) => {
+  let h = 2166136261;
+  const len = str.length;
+  for (let i = 0; i < len; i++) {
+    h ^= str.charCodeAt(i);
+    h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);
+  }
+  return (h >>> 0).toString(36);
+};
+// Kebab-case conversion with LRU cache
+const kebabCache = new Map();
+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);
+  }
+  kebabCache.set(str, result);
+  return result;
+}
+// HTML minification
+const minHTML = (html) => html.replace(/>\s+</g, "><").replace(/\s{2,}/g, " ").trim();
+// XSS protection
+const escapeMap = Object.freeze({
+  '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#039;'
+});
+const escapeRegex = /[&<>"']/g;
+const escapeHtml = (text) => String(text).replace(escapeRegex, m => escapeMap[m]);
+/* ---------------- ELEMENT ---------------- */
+class Element {
+  constructor(tag, ridGen, stateStore) {
+    this.tag = toKebab(tag);
+    this.attrs = {};
+    this.children = [];
+    this.events = [];
+    this.cssText = "";
+    this._state = null;
+    this.hydrate = false;
+    this._computed = null;
+    this._ridGen = ridGen;
+    this._stateStore = stateStore;
+  }
+  id(v) {
+    this.attrs.id = v || this._ridGen();
+    return this;
+  }
+  text(c) {
+    this.children.push(escapeHtml(c));
+    return this;
+  }
+  append(c) {
+    this.children.push(c instanceof Element ? c : escapeHtml(c));
+    return this;
+  }
+  css(s) {
+    let cssStr = "";
+    for (const k in s) {
+      cssStr += toKebab(k) + ":" + s[k] + ";";
+    }
+    const sc = "c" + hash(cssStr);
+    this.attrs.class = this.attrs.class ? `${this.attrs.class} ${sc}` : sc;
+    this.cssText += `.${sc}{${cssStr}}`;
+    return this;
+  }
+  state(v) {
+    if (!this.attrs.id) this.id();
+    this._state = v;
+    this._stateStore[this.attrs.id] = v;
+    this.hydrate = true;
+    return this;
+  }
+  computed(fn) {
+    this._computed = fn;
+    if (!this.attrs.id) this.id();
+    this.hydrate = true;
+    return this;
+  }
+  on(ev, fn) {
+    if (!this.attrs.id) this.id();
+    this.events.push({ event: ev, id: this.attrs.id, fn });
+    this.hydrate = true;
+    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;
+    return this;
+  }
+}
+/* ---------------- HEAD ---------------- */
+class Head {
+  constructor() {
+    this.title = "Document";
+    this.metas = [];
+    this.links = [];
+    this.styles = [];
+    this.scripts = [];
+    this.globalStyles = [];
+    this.classStyles = {};
+  }
+  setTitle(t) {
+    this.title = escapeHtml(t);
+    return this;
+  }
+  addMeta(m) {
+    this.metas.push(m);
+    return this;
+  }
+  addLink(l) {
+    if (!this.links.includes(l)) this.links.push(l);
+    return this;
+  }
+  addStyle(s) {
+    this.styles.push(s);
+    return this;
+  }
+  addScript(s) {
+    this.scripts.push(s);
+    return this;
+  }
+  globalCss(selector, rules) {
+    let cssStr = selector + "{";
+    for (const k in rules) {
+      cssStr += toKebab(k) + ":" + rules[k] + ";";
+    }
+    cssStr += "}";
+    this.globalStyles.push(cssStr);
+    return this;
+  }
+  addClass(name, rules) {
+    let cssStr = "";
+    for (const k in rules) {
+      cssStr += toKebab(k) + ":" + rules[k] + ";";
+    }
+    this.classStyles[name] = cssStr;
+    return this;
+  }
+  render() {
+    const parts = ['<meta charset="UTF-8"><title>', this.title, '</title>'];
+    // Meta tags
+    const metaLen = this.metas.length;
+    for (let i = 0; i < metaLen; i++) {
+      const m = this.metas[i];
+      parts.push('<meta ');
+      for (const k in m) {
+        parts.push(toKebab(k), '="', escapeHtml(m[k]), '" ');
+      }
+      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]);
+    }
+    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>');
+    }
+    return parts.join('');
+  }
+}
+/* ---------------- LRU CACHE ---------------- */
+class LRUCache {
+  constructor(limit) {
+    this.limit = limit;
+    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.limit) {
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(key, value);
+  }
+  clear() {
+    this.cache.clear();
+  }
+  delete(key) {
+    this.cache.delete(key);
+  }
+  has(key) {
+    return this.cache.has(key);
+  }
+}
+const responseCache = new LRUCache(CONFIG.cacheLimit);
+const inFlightCache = new Map();
+/* ---------------- DOCUMENT ---------------- */
+class Document {
+  constructor(options = {}) {
+    this.body = [];
+    this.head = new Head();
+    this._ridGen = createRidGenerator();
+    this._stateStore = {};
+    this._useResponseCache = options.cache ?? false;
+    this._cacheKey = options.cacheKey || null;
+  }
+  title(t) {
+    this.head.setTitle(t);
+    return this;
+  }
+  addMeta(m) {
+    this.head.addMeta(m);
+    return this;
+  }
+  addLink(l) {
+    this.head.addLink(l);
+    return this;
+  }
+  addStyle(s) {
+    this.head.addStyle(s);
+    return this;
+  }
+  addScript(s) {
+    this.head.addScript(s);
+    return this;
+  }
+  use(el) {
+    this.body.push(el);
+    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);
+    }
+    return this;
+  }
+  createElement(tag) {
+    return getPooled('elements', tag, this._ridGen, this._stateStore);
+  }
+  /** Shorthand for createElement(tag). */
+  create(tag) {
+    return this.createElement(tag);
+  }
+  clear() {
+    const bodyLen = this.body.length;
+    for (let i = 0; i < bodyLen; i++) {
+      if (this.body[i] instanceof Element) {
+        recycle('elements', this.body[i]);
+      }
+    }
+    this.body.length = 0;
+    this._stateStore = {};
+  }
+  render() {
+    if (this._useResponseCache && this._cacheKey) {
+      const cached = responseCache.get(this._cacheKey);
+      if (cached) {
+        this.clear();
+        return cached;
+      }
+    }
+    const ctx = {
+      events: getPooled('arrays'),
+      states: getPooled('arrays'),
+      styles: [],
+      computed: getPooled('arrays')
+    };
+    const bodyParts = [];
+    const bodyLen = this.body.length;
+    for (let i = 0; i < bodyLen; i++) {
+      bodyParts.push(renderNode(this.body[i], ctx));
+    }
+    const bodyHTML = bodyParts.join('');
+    const headHTML = this.head.render();
+    const stylesHTML = ctx.styles.length > 0 ? '<style>' + 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>`;
+    recycle('arrays', ctx.events);
+    recycle('arrays', ctx.states);
+    recycle('arrays', ctx.computed);
+    const result = CONFIG.mode === "prod" ? minHTML(html) : html;
+    if (this._useResponseCache && this._cacheKey) {
+      responseCache.set(this._cacheKey, result);
+    }
+    this.clear();
+    return result;
+  }
+}
+/* ---------------- RENDERER ---------------- */
+const voidElements = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr'
+]);
+function renderNode(n, ctx) {
+  if (n == null) return '';
+  if (!(n instanceof Element)) return n;
+  const parts = ['<', n.tag];
+  for (const k in n.attrs) {
+    parts.push(' ', toKebab(k), '="', escapeHtml(n.attrs[k]), '"');
+  }
+  parts.push('>');
+  if (n.cssText) ctx.styles.push(n.cssText);
+  if (n._state !== null) {
+    ctx.states.push({ id: n.attrs.id, value: n._state, tag: n.tag });
+  }
+  if (n._computed) {
+    ctx.computed.push({ id: n.attrs.id, fn: n._computed.toString() });
+  }
+  // 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));
+    }
+    parts.push('</', n.tag, '>');
+  }
+  const eventLen = n.events.length;
+  for (let i = 0; i < eventLen; i++) {
+    ctx.events.push(n.events[i]);
+  }
+  return parts.join('');
+}
+/* ---------------- CLIENT ---------------- */
+function compileClient(ctx) {
+  const hasStates = ctx.states.length > 0;
+  const hasComputed = ctx.computed.length > 0;
+  const hasEvents = ctx.events.length > 0;
+  if (!hasStates && !hasComputed && !hasEvents) {
+    return '';
+  }
+  // FIX: Moved helper functions inside the scope to prevent global pollution
+  const parts = [
+    'window.state={};',
+    'document.addEventListener("DOMContentLoaded",function(){',
+    'const getById=id=>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 || '');
+    parts.push(
+      'window.state["', s.id, '"]=', JSON.stringify(s.value), ';',
+      '(function(){var _el=getById("', s.id, '");if(_el)_el.', prop, '=window.state["', s.id, '"];})();'
+    );
+  }
+  // Computed
+  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);})();');
+  }
+  // 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);
+    }
+    parts.push('(function(){var _el=getById("', e.id, '");if(_el)_el.addEventListener("', e.event, '",', f, ');})();');
+  }
+  parts.push('});');
+  return parts.join('');
+}
+/* ---------------- MIDDLEWARE HELPERS ---------------- */
+function createCachedRenderer(builderFn, cacheKeyOrFn) {
+  return (req, res, next) => {
+    const key = typeof cacheKeyOrFn === 'function' ? cacheKeyOrFn(req) : cacheKeyOrFn;
+    if (key == null || key === '') {
+      try {
+        const doc = 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);
+    }
+    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);
+      });
+    }
+    promise.then((html) => res.send(html)).catch((err) => {
+      if (err.status === 500) {
+        res.status(500).send('Internal Server Error');
+      } else {
+        next(err);
+      }
+    });
+  };
+}
+function clearCache(pattern) {
+  if (!pattern) {
+    responseCache.clear();
+    inFlightCache.clear();
+    return;
+  }
+  const keysToDelete = [];
+  for (const [key] of responseCache.cache) {
+    if (key.includes(pattern)) keysToDelete.push(key);
+  }
+  for (const key of inFlightCache.keys()) {
+    if (key.includes(pattern) && !keysToDelete.includes(key)) keysToDelete.push(key);
+  }
+  const len = keysToDelete.length;
+  for (let i = 0; i < len; i++) {
+    responseCache.delete(keysToDelete[i]);
+    inFlightCache.delete(keysToDelete[i]);
+  }
+}
+// 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);
+            this.setHeader('Content-Encoding', 'gzip');
+            this.setHeader('Content-Length', compressed.length);
+            return originalSend.call(this, compressed);
+          } catch (err) {
+            return originalSend.call(this, data);
+          }
+        }
+        return originalSend.call(this, data);
+      };
+    }
+    next();
+  };
+}
+// Warmup cache helper
+function warmupCache(routes) {
+  const results = [];
+  for (const route of routes) {
+    const { key, builder } = route;
+    try {
+      const doc = 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 });
+    } catch (err) {
+      results.push({ key, error: err.message, success: false });
+    }
+  }
+  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: {
+      elements: pools.elements.length,
+      arrays: pools.arrays.length,
+      objects: pools.objects.length
+    }
+  };
+}
+/* ---------------- EXPORTS ---------------- */
+module.exports = {
+  Document,
+  Element,
+  Head,
+  CONFIG,
+  createCachedRenderer,
+  clearCache,
+  enableCompression,
+  responseCache,
+  warmupCache,
+  getCacheStats
+};

package/package.json ADDED Viewed

@@ -0,0 +1,37 @@
+{
+  "name": "@trebor/buildhtml",
+  "version": "1.0.0",
+  "description": "Zero-dependency, ultra-fast HTML builder for server-side rendering (SSR).",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "scripts": {
+    "start": "node example/server.js",
+    "test": "node test-debug.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0trebor0/buildhtml.git"
+  },
+  "keywords": [
+    "ssr",
+    "server-side-rendering",
+    "javascript",
+    "nodejs",
+    "html-builder",
+    "buildhtml",
+    "html-builder"
+  ],
+  "author": "0trebor0 <webdevme@outlook.com>",
+  "license": "CC-BY-NC-4.0",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/0trebor0/buildhtml/issues"
+  },
+  "homepage": "https://github.com/0trebor0/buildhtml#readme"
+}