New docs

src/docs/api/html.md

@@ -0,0 +1,103 @@
+# Rendering Engine: `$.html`
+
+The `$.html` function is the architect of your UI. It creates standard HTML elements and wires them directly to your signals without the need for a Virtual DOM.
+
+## 1. Syntax: `$.html(tag, [props], [content])`
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **tag** | `string` | **Yes** | Any valid HTML5 tag (e.g., `'div'`, `'button'`, `'input'`). |
+| **props** | `Object` | No | Attributes, event listeners, and reactive bindings. |
+| **content** | `any` | No | Text, Nodes, Arrays, or Reactive Functions. |
+
+### Example:
+```javascript
+const myButton = $.html('button', { class: 'btn-primary' }, 'Click me');
+```
+
+---
+
+## 2. Global Tag Helpers
+
+To avoid repetitive `$.html` calls, SigPro automatically exposes common tags to the global `window` object. This allows for a clean, declarative syntax.
+
+```javascript
+// Instead of $.html('div', ...), just use:
+div({ id: 'wrapper' }, [
+  h1("Welcome"),
+  p("This is SigPro.")
+]);
+```
+
+---
+
+## 3. Handling Properties & Attributes
+
+SigPro distinguishes between static attributes and reactive bindings using the **`$` prefix**.
+
+### Static vs. Reactive Attributes
+* **Static:** Applied once during creation.
+* **Reactive (`$`):** Automatically updates the DOM when the signal changes.
+
+| Property | Syntax | Result |
+| :--- | :--- | :--- |
+| **Attribute** | `{ id: 'main' }` | `id="main"` |
+| **Event** | `{ onclick: fn }` | Adds an event listener. |
+| **Reactive Attr** | `{ $class: $theme }` | Updates `class` whenever `$theme()` changes. |
+| **Boolean Attr** | `{ $disabled: $isBusy }` | Toggles the `disabled` attribute automatically. |
+
+
+
+---
+
+## 4. Two-Way Data Binding
+
+For form inputs, SigPro provides a powerful shortcut using `$value` or `$checked`. It automatically handles the event listening and the value synchronization.
+
+```javascript
+const $text = $("Type here...");
+
+input({ 
+  type: 'text', 
+  $value: $text // Syncs input -> signal and signal -> input
+});
+
+p(["You typed: ", $text]);
+```
+
+---
+
+## 5. Reactive Content (Dynamic Children)
+
+The `content` argument is incredibly flexible. If you pass a **function**, SigPro treats it as a reactive "portal" that re-renders only that specific part of the DOM.
+
+### Text & Nodes
+```javascript
+const $count = $(0);
+
+// Text node updates surgically
+div(["Count: ", $count]); 
+
+// Conditional rendering with a function
+div(() => {
+  return $count() > 10 
+    ? h1("High Score!") 
+    : p("Keep going...");
+});
+```
+
+### The "Guillotine" (Performance Tip)
+When a reactive function in the content returns a **new Node**, SigPro uses `replaceWith()` to swap the old node for the new one. This ensures that:
+1. The update is nearly instantaneous.
+2. The old node is correctly garbage-collected.
+
+---
+
+## 6. Summary: Content Types
+
+| Input | Behavior |
+| :--- | :--- |
+| **String / Number** | Appended as a TextNode. |
+| **HTMLElement** | Appended directly to the parent. |
+| **Array** | Each item is processed and appended in order. |
+| **Function `() => ...`** | Creates a **live reactive zone** that updates automatically. |