cdom 0.0.12 → 0.0.13

package/README.md

@@ -241,29 +241,146 @@ oncreate: {
 
 ### 7. Persistence
 
-Sync your signals and state automatically to `localStorage` or `sessionStorage`.
+You can store named session or state objects in Storage objects (e.g. `sessionStorage` or `localStorage`) for persistence. It will be saved any time there is a change. Objects are automatically serialized to JSON and deserialized back to objects.
+
+Both objects and strings are supported for the `storage` value (e.g., `localStorage` or `"localStorage"`).
 
 ```javascript
-// Retrieve on every access, update on every change
-oncreate: {
-    "=signal": [
-        'light', 
-        { name: 'site-theme', storage: localStorage }
-    ]
-}
+// cDOM.session is a shortcut for state with sessionStorage
+const user = session({name:'Guest', theme:'dark'}, {name:'user'});
+
+// Retrieve it elsewhere (even in another file)
+const sameUser = session.get('user');
+
+// Get or create with default value
+const score = session.get('user', {
+    defaultValue: { name: 'Guest', theme: 'dark' }
+});
+```
+
+#### How Storage Persistence Works
+
+**Important:** Storage (localStorage/sessionStorage) is used **for persistence only**, not as a reactive data source.
+
+- **On initialization**: State is loaded from storage if it exists
+- **On updates**: Changes to the state proxy automatically write to storage AND trigger reactive updates
+- **On reads**: Values are read from the in-memory reactive proxy (not from storage)
+
+**The in-memory state proxy is the source of truth for reactivity.** Storage is only used to persist state across page reloads.
+
+⚠️ **This means:**
+- Updating storage directly via `localStorage.setItem()` will **NOT** trigger UI updates
+- Updating storage via browser dev tools will **NOT** trigger UI updates
+- Changes will only be reflected after a page reload or when the state is re-initialized
+
+**To trigger reactive updates, always modify the state object itself:**
+
+```javascript
+// ✅ CORRECT - Triggers reactivity
+const user = state.get('user');
+user.name = 'Alice';  // Updates in-memory state, writes to storage, triggers UI update
+
+// ❌ WRONG - Does NOT trigger reactivity
+localStorage.setItem('user', JSON.stringify({ name: 'Alice' }));  // Only updates storage
 ```
 
-### 8. Persistence & Transformations
+### 8. Transformations
 
-Automatically cast incoming values or sync with storage.
+Automatically cast incoming values or sync with storage. Built-in transforms include: `Integer`, `Number`, `String`, `Boolean`.
 
 ```javascript
 cDOM.signal(0, { 
     name: 'count', 
-    transform: 'Integer' // Built-in: Integer, Number, String, Boolean
+    transform: 'Integer' 
 });
 ```
 
+### 9. Macros
+
+Macros allow you to define reusable logic templates entirely in JSON, without writing JavaScript. They are perfect for domain-specific calculations, complex formulas, or frequently-used patterns.
+
+#### Defining a Macro
+
+```json
+{
+  "=macro": {
+    "name": "adjusted_price",
+    "schema": {
+      "type": "object",
+      "required": ["basePrice", "taxRate"],
+      "properties": {
+        "basePrice": { "type": "number", "minimum": 0 },
+        "taxRate": { "type": "number", "minimum": 0, "maximum": 1 },
+        "discount": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "body": {
+      "*": [
+        "$.basePrice",
+        { "+": [1, "$.taxRate"] },
+        { "-": [1, "$.discount"] }
+      ]
+    }
+  }
+}
+```
+
+**Fields:**
+- **`name`**: The macro identifier (becomes a callable helper)
+- **`schema`** (optional): JSON Schema for input validation
+- **`body`**: The template structure using `$.propertyName` to reference inputs
+
+#### Calling a Macro
+
+Macros are called like any helper, but always with an object argument:
+
+```json
+{
+  "=adjusted_price": {
+    "basePrice": 100,
+    "taxRate": 0.08,
+    "discount": 0.10
+  }
+}
+```
+
+Result: `97.2` (100 × 1.08 × 0.90)
+
+#### Using State in Macros
+
+```json
+{
+  "=adjusted_price": {
+    "basePrice": "=/product/price",
+    "taxRate": "=/settings/tax",
+    "discount": 0.10
+  }
+}
+```
+
+### 10. Object-Based Helper Arguments
+
+Helpers can now accept either **positional arguments** (array) or **named arguments** (object):
+
+**Positional (traditional):**
+```json
+{ "=sum": [1, 2, 3] }
+```
+
+**Named (new):**
+```json
+{
+  "=webservice": {
+    "url": "/api/users",
+    "method": "POST",
+    "body": "=/formData"
+  }
+}
+```
+
+When an object is passed, it's treated as a single argument. To pass an array as a single argument, wrap it: `[[1, 2, 3]]`.
+
+
 ## Supported Operators and Helpers
 
 ### Operators (Structural Keys)

package/examples/dashboard.html

@@ -28,16 +28,20 @@
         schema('LogList', { type: 'array', items: 'LogEntry' });
 
         // --- STATE ---
-        const cpu = signal(45, { name: 'cpuUsage', schema: 'Percentage', transform: 'Integer', storage: localStorage });
-        const mem = signal(62, { name: 'memUsage', schema: 'Percentage', transform: 'Number', storage: localStorage });
-        const req = signal(850, { name: 'reqCount', schema: 'Metric', transform: 'Integer', storage: localStorage });
-        const lat = signal(24, { name: 'latency', schema: 'Metric', transform: 'Integer', storage: localStorage });
+        const cpu = signal.get('cpuUsage', { defaultValue: 45, schema: 'Percentage', transform: 'Integer', storage: 'localStorage' });
+        const mem = signal.get('memUsage', { defaultValue: 62, schema: 'Percentage', transform: 'Number', storage: 'localStorage' });
+        const req = signal.get('reqCount', { defaultValue: 850, schema: 'Metric', transform: 'Integer', storage: 'localStorage' });
+        const lat = signal.get('latency', { defaultValue: 24, schema: 'Metric', transform: 'Integer', storage: 'localStorage' });
 
-        const history = state(Array(30).fill(30), { name: 'perfHistory', storage: localStorage });
-        const logs = state([
-            { t: '08:00:00.00', m: 'Security protocol initialized', s: 'info' },
-            { t: '08:01:00.00', m: 'Node cluster synced', s: 'info' }
-        ], { name: 'liveLogs', schema: 'LogList', storage: localStorage });
+        const history = state.get('perfHistory', { defaultValue: Array(30).fill(30), storage: 'localStorage' });
+        const logs = state.get('liveLogs', {
+            defaultValue: [
+                { t: '08:00:00.00', m: 'Security protocol initialized', s: 'info' },
+                { t: '08:01:00.00', m: 'Node cluster synced', s: 'info' }
+            ],
+            schema: 'LogList',
+            storage: 'localStorage'
+        });
 
         // --- CUSTOM HELPERS ---
         // Only keeping the one specific to business logic (Class generation)

package/examples/macros.html

@@ -0,0 +1,341 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>cDOM Macro System Test</title>
+    <script src="../index.js"></script>
+    <style>
+        body {
+            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+            max-width: 800px;
+            margin: 40px auto;
+            padding: 20px;
+            background: #f5f5f5;
+        }
+
+        .test-section {
+            background: white;
+            padding: 20px;
+            margin: 20px 0;
+            border-radius: 8px;
+            box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+        }
+
+        h2 {
+            color: #333;
+            border-bottom: 2px solid #4CAF50;
+            padding-bottom: 10px;
+        }
+
+        .result {
+            background: #e8f5e9;
+            padding: 10px;
+            border-left: 4px solid #4CAF50;
+            margin: 10px 0;
+            font-weight: bold;
+        }
+
+        code {
+            background: #f0f0f0;
+            padding: 2px 6px;
+            border-radius: 3px;
+            font-family: 'Courier New', monospace;
+        }
+
+        pre {
+            background: #1e1e1e;
+            color: #d4d4d4;
+            padding: 15px;
+            border-radius: 5px;
+            overflow-x: auto;
+            font-family: 'Consolas', 'Monaco', 'Courier New', monospace;
+            font-size: 14px;
+            line-height: 1.4;
+            margin: 10px 0;
+        }
+
+        .json-label {
+            font-size: 12px;
+            color: #888;
+            margin-bottom: 4px;
+            text-transform: uppercase;
+            letter-spacing: 0.05em;
+        }
+    </style>
+</head>
+
+<body>
+    <h1>🔧 cDOM Macro System Test</h1>
+
+    <div id="app"></div>
+
+    <script>
+        const { state } = cDOM;
+
+        // Create test state
+        const testState = state({
+            basePrice: 100,
+            taxRate: 0.08,
+            discount: 0.10
+        }, { name: 'pricing' });
+
+        cDOM({
+            "div": {
+                "children": [
+                    {
+                        "div": {
+                            "class": "test-section",
+                            "children": [
+                                { "h2": { "children": ["Test 1: Define Macro"] } },
+                                { "p": { "children": ["Defining a macro called 'adjusted_price' with schema validation..."] } },
+                                { "div": { "class": "json-label", "children": ["Macro Definition:"] } },
+                                {
+                                    "pre": {
+                                        "children": [
+                                            JSON.stringify({
+                                                "=macro": {
+                                                    "name": "adjusted_price",
+                                                    "schema": {
+                                                        "type": "object",
+                                                        "required": ["basePrice", "taxRate"],
+                                                        "properties": {
+                                                            "basePrice": { "type": "number", "minimum": 0 },
+                                                            "taxRate": { "type": "number", "minimum": 0, "maximum": 1 },
+                                                            "discount": { "type": "number", "minimum": 0, "maximum": 1 }
+                                                        }
+                                                    },
+                                                    "body": {
+                                                        "*": [
+                                                            "$.basePrice",
+                                                            { "+": [1, "$.taxRate"] },
+                                                            { "-": [1, "$.discount"] }
+                                                        ]
+                                                    }
+                                                }
+                                            }, null, 4)
+                                        ]
+                                    }
+                                },
+                                {
+                                    "=macro": {
+                                        "name": "adjusted_price",
+                                        "schema": {
+                                            "type": "object",
+                                            "required": ["basePrice", "taxRate"],
+                                            "properties": {
+                                                "basePrice": { "type": "number", "minimum": 0 },
+                                                "taxRate": { "type": "number", "minimum": 0, "maximum": 1 },
+                                                "discount": { "type": "number", "minimum": 0, "maximum": 1 }
+                                            }
+                                        },
+                                        "body": {
+                                            "*": [
+                                                "$.basePrice",
+                                                { "+": [1, "$.taxRate"] },
+                                                { "-": [1, "$.discount"] }
+                                            ]
+                                        }
+                                    }
+                                },
+                                {
+                                    "div": {
+                                        "class": "result",
+                                        "children": ["✓ Macro registered successfully"]
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    {
+                        "div": {
+                            "class": "test-section",
+                            "children": [
+                                { "h2": { "children": ["Test 2: Call Macro with Literal Values"] } },
+                                { "p": { "children": ["Calling macro with basePrice=100, taxRate=0.08, discount=0.10"] } },
+                                { "div": { "class": "json-label", "children": ["Macro Invocation:"] } },
+                                {
+                                    "pre": {
+                                        "children": [
+                                            JSON.stringify({
+                                                "=adjusted_price": {
+                                                    "basePrice": 100,
+                                                    "taxRate": 0.08,
+                                                    "discount": 0.10
+                                                }
+                                            }, null, 4)
+                                        ]
+                                    }
+                                },
+                                {
+                                    "div": {
+                                        "class": "result",
+                                        "children": [
+                                            "Result: $",
+                                            {
+                                                "=adjusted_price": {
+                                                    "basePrice": 100,
+                                                    "taxRate": 0.08,
+                                                    "discount": 0.10
+                                                }
+                                            }
+                                        ]
+                                    }
+                                },
+                                { "p": { "children": ["Expected: $97.20 (100 × 1.08 × 0.90)"] } }
+                            ]
+                        }
+                    },
+                    {
+                        "div": {
+                            "class": "test-section",
+                            "children": [
+                                { "h2": { "children": ["Test 3: Call Macro with State References"] } },
+                                { "p": { "children": ["Calling macro with values from state..."] } },
+                                { "div": { "class": "json-label", "children": ["Macro Invocation (State References):"] } },
+                                {
+                                    "pre": {
+                                        "children": [
+                                            JSON.stringify({
+                                                "=adjusted_price": {
+                                                    "basePrice": "=/pricing/basePrice",
+                                                    "taxRate": "=/pricing/taxRate",
+                                                    "discount": "=/pricing/discount"
+                                                }
+                                            }, null, 4)
+                                        ]
+                                    }
+                                },
+                                {
+                                    "div": {
+                                        "class": "result",
+                                        "children": [
+                                            "Result: $",
+                                            {
+                                                "=adjusted_price": {
+                                                    "basePrice": "=/pricing/basePrice",
+                                                    "taxRate": "=/pricing/taxRate",
+                                                    "discount": "=/pricing/discount"
+                                                }
+                                            }
+                                        ]
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    {
+                        "div": {
+                            "class": "test-section",
+                            "children": [
+                                { "h2": { "children": ["Test 4: Macro Without Schema"] } },
+                                { "p": { "children": ["Defining a simple macro without schema validation..."] } },
+                                { "div": { "class": "json-label", "children": ["Macro Definition:"] } },
+                                {
+                                    "pre": {
+                                        "children": [
+                                            JSON.stringify({
+                                                "=macro": {
+                                                    "name": "simple_sum",
+                                                    "body": { "+": ["$.a", "$.b"] }
+                                                }
+                                            }, null, 4)
+                                        ]
+                                    }
+                                },
+                                {
+                                    "=macro": {
+                                        "name": "simple_sum",
+                                        "body": { "+": ["$.a", "$.b"] }
+                                    }
+                                },
+                                { "p": { "class": "success", "children": ["✓ simple_sum macro registered (no schema)"] } },
+                                { "p": { "children": ["Calling: simple_sum(a=10, b=25)"] } },
+                                { "div": { "class": "json-label", "children": ["Macro Invocation:"] } },
+                                {
+                                    "pre": {
+                                        "children": [
+                                            JSON.stringify({
+                                                "=simple_sum": {
+                                                    "a": 10,
+                                                    "b": 25
+                                                }
+                                            }, null, 4)
+                                        ]
+                                    }
+                                },
+                                {
+                                    "div": {
+                                        "class": "result",
+                                        "children": [
+                                            "Result: ",
+                                            {
+                                                "=simple_sum": {
+                                                    "a": 10,
+                                                    "b": 25
+                                                }
+                                            },
+                                            " (Expected: 35)"
+                                        ]
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    {
+                        "div": {
+                            "class": "test-section",
+                            "children": [
+                                { "h2": { "children": ["Test 5: Macro With String Operations"] } },
+                                { "p": { "children": ["A macro that formats a greeting..."] } },
+                                { "div": { "class": "json-label", "children": ["Macro Definition:"] } },
+                                {
+                                    "pre": {
+                                        "children": [
+                                            JSON.stringify({
+                                                "=macro": {
+                                                    "name": "greeting",
+                                                    "body": { "=concat": ["Hello, ", "$.name", "!"] }
+                                                }
+                                            }, null, 4)
+                                        ]
+                                    }
+                                },
+                                {
+                                    "=macro": {
+                                        "name": "greeting",
+                                        "body": { "=concat": ["Hello, ", "$.name", "!"] }
+                                    }
+                                },
+                                { "p": { "class": "success", "children": ["✓ greeting macro registered"] } },
+                                { "div": { "class": "json-label", "children": ["Macro Invocation:"] } },
+                                {
+                                    "pre": {
+                                        "children": [
+                                            JSON.stringify({
+                                                "=greeting": { "name": "World" }
+                                            }, null, 4)
+                                        ]
+                                    }
+                                },
+                                {
+                                    "div": {
+                                        "class": "result",
+                                        "children": [
+                                            {
+                                                "=greeting": { "name": "World" }
+                                            }
+                                        ]
+                                    }
+                                }
+                            ]
+                        }
+                    }
+                ]
+            }
+        }, document.getElementById('app'));
+    </script>
+</body>
+
+</html>

package/examples/spreadsheet.cdom

@@ -21,7 +21,8 @@
           }
         },
         {
-          "name": "appState"
+          "name": "appState",
+           "storage": "localStorage"
         }
       ]
     },

package/index.js

@@ -24,30 +24,16 @@
         return val;
     }
 
-    function createPathFunction(pathStr, rootType) {
-        const parts = pathStr.split(/[./]/).filter(p => p !== '');
-        return (ctx, ev) => {
-            let current;
-            let start = 0;
-
-            if (rootType === '$this') current = ctx;
-            else if (rootType === '$event') current = ev;
-            else {
-                current = findInScope(ctx, parts[0]);
-                if (current === undefined) current = getHelper(parts[0]);
-
-                if (current !== undefined) start = 1;
-                else return undefined;
-            }
+    const getStorage = (s) => {
+        if (!s) return null;
+        if (typeof s === 'object') return s;
+        try {
+            if (s === 'localStorage' || s === 'window.localStorage') return globalThis.localStorage;
+            if (s === 'sessionStorage' || s === 'window.sessionStorage') return globalThis.sessionStorage;
+        } catch (e) { /* Storage might be blocked */ }
+        return null;
+    };
 
-            for (let i = start; i < parts.length; i++) {
-                if (current === null || current === undefined) return undefined;
-                current = unwrap(current);
-                current = current[parts[i]];
-            }
-            return current;
-        };
-    }
 
     function createExpression(text) {
         let at = 0;
@@ -312,6 +298,32 @@
                 if (path.startsWith('$event.') || path.startsWith('$event/')) return createPathFunction(path.slice(7), '$event');
             }
 
+            // Handle $.propertyName (macro argument reference)
+            if (t === '$') {
+                const p = peek();
+                if (p === '.') {
+                    next(); // consume '.'
+                    let path = '';
+                    while (true) {
+                        const tok = peek();
+                        if (tok && /^[\w$]/.test(tok)) {
+                            path += next();
+                        } else if (tok === '.' || tok === '/') {
+                            const nextTok = peek(1);
+                            if (nextTok && /^[\w$]/.test(nextTok)) {
+                                path += next(); // eat . or /
+                                path += next(); // eat identifier
+                            } else {
+                                break;
+                            }
+                        } else {
+                            break;
+                        }
+                    }
+                    return createPathFunction(path, '$macro');
+                }
+            }
+
             // Bareword: helper or error
             return (ctx, ev) => {
                 const val = findInScope(ctx, t) || getHelper(t);
@@ -422,7 +434,7 @@
 
     function signal(val, options = {}) {
         const name = options.name;
-        const storage = options.storage;
+        const storage = getStorage(options.storage);
         const schema = options.schema;
         const transform = options.transform;
 
@@ -437,16 +449,27 @@
         if (name && storage) {
             const stored = storage.getItem(name);
             if (stored !== null) {
-                try { value = JSON.parse(stored); } catch (e) { /* ignore */ }
+                try {
+                    const parsed = JSON.parse(stored);
+                    value = applyTransform(parsed);
+                } catch (e) { /* ignore */ }
             }
         }
+        if (schema) validate(value, schema);
 
         const s = {
             get value() {
                 if (name && storage) {
                     const stored = storage.getItem(name);
                     if (stored !== null) {
-                        try { value = JSON.parse(stored); } catch (e) { /* ignore */ }
+                        try {
+                            const parsed = JSON.parse(stored);
+                            const transformed = applyTransform(parsed);
+                            if (transformed !== value) {
+                                value = transformed;
+                                if (schema) validate(value, schema);
+                            }
+                        } catch (e) { /* ignore */ }
                     }
                 }
                 if (currentSubscriber) registerDependency(name);
@@ -469,9 +492,15 @@
         return s;
     }
 
+    signal.get = function (name, options = {}) {
+        if (registry.has(name)) return registry.get(name);
+        const val = options.defaultValue !== undefined ? options.defaultValue : null;
+        return signal(val, { ...options, name });
+    };
+
     function state(val, options = {}) {
         const name = options.name;
-        const storage = options.storage;
+        const storage = getStorage(options.storage);
         const schema = options.schema;
         const transform = options.transform;
 
@@ -488,15 +517,27 @@
             if (name && storage) {
                 const stored = storage.getItem(name);
                 if (stored !== null) {
-                    try { value = JSON.parse(stored); } catch (e) { /* ignore */ }
+                    try {
+                        const parsed = JSON.parse(stored);
+                        value = applyTransform(parsed);
+                    } catch (e) { /* ignore */ }
                 }
             }
+            if (schema) validate(value, schema);
+
             if (name && storage) {
                 result = {
                     get value() {
                         const stored = storage.getItem(name);
                         if (stored !== null) {
-                            try { value = JSON.parse(stored); } catch (e) { /* ignore */ }
+                            try {
+                                const parsed = JSON.parse(stored);
+                                const transformed = applyTransform(parsed);
+                                if (transformed !== value) {
+                                    value = transformed;
+                                    if (schema) validate(value, schema);
+                                }
+                            } catch (e) { /* ignore */ }
                         }
                         if (currentSubscriber) registerDependency(name);
                         return value;
@@ -515,7 +556,7 @@
             }
         } else {
             // Deep reactive proxy
-            const makeReactive = (target, path = [], rootObj = val) => {
+            const makeReactive = (target, path = [], rootObj = target) => {
                 // Initial load for root
                 if (path.length === 0 && name && storage) {
                     const stored = storage.getItem(name);
@@ -528,34 +569,18 @@
                         } catch (e) { /* ignore */ }
                     }
                 }
+                if (path.length === 0 && schema) validate(target, schema);
 
                 return new Proxy(target, {
                     get(t, prop) {
                         if (typeof prop !== 'string' || prop === 'constructor' || prop === 'toJSON') return t[prop];
                         if (prop === '_lv_is_proxy') return true;
 
-                        let currentVal = t[prop];
-                        if (name && storage) {
-                            const stored = storage.getItem(name);
-                            if (stored !== null) {
-                                try {
-                                    const root = JSON.parse(stored);
-                                    let nav = root;
-                                    for (const p of path) {
-                                        if (nav && typeof nav === 'object') nav = nav[p];
-                                        else { nav = undefined; break; }
-                                    }
-                                    if (nav && typeof nav === 'object' && nav[prop] !== undefined) {
-                                        currentVal = nav[prop];
-                                    }
-                                } catch (e) { /* ignore */ }
-                            }
-                        }
-
                         if (currentSubscriber) {
                             registerDependency(name);
                         }
 
+                        const currentVal = t[prop];
                         // Recursively wrap nested objects
                         if (currentVal && typeof currentVal === 'object' && !Array.isArray(currentVal)) {
                             return makeReactive(currentVal, [...path, prop], rootObj);
@@ -566,7 +591,6 @@
                         const transformed = applyTransform(value);
                         if (schema) {
                             // Validate the entire root object after this change would be applied
-                            // but since we want to be safe, we can dry-run the change
                             const backup = t[prop];
                             t[prop] = transformed;
                             try {
@@ -595,7 +619,18 @@
         return result;
     }
 
-    state.get = (name) => registry.get(name);
+    state.get = function (name, options = {}) {
+        if (registry.has(name)) return registry.get(name);
+        const val = options.defaultValue !== undefined ? options.defaultValue : null;
+        return state(val, { ...options, name });
+    };
+
+    const session = (val, options = {}) => state(val, { ...options, storage: globalThis.sessionStorage });
+    session.get = function (name, options = {}) {
+        if (registry.has(name)) return registry.get(name);
+        const val = options.defaultValue !== undefined ? options.defaultValue : null;
+        return state(val, { ...options, name, storage: globalThis.sessionStorage });
+    };
 
     function registerDependency(name) {
         if (!name || !currentSubscriber) return;
@@ -717,6 +752,56 @@
     helpers.set('Number', v => Number(v));
     helpers.set('String', v => String(v));
     helpers.set('Boolean', v => !!v);
+    helpers.set('signal', signal);
+    helpers.set('state', state);
+    helpers.set('session', session);
+    helpers.set('signal.get', signal.get);
+    helpers.set('state.get', state.get);
+    helpers.set('session.get', session.get);
+
+    // Macro helper - creates reusable JSON templates
+    helpers.set('macro', function (definition) {
+        const { name, schema: macroSchema, body } = definition;
+        if (!name || !body) {
+            console.error('[cDOM] Macro definition requires "name" and "body"');
+            return;
+        }
+
+        // Register the macro as a new helper
+        const macroFn = function (input) {
+            // Note: input is already resolved by evaluateStructural
+            // Validate input if schema is provided
+            if (macroSchema) {
+                try {
+                    validate(input, macroSchema);
+                } catch (e) {
+                    console.error(`[cDOM] Macro "${name}" validation error:`, e);
+                    throw e;
+                }
+            }
+
+            // Evaluate the body with macro context
+            return evaluateMacroBody(body, this, null, input);
+        };
+
+        // Mark this as a macro so evaluateStructural knows to resolve the object first
+        macroFn.isMacro = true;
+
+        helpers.set(name, macroFn);
+        return `[Macro ${name} registered]`;
+    });
+
+    // Mark macro helper to skip object resolution - it needs the raw definition
+    helpers.get('macro').skipObjectResolution = true;
+
+    // Helper function to evaluate macro body with $ context
+    function evaluateMacroBody(body, context, event, macroContext) {
+        // Store the current macro context on the element
+        // This persists so async helper loading can still access it
+        context._macroContext = macroContext;
+        return evaluateStructural(body, context, event, false);
+    }
+
 
     function getHelper(name, unsafe) {
         if (helpers.has(name)) return helpers.get(name);
@@ -795,7 +880,13 @@
 
 
     function evaluateStructural(obj, context, event, unsafe) {
-        if (typeof obj !== 'object' || obj === null || obj.nodeType) return obj;
+        if (typeof obj !== 'object' || obj === null || obj.nodeType) {
+            // Check if it's a string starting with '$.' (macro argument reference)
+            if (typeof obj === 'string' && obj.startsWith('$.')) {
+                return evaluateStateExpression(obj, context, event);
+            }
+            return obj;
+        }
         obj = unwrap(obj);
 
         if (Array.isArray(obj)) {
@@ -827,10 +918,42 @@
             const helperName = alias || key.slice(1);
             const helperFn = getHelper(helperName, unsafe);
             if (helperFn) {
+                // If val is an object (not array), treat as single named-argument object
+                // UNLESS the helper has skipObjectResolution flag (like macro)
+                if (!Array.isArray(val) && typeof val === 'object' && val !== null) {
+                    // If helper wants raw object, pass it directly
+                    if (helperFn.skipObjectResolution) {
+                        return helperFn.call(context, val);
+                    }
+
+                    // Otherwise resolve the object properties
+                    const resolvedObj = {};
+                    for (const k of Object.keys(val)) {
+                        const v = val[k];
+                        const isPath = typeof v === 'string' && (
+                            v.startsWith('=/') ||
+                            v.startsWith('$.') ||
+                            v === '$this' || v.startsWith('$this/') || v.startsWith('$this.') ||
+                            v === '$event' || v.startsWith('$event/') || v.startsWith('$event.')
+                        );
+
+                        if (isPath) {
+                            resolvedObj[k] = unwrap(evaluateStateExpression(v, context, event));
+                        } else if (typeof v === 'object' && v !== null && !v.nodeType) {
+                            resolvedObj[k] = evaluateStructural(v, context, event, unsafe);
+                        } else {
+                            resolvedObj[k] = v;
+                        }
+                    }
+                    return helperFn.call(context, resolvedObj);
+                }
+
+                // Otherwise, treat as array of positional arguments
                 const args = Array.isArray(val) ? val : [val];
                 const resolvedArgs = args.map(arg => {
                     const isPath = typeof arg === 'string' && (
                         arg.startsWith('=/') ||
+                        arg.startsWith('$.') ||
                         arg === '$this' || arg.startsWith('$this/') || arg.startsWith('$this.') ||
                         arg === '$event' || arg.startsWith('$event/') || arg.startsWith('$event.')
                     );
@@ -842,10 +965,10 @@
                             if (p) {
                                 let path = arg;
                                 if (p === 'state') path = arg.slice(2); // Remove =/ prefix
-                                return createPathFunction(path, p)(context, event);
+                                return createPathFunction(path, p)(context, event, context._macroContext);
                             }
                         }
-                        return evaluateStateExpression(arg, context, event);
+                        return unwrap(evaluateStateExpression(arg, context, event));
                     }
                     if (typeof arg === 'object' && arg !== null && !arg.nodeType) {
                         return evaluateStructural(arg, context, event, unsafe);
@@ -929,10 +1052,22 @@
             let root;
             if (type === '$this') root = ctx;
             else if (type === '$event') root = ev;
+            else if (type === '$macro') root = ctx?._macroContext;
             else root = findInScope(ctx, name);
 
             if (!root) return (type === 'state') ? `[Unknown: ${name}]` : undefined;
 
+            // For $macro, we access the property directly on the macro context
+            if (type === '$macro') {
+                if (parts.length === 0) return root;
+                let target = root;
+                for (const part of parts) {
+                    if (target === undefined || target === null) return undefined;
+                    target = target[part];
+                }
+                return target;
+            }
+
             // For root-only access
             if (path.length === 0) {
                 if (type === 'state' && currentSubscriber) registerDependency(name);
@@ -1460,6 +1595,7 @@
     // Export to global scope
     cDOM.signal = signal;
     cDOM.state = state;
+    cDOM.session = session;
     cDOM.helper = helper;
     cDOM.schema = schema;
     cDOM.validate = validate;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdom",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Safe, reactive UIs based on JSON Pointer, XPath, JSON Schema",
   "keywords": [
     "JPRX",