cdom 0.0.13 → 0.0.15

package/README.md

@@ -316,9 +316,9 @@ Macros allow you to define reusable logic templates entirely in JSON, without wr
     },
     "body": {
       "*": [
-        "$.basePrice",
-        { "+": [1, "$.taxRate"] },
-        { "-": [1, "$.discount"] }
+        "=$.basePrice",
+        { "+": [1, "=$.taxRate"] },
+        { "-": [1, "=$.discount"] }
       ]
     }
   }
@@ -328,7 +328,7 @@ Macros allow you to define reusable logic templates entirely in JSON, without wr
 **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
+- **`body`**: The template structure using `=$.propertyName` to reference inputs
 
 #### Calling a Macro
 
@@ -358,9 +358,67 @@ Result: `97.2` (100 × 1.08 × 0.90)
 }
 ```
 
-### 10. Object-Based Helper Arguments
+### 10. Hypermedia Query Parameters (`$query`)
 
-Helpers can now accept either **positional arguments** (array) or **named arguments** (object):
+When loading `.cdom` files via the `src` or `href` attributes, you can pass parameters via the query string. These parameters are automatically available within the loaded component as **implicit macro arguments**.
+
+#### Basic Usage
+
+URL: `profile.cdom?name=Joe&id=123`
+
+```json
+{
+  "div": {
+    "children": [
+      { "h2": ["Hello, ", "=$.name"] },
+      { "p": ["User ID: ", "=$.id"] }
+    ]
+  }
+}
+```
+
+#### Collision Resolution (`=$query`)
+
+If you are inside a macro that uses the same argument name as a query parameter, the macro argument **shadows** the query parameter. To access the original URL parameters explicitly, use the `=$query` sigil.
+
+```json
+{
+  "=greet": { "name": "MacroUser" } 
+}
+// Inside the greet macro body:
+{ "p": ["Hello ", "=$.name"] }       // Returns "Hello MacroUser"
+{ "p": ["Original ", "=$query.name"] } // Returns "Original Joe"
+```
+
+### 11. The Dynamic Sigil Standard (`=`)
+
+To ensure zero ambiguity between literal strings and dynamic references, cDOM follows a strict rule: **Everything dynamic starts with `=`.**
+
+| Sigil | Target | Description |
+| :--- | :--- | :--- |
+| **`=/`** | Global State | Look up value in in-memory state proxy |
+| **`=$.`** | Macro Argument | Reference an input passed to the current macro |
+| **`=$this`** | Context Node | Reference the current DOM element |
+| **`=$event`** | Logic Event | Reference the current DOM event (in handlers) |
+| **`=$query`** | URL Query | Explicitly access Hypermedia URL parameters |
+
+#### Shorthand Child Evaluation
+As of v2.6.0, you can place these strings directly as children without an object wrapper:
+
+```json
+// ✅ Cleanest (Recommended)
+{ "h1": "=$.title" }
+
+// ✅ Also works
+{ "h1": { "=": "=$.title" } }
+
+// ⚠️ Deprecated
+{ "h1": { "=": "$.title" } }
+```
+
+### 11. Object-Based Helper Arguments
+
+Helpers can accept either **positional arguments** (array) or **named arguments** (object):
 
 **Positional (traditional):**
 ```json

package/examples/dashboard.html

@@ -143,12 +143,12 @@
                                 {
                                     "div": {
                                         "class": "grid", "children": [
-                                            Metric('Process Load', { "=": "=/cpuUsage" }, '%', '⚡'),
+                                            Metric('Process Load', "=/cpuUsage", '%', '⚡'),
                                             // Using standard helpers 'round'
-                                            Metric('Memory Heap', { "=round": [{ "=": "=/memUsage" }, 1] }, '%', '💾'),
+                                            Metric('Memory Heap', { "=round": ["=/memUsage", 1] }, '%', '💾'),
                                             // Using standard helpers 'fixed' and 'divide'
-                                            Metric('Net Throughput', { "=fixed": [{ "=divide": [{ "=": "=/reqCount" }, 10] }, 1] }, 'k/s', '🚀'),
-                                            Metric('Network Jitter', { "=": "=/latency" }, 'ms', '📡')
+                                            Metric('Net Throughput', { "=fixed": [{ "=divide": ["=/reqCount", 10] }, 1] }, 'k/s', '🚀'),
+                                            Metric('Network Jitter', "=/latency", 'ms', '📡')
                                         ]
                                     }
                                 },

package/examples/hypermedia-demo.html

@@ -0,0 +1,206 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>cDOM | Hypermedia & $query Demo</title>
+    <script src="../index.js"></script>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono&display=swap"
+        rel="stylesheet">
+    <style>
+        :root {
+            --primary: #6366f1;
+            --bg: #f8fafc;
+            --card-bg: #ffffff;
+            --text: #1e293b;
+            --code-bg: #1e1e2e;
+        }
+
+        body {
+            font-family: 'Inter', sans-serif;
+            background-color: var(--bg);
+            color: var(--text);
+            margin: 0;
+            padding: 2rem;
+            line-height: 1.5;
+        }
+
+        .container {
+            max-width: 1000px;
+            margin: 0 auto;
+        }
+
+        header {
+            margin-bottom: 3rem;
+            text-align: center;
+        }
+
+        h1 {
+            font-weight: 800;
+            letter-spacing: -0.025em;
+            margin-bottom: 0.5rem;
+        }
+
+        .subtitle {
+            color: #64748b;
+            font-size: 1.125rem;
+        }
+
+        .demo-grid {
+            display: grid;
+            grid-template-columns: 1fr 1fr;
+            gap: 2rem;
+            margin-bottom: 4rem;
+        }
+
+        @media (max-width: 768px) {
+            .demo-grid {
+                grid-template-columns: 1fr;
+            }
+        }
+
+        .panel {
+            background: var(--card-bg);
+            border-radius: 16px;
+            border: 1px solid #e2e8f0;
+            overflow: hidden;
+            display: flex;
+            flex-direction: column;
+        }
+
+        .panel-header {
+            padding: 0.75rem 1.25rem;
+            background: #f1f5f9;
+            border-bottom: 1px solid #e2e8f0;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+        }
+
+        .panel-title {
+            font-size: 0.75rem;
+            font-weight: 700;
+            text-transform: uppercase;
+            letter-spacing: 0.05em;
+            color: #64748b;
+        }
+
+        .url-badge {
+            font-family: 'JetBrains Mono', monospace;
+            font-size: 0.75rem;
+            background: #e2e8f0;
+            padding: 0.2rem 0.6rem;
+            border-radius: 4px;
+            color: #475569;
+        }
+
+        .preview-area {
+            padding: 2rem;
+            flex: 1;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            background-image: radial-gradient(#e2e8f0 1px, transparent 1px);
+            background-size: 20px 20px;
+        }
+
+        .code-area {
+            background: var(--code-bg);
+            color: #cdd6f4;
+            padding: 1.5rem;
+            font-family: 'JetBrains Mono', monospace;
+            font-size: 0.875rem;
+            margin: 0;
+            overflow: auto;
+            max-height: 500px;
+        }
+
+        .tag {
+            display: inline-block;
+            padding: 0.25rem 0.75rem;
+            background: var(--primary);
+            color: white;
+            border-radius: 20px;
+            font-size: 0.75rem;
+            font-weight: 600;
+            margin-bottom: 1rem;
+        }
+
+        pre {
+            margin: 0;
+        }
+    </style>
+</head>
+
+<body>
+    <div class="container">
+        <header>
+            <div class="tag">NEW FEATURE: $QUERY</div>
+            <h1>Hypermedia & Query Parameters</h1>
+            <p class="subtitle">Demonstrating $query resolution and implicit macro arguments in loaded components.</p>
+        </header>
+
+        <section class="demo-section">
+            <div class="demo-grid">
+                <!-- Result Panel -->
+                <div class="panel">
+                    <div class="panel-header">
+                        <span class="panel-title">Rendered Output</span>
+                        <span class="url-badge">profile.cdom?name=Alice&id=USR-789</span>
+                    </div>
+                    <div class="preview-area">
+                        <!-- cDOM will load here -->
+                        <div src="profile.cdom?name=Alice&amp;role=Lead+Designer&amp;region=North+America&amp;id=USR-789"
+                            style="width: 100%; max-width: 350px;"></div>
+                    </div>
+                </div>
+
+                <!-- Code Panel -->
+                <div class="panel">
+                    <div class="panel-header">
+                        <span class="panel-title">Source: profile.cdom</span>
+                    </div>
+                    <pre class="code-area" id="code-display">Loading source code...</pre>
+                </div>
+            </div>
+        </section>
+
+        <section style="background: white; padding: 2.5rem; border-radius: 24px; border: 1px solid #e2e8f0;">
+            <h2 style="margin-top: 0;">How it works</h2>
+            <p>
+                The <code>src</code> attribute on a <code>div</code> (or any non-native element) triggers a hypermedia
+                load.
+                Any query parameters in the URL are automatically parsed and injected as <b>implicit macro
+                    arguments</b>.
+            </p>
+            <ul style="color: #475569; padding-left: 1.5rem;">
+                <li style="margin-bottom: 1rem;">
+                    <strong>$.name</strong>: Accesses the parameter from the URL context. If a local macro defines a
+                    <code>name</code> argument, it will shadow this value.
+                </li>
+                <li style="margin-bottom: 1rem;">
+                    <strong>$query.name</strong>: Explicitly accesses the URL parameter, bypassing any local macro
+                    shadowing.
+                </li>
+                <li style="margin-bottom: 1rem;">
+                    <strong>Scope Bubbling</strong>: The engine searches up the component tree to find the nearest
+                    match, ensuring that nested components can still reach global query parameters.
+                </li>
+            </ul>
+        </section>
+    </div>
+
+    <script>
+        // Fetch and display the source code of the .cdom file
+        fetch('profile.cdom')
+            .then(response => response.text())
+            .then(text => {
+                document.getElementById('code-display').textContent = text;
+            });
+    </script>
+</body>
+
+</html>

package/examples/macros.html

@@ -88,8 +88,8 @@
                         "div": {
                             "class": "test-section",
                             "children": [
-                                { "h2": { "children": ["Test 1: Define Macro"] } },
-                                { "p": { "children": ["Defining a macro called 'adjusted_price' with schema validation..."] } },
+                                { "h2": "Test 1: Define Macro" },
+                                { "p": "Defining a macro called 'adjusted_price' with schema validation..." },
                                 { "div": { "class": "json-label", "children": ["Macro Definition:"] } },
                                 {
                                     "pre": {
@@ -108,9 +108,9 @@
                                                     },
                                                     "body": {
                                                         "*": [
-                                                            "$.basePrice",
-                                                            { "+": [1, "$.taxRate"] },
-                                                            { "-": [1, "$.discount"] }
+                                                            "=$.basePrice",
+                                                            { "+": [1, "=$.taxRate"] },
+                                                            { "-": [1, "=$.discount"] }
                                                         ]
                                                     }
                                                 }
@@ -132,9 +132,9 @@
                                         },
                                         "body": {
                                             "*": [
-                                                "$.basePrice",
-                                                { "+": [1, "$.taxRate"] },
-                                                { "-": [1, "$.discount"] }
+                                                "=$.basePrice",
+                                                { "+": [1, "=$.taxRate"] },
+                                                { "-": [1, "=$.discount"] }
                                             ]
                                         }
                                     }
@@ -152,8 +152,8 @@
                         "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"] } },
+                                { "h2": "Test 2: Call Macro with Literal Values" },
+                                { "p": "Calling macro with basePrice=100, taxRate=0.08, discount=0.10" },
                                 { "div": { "class": "json-label", "children": ["Macro Invocation:"] } },
                                 {
                                     "pre": {
@@ -183,7 +183,7 @@
                                         ]
                                     }
                                 },
-                                { "p": { "children": ["Expected: $97.20 (100 × 1.08 × 0.90)"] } }
+                                { "p": "Expected: $97.20 (100 × 1.08 × 0.90)" }
                             ]
                         }
                     },
@@ -191,8 +191,8 @@
                         "div": {
                             "class": "test-section",
                             "children": [
-                                { "h2": { "children": ["Test 3: Call Macro with State References"] } },
-                                { "p": { "children": ["Calling macro with values from state..."] } },
+                                { "h2": "Test 3: Call Macro with State References" },
+                                { "p": "Calling macro with values from state..." },
                                 { "div": { "class": "json-label", "children": ["Macro Invocation (State References):"] } },
                                 {
                                     "pre": {
@@ -229,8 +229,8 @@
                         "div": {
                             "class": "test-section",
                             "children": [
-                                { "h2": { "children": ["Test 4: Macro Without Schema"] } },
-                                { "p": { "children": ["Defining a simple macro without schema validation..."] } },
+                                { "h2": "Test 4: Macro Without Schema" },
+                                { "p": "Defining a simple macro without schema validation..." },
                                 { "div": { "class": "json-label", "children": ["Macro Definition:"] } },
                                 {
                                     "pre": {
@@ -238,7 +238,7 @@
                                             JSON.stringify({
                                                 "=macro": {
                                                     "name": "simple_sum",
-                                                    "body": { "+": ["$.a", "$.b"] }
+                                                    "body": { "+": ["=$.a", "=$.b"] }
                                                 }
                                             }, null, 4)
                                         ]
@@ -247,11 +247,11 @@
                                 {
                                     "=macro": {
                                         "name": "simple_sum",
-                                        "body": { "+": ["$.a", "$.b"] }
+                                        "body": { "+": ["=$.a", "=$.b"] }
                                     }
                                 },
                                 { "p": { "class": "success", "children": ["✓ simple_sum macro registered (no schema)"] } },
-                                { "p": { "children": ["Calling: simple_sum(a=10, b=25)"] } },
+                                { "p": "Calling: simple_sum(a=10, b=25)" },
                                 { "div": { "class": "json-label", "children": ["Macro Invocation:"] } },
                                 {
                                     "pre": {
@@ -287,8 +287,8 @@
                         "div": {
                             "class": "test-section",
                             "children": [
-                                { "h2": { "children": ["Test 5: Macro With String Operations"] } },
-                                { "p": { "children": ["A macro that formats a greeting..."] } },
+                                { "h2": "Test 5: Macro With String Operations" },
+                                { "p": "A macro that formats a greeting..." },
                                 { "div": { "class": "json-label", "children": ["Macro Definition:"] } },
                                 {
                                     "pre": {
@@ -296,7 +296,7 @@
                                             JSON.stringify({
                                                 "=macro": {
                                                     "name": "greeting",
-                                                    "body": { "=concat": ["Hello, ", "$.name", "!"] }
+                                                    "body": { "=concat": ["Hello, ", "=$.name", "!"] }
                                                 }
                                             }, null, 4)
                                         ]
@@ -305,7 +305,7 @@
                                 {
                                     "=macro": {
                                         "name": "greeting",
-                                        "body": { "=concat": ["Hello, ", "$.name", "!"] }
+                                        "body": { "=concat": ["Hello, ", "=$.name", "!"] }
                                     }
                                 },
                                 { "p": { "class": "success", "children": ["✓ greeting macro registered"] } },

package/examples/profile.cdom

@@ -0,0 +1,64 @@
+{
+  "div": {
+    "class": "profile-card",
+    "style": "padding: 1.5rem; background: white; border-radius: 12px; box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1); border: 1px solid #e5e7eb; font-family: 'Inter', sans-serif;",
+    "children": [
+      {
+        "div": {
+          "style": "display: flex; align-items: center; gap: 1rem; margin-bottom: 1rem;",
+          "children": [
+            {
+              "div": {
+                "style": "width: 48px; height: 48px; background: #6366f1; border-radius: 50%; display: flex; align-items: center; justify-content: center; color: white; font-weight: bold; font-size: 1.25rem;",
+                "children": [{ "=left": ["=$.name", 1] }]
+              }
+            },
+            {
+              "div": {
+                "children": [
+                  { "h3": { "style": "margin: 0; color: #111827;", "children": ["=$.name"] } },
+                  { "p": { "style": "margin: 0; color: #6b7280; font-size: 0.875rem;", "children": ["=$.role"] } }
+                ]
+              }
+            }
+          ]
+        }
+      },
+      {
+        "div": {
+          "style": "font-size: 0.875rem; color: #374151; display: flex; flex-direction: column; gap: 0.5rem;",
+          "children": [
+            { "div": ["📍 Region: ", { "b": "=$.region" }] },
+            { "div": ["🔑 ID: ", { "code": "=$query.id" }] }
+          ]
+        }
+      },
+      {
+        "div": {
+          "style": "margin-top: 1.5rem; padding-top: 1rem; border-top: 1px solid #f3f4f6;",
+          "oncreate": {
+            "=macro": {
+              "name": "Badge",
+              "body": {
+                "span": {
+                  "style": "display: inline-flex; align-items: center; padding: 0.25rem 0.75rem; border-radius: 9999px; font-size: 0.75rem; font-weight: 500; background: #e0e7ff; color: #4338ca;",
+                  "children": ["=$.label"]
+                }
+              }
+            }
+          },
+          "children": [
+            { "p": { "style": "font-size: 0.75rem; color: #9ca3af; margin-bottom: 0.5rem;", "children": ["Generated via macro shadowing $.name:"] } },
+            { "=Badge": { "label": { "=concat": ["Active: ", "=$.name"] } } },
+            {
+              "p": {
+                "style": "font-size: 0.75rem; color: #9ca3af; margin-top: 0.75rem;",
+                "children": ["Original URL param accessible via $query.name: ", { "b": "=$query.name" }]
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

package/examples/query-test.html

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>cDOM Query Param Test</title>
+    <script src="../index.js"></script>
+</head>
+
+<body style="padding: 2rem; font-family: sans-serif;">
+    <h1>cDOM Query Parameter Testing</h1>
+
+    <div style="margin-bottom: 2rem;">
+        <h3>Dynamic Load (Hypermedia)</h3>
+        <p>Loading <code>profile.cdom?name=Joe&location=London&id=123</code></p>
+        <div src="profile.cdom?name=Joe&location=London&id=123"></div>
+    </div>
+
+    <hr>
+
+    <div style="margin-bottom: 2rem;">
+        <h3>Another Load</h3>
+        <p>Loading <code>profile.cdom?name=Alice&location=New York&id=456</code></p>
+        <div src="profile.cdom?name=Alice&location=New York&id=456"></div>
+    </div>
+</body>
+
+</html>

package/examples/scratch.html

@@ -1,9 +1,15 @@
+<!DOCTYPE html>
 <html>
-<script src="../index.js"></script>
 
-<body>
+<head>
+    <title>cDOM | Scratchpad</title>
+    <script src="../index.js"></script>
+</head>
+
+<body style="font-family: 'Inter', sans-serif; padding: 2rem; line-height: 1.6;">
     <script>
         const { $, _ } = cDOM;
+
         cDOM.helper('increment', (ref) => {
             if (ref && typeof ref === 'object' && 'value' in ref) ref.value++;
             else if (ref && typeof ref === 'object' && ref.count !== undefined) ref.count++;
@@ -27,42 +33,44 @@
                     console.log('App mounted to DOM!', this);
                 },
                 children: [
-                    "App Name: ", { "=": "=/appName" }, { br: {} },
-                    "Local Counter (Scoped): ", { "=": "=/localCounter/count" },
+                    { h1: "cDOM Scratchpad" },
+                    "App Name: ", "=/appName", { br: {} },
+                    "Local Counter (Scoped): ", "=/localCounter/count",
                     {
-                        button: {
-                            onclick: [
-                                { "=log": ["Starting array execution..."] },
-                                { "++": ["=/localCounter/count"] },
-                                { "=log": ["Counter is now:", "=/localCounter/count"] },
-                                { "set": ["=/appName", "cDOM Rocked!"] }
-                            ],
-                            children: ["Array Handler Demo"]
+                        div: {
+                            style: "margin: 1.5rem 0",
+                            children: [
+                                {
+                                    button: {
+                                        onclick: [
+                                            { "=log": ["Starting array execution..."] },
+                                            { "++": ["=/localCounter/count"] },
+                                            { "=log": ["Counter is now:", "=/localCounter/count"] },
+                                            { "set": ["=/appName", "cDOM Rocked!"] }
+                                        ],
+                                        children: ["Array Handler Demo"]
+                                    }
+                                }
+                            ]
                         }
                     },
                     {
                         div: {
+                            style: "background: #f8fafc; padding: 1.5rem; border-radius: 12px; border: 1px solid #e2e8f0;",
                             children: [
+                                "This div can also see the local counter: ", "=/localCounter/count",
                                 { br: {} },
-                                "This div can also see the local counter: ", { "=": "=/localCounter/count" },
-                                { br: {} },
-                                { br: {} },
-                                "Math expression (count * 2 + 5): ", { "=": "=/localCounter/count * 2 + 5" },
-                                { br: {} },
-                                { br: {} },
+                                { b: ["Math expression (count * 2 + 5): ", "=/localCounter/count * 2 + 5"] },
+                                { hr: { style: "margin: 1.5rem 0; border: 0; border-top: 1px solid #e2e8f0;" } },
                                 {
                                     div: {
-                                        style: {
-                                            "margin-top": "10px",
-                                            "color": "#666",
-                                            "font-size": "0.9em"
-                                        },
+                                        style: "font-size: 0.9em; color: #64748b; font-family: monospace;",
                                         children: [
-                                            "XPath (Active Button Count): ", { "$": "count(//button)" }, { br: {} },
-                                            "XPath (Button Label): ", { "$": "//button/text()" }, { br: {} },
-                                            "Dynamic Helper { =sum: [1, 2, 3] }: ", { "=sum": [1, 2, 3] }, { br: {} },
-                                            "Dynamic Helper{ =currency: [=/localCounter/count] }: ", { "=currency": ["=/localCounter/count"] }, { br: {} },
-                                            "Undefined Helper: ", { "=This.Should.Not.Exist": [] }
+                                            { div: ["XPath (Active Button Count): ", { "$": "count(//button)" }] },
+                                            { div: ["XPath (Button Label): ", { "$": "//button/text()" }] },
+                                            { div: ["Dynamic Helper { =sum: [1, 2, 3] }: ", { "=sum": [1, 2, 3] }] },
+                                            { div: ["Dynamic Helper { =currency: [=/localCounter/count] }: ", { "=currency": ["=/localCounter/count"] }] },
+                                            { div: ["Undefined Helper: ", { "=This.Should.Not.Exist": [] }] }
                                         ]
                                     }
                                 }
@@ -71,7 +79,7 @@
                     }
                 ]
             }
-        }, {})
+        });
     </script>
 </body>
 

package/index.js

@@ -41,7 +41,7 @@
 
         function tokenize(src) {
             const results = [];
-            const tokenRegex = /\s*(\d*\.\d+|\d+|"([^"\\]|\\.)*"|'([^'\\]|\\.)*'|=\/|\.{1,2}\/|\/|\$this|\$event|[a-zA-Z_$][\w$]*|==|!=|<=|>=|&&|\|\||[-+*/%^<>!?:.,(){}[\]])\s*/g;
+            const tokenRegex = /\s*(\d*\.\d+|\d+|"([^"\\]|\\.)*"|'([^'\\]|\\.)*'|=\/|=\$this|=\$event|=\$query|=\$|[a-zA-Z_$][\w$]*|==|!=|<=|>=|&&|\|\||[-+*/%^<>!?:.,(){}[\]])\s*/g;
             let match;
             while ((match = tokenRegex.exec(src)) !== null) {
                 results.push(match[1]);
@@ -272,9 +272,9 @@
                 return createPathFunction(path, 'state');
             }
 
-            // Handle $this and $event
-            if (t === '$this' || t === '$event') {
-                let path = t;
+            // Handle =$this and =$event
+            if (t === '=$this' || t === '=$event') {
+                let path = t.slice(1); // Remove the '=' prefix
                 // Check for property access
                 while (true) {
                     const p = peek();
@@ -292,14 +292,15 @@
                         break;
                     }
                 }
-                if (path === '$this') return (ctx) => ctx;
-                if (path === '$event') return (ctx, ev) => ev;
+                const root = path === '$this' ? (ctx) => ctx : (ctx, ev) => ev;
+                if (path === '$this') return root;
+                if (path === '$event') return root;
                 if (path.startsWith('$this.') || path.startsWith('$this/')) return createPathFunction(path.slice(6), '$this');
                 if (path.startsWith('$event.') || path.startsWith('$event/')) return createPathFunction(path.slice(7), '$event');
             }
 
-            // Handle $.propertyName (macro argument reference)
-            if (t === '$') {
+            // Handle =$.propertyName
+            if (t === '=$') {
                 const p = peek();
                 if (p === '.') {
                     next(); // consume '.'
@@ -324,6 +325,33 @@
                 }
             }
 
+            // Handle =$query.propertyName
+            if (t === '=$query') {
+                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, '$query');
+                }
+                return (ctx) => findContext(ctx, '_queryContext');
+            }
+
             // Bareword: helper or error
             return (ctx, ev) => {
                 const val = findInScope(ctx, t) || getHelper(t);
@@ -881,8 +909,8 @@
 
     function evaluateStructural(obj, context, event, unsafe) {
         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('$.')) {
+            // Check if it's a string starting with '=' (dynamic reference)
+            if (typeof obj === 'string' && obj.startsWith('=')) {
                 return evaluateStateExpression(obj, context, event);
             }
             return obj;
@@ -932,9 +960,10 @@
                         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.')
+                            v.startsWith('=$.') ||
+                            v.startsWith('=$this') ||
+                            v.startsWith('=$event') ||
+                            v.startsWith('=$query')
                         );
 
                         if (isPath) {
@@ -953,9 +982,10 @@
                 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.')
+                        arg.startsWith('=$.') ||
+                        arg.startsWith('=$this') ||
+                        arg.startsWith('=$event') ||
+                        arg.startsWith('=$query')
                     );
 
                     if (isPath) {
@@ -1018,6 +1048,15 @@
         return registry.get(name);
     }
 
+    function findContext(node, key) {
+        let curr = node;
+        while (curr) {
+            if (curr[key]) return curr[key];
+            curr = curr.parentNode || curr.host || curr._lv_parent;
+        }
+        return null;
+    }
+
     function evaluateStateExpression(expression, contextNode, event) {
         let compiled = stateExpressionCache.get(expression);
         if (!compiled) {
@@ -1052,7 +1091,8 @@
             let root;
             if (type === '$this') root = ctx;
             else if (type === '$event') root = ev;
-            else if (type === '$macro') root = ctx?._macroContext;
+            else if (type === '$macro') root = findContext(ctx, '_macroContext');
+            else if (type === '$query') root = findContext(ctx, '_queryContext');
             else root = findInScope(ctx, name);
 
             if (!root) return (type === 'state') ? `[Unknown: ${name}]` : undefined;
@@ -1255,6 +1295,9 @@
         }
 
         if (typeof onode !== 'object') {
+            if (typeof onode === 'string' && onode.startsWith('=') && onode.length > 1) {
+                return cdomToDOM({ "=": onode }, wasString, unsafe, context);
+            }
             return document.createTextNode(onode);
         }
 
@@ -1305,7 +1348,14 @@
         const el = document.createElement(tag);
         if (context) Object.defineProperty(el, '_lv_parent', { value: context, enumerable: false, configurable: true });
 
-        if (typeof content === 'object' && content !== null && !Array.isArray(content) && !content.nodeType) {
+        // Check if content is a structural reference object itself
+        const isStructural = (obj) => {
+            if (typeof obj !== 'object' || obj === null || Array.isArray(obj) || obj.nodeType) return false;
+            const keys = Object.keys(obj);
+            return keys.length === 1 && (keys[0] === '=' || keys[0] === '$' || keys[0].startsWith('=') || symbolicOperators.has(keys[0]));
+        };
+
+        if (typeof content === 'object' && content !== null && !Array.isArray(content) && !content.nodeType && !isStructural(content)) {
             for (const key in content) {
                 const val = content[key];
                 if (key === 'children') {
@@ -1404,8 +1454,10 @@
             return;
         }
 
-        // Check if it's a CSS selector (doesn't start with http/https or /)
-        if (!srcValue.startsWith('http') && !srcValue.startsWith('/') && !srcValue.startsWith('./') && !srcValue.startsWith('../')) {
+        // Check if it's a CSS selector
+        // We avoid querySelector if it looks like a file path or URL to prevent DOMException
+        const isUrlLike = srcValue.includes('/') || srcValue.includes('?');
+        if (!isUrlLike && !srcValue.startsWith('http')) {
             try {
                 const source = document.querySelector(srcValue);
                 if (source) {
@@ -1434,13 +1486,17 @@
 
             const contentType = response.headers.get('content-type') || '';
             const text = await response.text();
+            const pathname = url.pathname.toLowerCase();
 
             // Determine how to handle content
-            const isCDOM = srcValue.endsWith('.cdom') || contentType.includes('application/cdom');
-            const isHTML = contentType.includes('text/html') || srcValue.endsWith('.html') || srcValue.endsWith('.htm');
+            const isCDOM = pathname.endsWith('.cdom') || contentType.includes('application/cdom') || contentType.includes('application/json');
+            const isHTML = pathname.endsWith('.html') || pathname.endsWith('.htm') || contentType.includes('text/html');
 
             if (isCDOM) {
                 const cdomData = JSON.parse(text);
+                const query = Object.fromEntries(url.searchParams.entries());
+                element._queryContext = query;
+                if (!element._macroContext) element._macroContext = query;
                 const dom = cdomToDOM(cdomData, true, false, element);
                 element.replaceChildren(dom);
             } else if (isHTML) {

package/package.json

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