lightview 2.4.4 → 2.5.0

package/AI-GUIDANCE.md

@@ -151,8 +151,25 @@ Lightview X allows embedded `${}` expressions in attributes for simple reactivit
 
 **cDOM (Computed DOM)** and **JPRX (JSON Reactive Expressions)** allow you to build fully reactive UIs using **only JSON**.
 
-### JPRX Helper Reference
-JPRX supports a wide range of helpers. AI agents should use these instead of trying to write JS when builing streaming UIs at runtime.
+### Expression Syntax
+*   **`=(expr)` (JPRX)**: Wraps reactive expressions that navigate **reactive state** (Signals/States). Use `=(/path)` for paths, `=(function(...))` for helpers.
+*   **`#(xpath)` (cDOM XPath)**: Wraps XPath expressions that navigate the **DOM tree** during construction. Use `#(../../@id)` to navigate ancestors and access attributes.
+
+**Note**: For initialization functions like `state()` and `signal()`, use `=function(...)` without the outer wrapper, as they execute once on mount rather than being reactive expressions.
+
+### Name Resolution & Scoping
+JPRX uses an **up-tree search** to find signals or states:
+1.  **Search starts** at the element where the expression is defined.
+2.  **Bubbles up** through parent elements looking for a registered name.
+3.  **Falls back** to the global registry.
+
+**The `$this` Placeholder**:
+Use `{ scope: $this }` in `=state` or `=signal` to register data specifically at the current element's level. This is essential for creating multiple independent instances of a component.
+
+### The `...` (Explosion) Operator
+*   **Infix Mapping (`/path...property`)**: Extracts `property` from every object in the `/path` array. **Inside a function call, it automatically explodes** the results into separate arguments.
+*   **Trailing Spread (`/path...`)**: Spreads a direct array reference into individual arguments.
+*   **Warning**: Never write `/path...property...`. The trailing dots will be incorrectly included in the property name lookup.
 
 | Category | Helpers |
 | :--- | :--- |
@@ -163,7 +180,7 @@ JPRX supports a wide range of helpers. AI agents should use these instead of try
 | **Stats** | `sum`, `avg`, `min`, `max`, `median`, `stdev`, `variance` |
 | **Data** | `lookup(val, searchArr, resultArr)` (VLOOKUP-style) |
 | **State** | `state(val, opts)`, `set(path, val)`, `bind(path)`, `increment`, `decrement`, `toggle` |
-| **DOM** | `xpath(expr)` (Backward-looking only), `move(target, loc)` |
+| **DOM** | `#(path)` (XPath Navigation), `move(target, loc)` |
 | **Net** | `fetchHelper(url, opts)`, `mount(url, opts)` |
 
 ### The "Decentralized Layout" Pattern (AI Strategy)
@@ -177,7 +194,7 @@ JPRX supports a wide range of helpers. AI agents should use these instead of try
   div: {
     id: "widget-1",
     onmount: ["=state({val:0}, {name:'w1', scope:$this})", "=move('#sidebar')"],
-    children: [ { p: "Val: =/w1/val" } ]
+    children: [ { p: ["Val: ", =(/w1/val)] } ]
   }
 }
 ```
@@ -247,13 +264,13 @@ router.use(
 <a name="deep-links"></a>
 ## 8. Deep Links & Resources
 
-*   **Documentation Home**: [/docs/index.html](file:///c:/Users/Owner/AntigravityProjects/lightview/docs/index.html)
-*   **Core Logic**: [/lightview.js](file:///c:/Users/Owner/AntigravityProjects/lightview/lightview.js)
-*   **Extension (Hypermedia)**: [/lightview-x.js](file:///c:/Users/Owner/AntigravityProjects/lightview/lightview-x.js)
-*   **Router**: [/lightview-router.js](file:///c:/Users/Owner/AntigravityProjects/lightview/lightview-router.js)
-*   **CDOM/JPRX Parser**: [/lightview-cdom.js](file:///c:/Users/Owner/AntigravityProjects/lightview/lightview-cdom.js)
-*   **Component Index**: [/components/index.js](file:///c:/Users/Owner/AntigravityProjects/lightview/components/index.js)
-*   **JPRX Helpers**: [/jprx/helpers/](file:///c:/Users/Owner/AntigravityProjects/lightview/jprx/helpers/)
+*   **Documentation Home**: [docs/index.html](docs/index.html)
+*   **Core Logic**: [lightview.js](lightview.js) and [docs/api/index.html](docs/api/index.html)
+*   **Extension (Hypermedia)**: [lightview-x.js](lightview-x.js) and [docs/api/hypermedia.html](docs/api/hypermedia.html)
+*   **Router**: [lightview-router.js](lightview-router.js) and [docs/router.html](docs/router.html)
+*   **CDOM/JPRX Parser**: [lightview-cdom.js](lightview-cdom.js) and [docs/cdom.html](docs/cdom.html)
+*   **Component Index**: [components/index.js](components/index.js) and [docs/components/index.html](docs/components/index.html)
+*   **JPRX Helpers**: [jprx/helpers/](jprx/helpers/) and [docs/cdom#helpers](docs/cdom.html#helpers)
 
 ---
 © 2026 AnyWhichWay LLC.

package/README.md

@@ -43,17 +43,17 @@ Traditional UI development requires AI agents to generate imperative JavaScript
 
 ```json
 {
-  "state": { "count": 0 },
   "div": {
+    "onmount": "=state({ count: 0 }, 'counter')",
     "children": [
-      { "p": "{$count}" },
-      { "button": { "onclick": "{set('count', add(count, 1))}", "children": ["Increment"] } }
+      { "p": ["Count: ", "=(/counter/count)"] },
+      { "button": { "onclick": "=(++/counter/count)", "children": ["Increment"] } }
     ]
   }
 }
 ```
 
-This JSON is **the entire application**. The `{...}` expressions are JPRX—a sandboxed, spreadsheet-like formula language (inspired by **XPath** and **JSON Pointers**) that resolves paths, calls registered helpers, and triggers reactivity automatically.
+This JSON is **the entire application**. The `=()` expressions are JPRX—a sandboxed, spreadsheet-like formula language (inspired by **XPath** and **JSON Pointers**) that resolves paths, calls registered helpers, and triggers reactivity automatically.
 
 ### Learn More
 

package/docs/assets/styles/site.css

@@ -498,7 +498,11 @@ img {
 
 /* ============= Hero Section ============= */
 .hero {
-    padding: 5rem 1.5rem;
+    max-height: calc(75vh - var(--site-nav-height));
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 1rem 1.5rem;
     text-align: center;
     background: linear-gradient(135deg, var(--site-bg) 0%, var(--site-bg-alt) 100%);
     position: relative;
@@ -526,7 +530,7 @@ img {
 .hero-logo {
     width: 100px;
     height: 100px;
-    margin-bottom: 1.5rem;
+    margin-bottom: 0.25rem;
 }
 
 
@@ -534,7 +538,7 @@ img {
 .hero h1 {
     font-size: 3.5rem;
     font-weight: 800;
-    margin: 0 0 0.5rem;
+    margin: 0 0 0.25rem;
     background: linear-gradient(135deg, var(--site-primary) 0%, var(--site-accent) 100%);
     -webkit-background-clip: text;
     -webkit-text-fill-color: transparent;
@@ -544,14 +548,14 @@ img {
 .hero-tagline {
     font-size: 1.5rem;
     color: var(--site-text-secondary);
-    margin: 0 0 1rem;
+    margin: 0 0 0.5rem;
     font-weight: 500;
 }
 
 .hero-description {
     font-size: 1.125rem;
     color: var(--site-text-secondary);
-    margin: 0 0 2rem;
+    margin: 0 0 1.25rem;
     max-width: 600px;
     margin-left: auto;
     margin-right: auto;
@@ -568,8 +572,8 @@ img {
     display: flex;
     gap: 3rem;
     justify-content: center;
-    margin-top: 3rem;
-    padding-top: 2rem;
+    margin-top: 1.5rem;
+    padding-top: 1rem;
     border-top: 1px solid var(--site-border);
 }
 
@@ -644,6 +648,9 @@ img {
 }
 
 .feature-card {
+    display: block;
+    color: inherit;
+    text-decoration: none;
     background: var(--site-surface);
     border: 1px solid var(--site-border);
     border-radius: var(--site-radius-lg);
@@ -673,6 +680,7 @@ img {
     font-size: 1.125rem;
     font-weight: 600;
     margin: 0 0 0.5rem;
+    color: var(--site-primary);
 }
 
 .feature-description {
@@ -681,6 +689,7 @@ img {
     font-size: 0.9375rem;
 }
 
+
 /* ============= Code Blocks ============= */
 pre,
 code {

package/docs/benchmarks/bau-tagged-fragment.js

@@ -0,0 +1,41 @@
+(async function () {
+    // In ES modules, document.currentScript is null, so we use import.meta.url
+    const urlParams = new URLSearchParams(import.meta.url.split('?')[1]);
+    const count = parseInt(urlParams.get('count')) || 1000;
+
+    // Settle inside the script context
+    if (window.gc) window.gc();
+    await new Promise(r => setTimeout(r, 100));
+
+    const start = performance.now();
+
+    // Import Bau from CDN
+    const { default: Bau } = await import('https://cdn.jsdelivr.net/npm/@grucloud/bau@0.106.0/+esm');
+    const bau = Bau();
+    const { section, header, h2, h3, div, article, p, span, footer } = bau.tags;
+
+    const items = [];
+    for (let i = 0; i < count; i++) {
+        items.push(article({ class: 'item-card' },
+            header(h3({ class: 'item-title' }, `Item ${i}`)),
+            div({ class: 'item-content' }, p({ class: 'item-description' }, `Detailed description for item ${i} in the benchmark list.`)),
+            footer({ class: 'item-footer' }, span(`Metadata for item ${i}`))
+        ));
+    }
+    const fragment = section({ class: 'benchmark-container' },
+        header(h2('Benchmark Results')),
+        div({ class: 'items-grid' }, ...items)
+    );
+    const target = document.getElementById('benchmark-target');
+    target.replaceChildren(fragment);
+
+    const end = performance.now();
+
+    // Store timing in a global for the driver to pick up
+    window.__bauTaggedBenchmarkTime = end - start;
+
+    // Signal completion
+    if (window.__resolveBauTaggedBenchmark) {
+        window.__resolveBauTaggedBenchmark();
+    }
+})();

package/docs/cdom-xpath.html

@@ -69,9 +69,9 @@ const cdom = `{
             { h3: "User Profile" },
             { button: { 
                 id: "7", 
-                // XPath #@id gets "7" from this button's id
-                // XPath #../@id gets "profile-container" from the parent div
-                children: ["Button ", #@id, " in section ", #../@id] 
+                // XPath #(@id) gets "7" from this button's id
+                // XPath #(../@id) gets "profile-container" from the parent div
+                children: ["Button ", #(@id), " in section ", #(../@id)] 
             }}
         ]
     }
@@ -116,17 +116,35 @@ $('#example').content(hydrate(parseJPRX(cdom)));</code></pre>
             <strong>Forbidden:</strong> <code>child::</code>, <code>descendant::</code>, and <code>following::</code>
             axes are disabled as they could create infinite loops or reference nodes that do not exist yet.
         </p>
+        <div
+            style="margin-top: 1rem; padding: 1rem; background: var(--site-bg-secondary); border-left: 4px solid var(--site-primary); border-radius: var(--site-radius);">
+            <p style="margin: 0; font-size: 0.95rem;">
+                <strong>💡 Need Forward-Looking XPath?</strong> For advanced use cases requiring <code>child::</code>,
+                <code>descendant::</code>, or <code>following::</code> axes, use the reactive <code>=xpath()</code>
+                helper
+                in JPRX instead of static <code>#()</code> in cDOM. The reactive helper evaluates XPath expressions
+                after the DOM is fully constructed and can access any part of the tree. See the
+                <a href="#reactive-xpath">Reactive XPath section</a> below for details.
+            </p>
+        </div>
 
         <h2 id="reactive-xpath">Reactive XPath (<code>=xpath()</code>)</h2>
         <p>
-            If you need an XPath expression to update reactively if attributes elsewhere in the DOM change,
-            use the <code>=xpath()</code> helper within a JPRX expression.
+            If you need an XPath expression to update reactively when attributes elsewhere in the DOM change,
+            or if you need to use <strong>forward-looking axes</strong> (like <code>child::</code>,
+            <code>descendant::</code>,
+            or <code>following::</code>), use the <code>=xpath()</code> helper within a JPRX expression.
+        </p>
+        <p>
+            Unlike static <code>#()</code> expressions which are evaluated once during construction,
+            <code>=xpath()</code> creates a reactive computed signal that re-evaluates whenever its dependencies change,
+            and it has <strong>no axis restrictions</strong> since the DOM is already fully constructed.
         </p>
         <div class="code-block">
             <pre><code>{
     div: {
-        title: "=xpath('../@data-section')",
-        class: "=concat('item ', xpath('../@theme'))"
+        title: "=(xpath('../@data-section'))",
+        class: "=(concat('item ', xpath('../@theme')))"
     }
 }</code></pre>
         </div>
@@ -142,12 +160,12 @@ $('#example').content(hydrate(parseJPRX(cdom)));</code></pre>
 { 
     button: { 
         id: "7", 
-        children: [#../@id] 
+        children: [#(../@id)] 
     } 
 }
 
 // Support for complex paths with predicates
-{ span: [#ancestor::div[@data-role='container']/@title] }</code></pre>
+{ span: [#(ancestor::div[@data-role='container']/@title)] }</code></pre>
         </div>
 
         <h2 id="safety">Security & Safety</h2>