lightview 2.3.8 → 2.4.7

package/.gemini/CODE_ANALYSIS_AND_IMPROVEMENT_PLAN.md

@@ -0,0 +1,56 @@
+# cDOM / JPRX Code Analysis and Improvement Recommendations
+
+## 1. Executive Summary
+This document outlines the analysis of the current JPRX (JSON Reactive Path eXpressions) and cDOM implementation within Lightview. While the system is powerful and integral to the framework's reactivity, its core logic (`jprx/parser.js`) has grown into a monolithic module that mixes tokenization, parsing, evaluation, and runtime state management. The primary recommendation is to refactor this into distinct layers to improve maintainability, performance, and testability.
+
+## 2. Current State Analysis
+
+### 2.1 Code Structure
+*   **Monolithic Design**: `jprx/parser.js` is approximately 1,900 lines long. It encapsulates:
+    *   **Tokenizer**: Regex-based lexer (`tokenize`).
+    *   **Pratt Parser**: Top-down operator precedence parser.
+    *   **Evaluator**: `evaluateAST` and `resolvePath` logic.
+    *   **Runtime Types**: `BindingTarget`, `LazyValue`.
+    *   **Global Registry**: Storage for helpers and operators.
+*   **Coupling**: The parser is tightly coupled with Lightview's specific reactivity model (Signals/Proxies) via direct imports and assumption of `Lightview.state` structure.
+
+### 2.2 Performance
+*   **Repeated Parsing**: Currently, there is no visible caching mechanism for parsed ASTs. Every time an expression is evaluated (unless manually memoized externally), it goes through the tokenization and parsing steps.
+*   **Object Creation**: The heavy use of intermediate objects during AST traversals and resolution could trigger frequent garbage collection in high-frequency updates.
+
+### 2.3 DX and Reliability
+*   **Error Reporting**: Syntax errors in JPRX expressions often result in generic failures or silent returns, making debugging difficult for the end-user.
+*   **Complexity**: Adding new operators or features requires modifying the central file, increasing the risk of regressions.
+
+## 3. Improvement Recommendations
+
+### Phase 1: Modularization (High Priority)
+Decompose `jprx/parser.js` into focused modules under a `jprx/core/` directory:
+
+1.  **`tokenization.js`**: Pure functions handling string-to-token conversion.
+2.  **`grammar.js`**: Definition of operators, precedence levels, and AST node types.
+3.  **`parser.js`**: The Pratt parser implementation that outputs a pure AST.
+4.  **`runtime.js`**: The `evaluateAST` logic and `BindingTarget`/`LazyValue` classes.
+5.  **`registry.js`**: Singleton or context-based registry for helpers and operators.
+
+### Phase 2: Performance Enhancements
+1.  **LRU Cache for ASTs**: Implement a Least Recently Used cache for the `tokenize -> parse` pipeline. If an expression string `count + 1` is seen again, serve the cached AST immediately.
+2.  **Fast-Path for Simple Paths**: 90% of expressions are likely simple property access (e.g., `user.name`). Implement a proper regex check to bypass the full parser for these cases and use direct traversal.
+3.  **Instruction Caching**: For repeated evaluations of the same AST, consider compiling to a closure (similar to how `new Function` works, but safe and sandboxed) if performance bottlenecks appear.
+
+### Phase 3: Robustness and Validation
+1.  **Fuzz Testing**: Implement grammar-based fuzz testing to ensure the parser does not crash on malformed inputs.
+2.  **Strict Mode**: Introduce a strict mode that throws descriptive errors for undefined paths or invalid operations, rather than silently failing.
+3.  **Type Safety**: If possible, add JSDoc type definitions to all internal AST nodes to aid tooling and potential future TypeScript migration.
+
+## 4. Code Specific Observations
+
+*   **`BindingTarget` Implementation**: The current "duck-typing" (`isBindingTarget = true`) is practical but could be cleaner using `Symbol.for('jprx.bindingTarget')` to avoid property collision.
+*   **Operator Registration**: The dynamic `registerOperator` is powerful but allows overwriting core behavior. Consider locking core operators (math, logic) after initialization.
+*   **Reactivity Integration**: The dependency on `Lightview.state` could be abstracted behind an interface (e.g., `IReactiveSource`), allowing JPRX to be used with other state management libraries if desired.
+
+## 5. Next Steps
+1.  Create the `jprx/core` directory structure.
+2.  Move `BindingTarget` and `LazyValue` to a `types.js` file.
+3.  Extract the `tokenize` function and unit test it in isolation.
+4.  Draft the `AST` cache mechanism.

package/AI-GUIDANCE.md

@@ -0,0 +1,274 @@
+# Lightview AI Guidance
+
+This document is the **definitive guide** for Large Language Models (LLMs) on how to effectively use the Lightview library. It covers all development workflows, particularly emphasizing correct source file usage, hypermedia patterns, and dynamic generation.
+
+## Table of Contents
+1.  [Critical: Source Files vs Modules](#source-files)
+2.  [The Four UI Syntaxes](#the-four-ui-syntaxes)
+3.  [Hypermedia & Lightview X](#hypermedia-lightview-x)
+4.  [JPRX & cDOM (AI-Safe Generation)](#jprx-cdom)
+5.  [Component System](#component-system)
+6.  [Routing & Navigation](#routing-navigation)
+7.  [AI Development Strategies](#ai-development-strategies)
+8.  [Deep Links & Resources](#deep-links)
+
+---
+
+<a name="source-files"></a>
+## 1. Critical: Source Files vs Modules
+
+**PAY CAREFUL ATTENTION TO FILE TYPES.**
+
+*   **Standard Scripts (`.js`)**: These files exist in the root and are suitable for direct browser inclusion via script tags or simple bundling.
+    *   `lightview.js`: The core reactive engine (Signals, State, $, Effect).
+    *   `lightview-x.js`: The "Extension" module (Hypermedia, src fetching, simple validation, vDOM/oDOM conversion).
+    *   `lightview-router.js`: The Router implementation.
+    *   `lightview-cdom.js`: The parser for JPRX and cDOM.
+
+*   **ES Modules (in subdirectories)**: Files in `jprx/`, `components/`, etc., are ES modules.
+    *   **Do not** reference these directly in a generic HTML script tag without `type="module"`.
+    *   **Do** import them in your application logic files (e.g., `import { ... } from './jprx/parser.js'`).
+
+**Guidance**: When helping a user set up a new project, prefer importing from the root standard scripts for simplicity, or set up a proper `build.js` if deep module imports are needed.
+
+**Note on Syntaxes**:
+- **Tagged API**: Supported in `lightview.js`.
+- **vDOM**: Supported in `lightview.js` (standard `{ tag: ... }` objects).
+- **oDOM**: Requires `lightview-x.js` (converts `{ div: ... }` usage).
+
+---
+
+<a name="the-four-ui-syntaxes"></a>
+## 2. The Four UI Syntaxes
+
+Choose the syntax that matches your goal.
+
+### A. Tagged API (Best for Logic)
+Javascript functions representing HTML tags. Best for building applications with complex logic.
+```javascript
+const { div, h1, button } = Lightview.tags;
+const count = signal(0);
+
+const view = div({ class: "p-4" },
+  h1("Counter"),
+  button({ onclick: () => count.value++ }, () => `Count: ${count.value}`)
+);
+```
+
+### B. vDOM (Best for Structured Data)
+Explicit JSON structure. Use this when you need a standard, serializable format.
+```javascript
+const view = {
+  tag: "div",
+  attributes: { class: "p-4" },
+  children: [
+    { tag: "h1", children: ["Counter"] },
+    { tag: "button", attributes: { onclick: () => count.value++ }, children: [() => `Count: ${count.value}`] }
+  ]
+};
+```
+
+### C. oDOM (Best for Compact Templates)
+"Object DOM" uses keys as tags. It is significantly more concise. **Preferred for configuration-based UIs.**
+```javascript
+const view = {
+  div: {
+    class: "p-4",
+    children: [
+      { h1: "Counter" },
+      { button: { onclick: "...", children: ["Increment"] } }
+    ]
+  }
+};
+```
+
+### D. Custom Elements (Best for Hybrid Apps)
+Standard HTML tags powered by Lightview. Use these when enhancing an existing HTML page.
+```html
+<lv-button onclick="alert('clicked')">Click Me</lv-button>
+```
+
+---
+
+<a name="hypermedia-lightview-x"></a>
+## 3. Hypermedia & Lightview X
+
+Lightview X adds powerful **Hypermedia** capabilities to standard HTML elements.
+
+### The `src` and `href` Attributes (Hypermedia)
+*   **`src`**: Fetches content and replaces the element or its content.
+    *   **Support**: `.html`, `.json`, `.vdom`, `.odom`, `.cdom`, `.cdomc`
+    *   **Usage**: `<div src="/components/user-card.vdom"></div>`
+*   **`href`**: Non-standard tags (like `div`) with `href` act as "Links".
+    *   **Behavior**: Clicking them fetches the content at the URL and replaces the element's `src`.
+    *   **Targeting**: Use `target="#dest:beforeend"` to direct the content elsewhere.
+    *   **Usage**: `<div href="/api/next-page" target="#content:beforeend">Load More</div>`
+
+### Advanced Fetches (`data-method` & `data-body`)
+Customize HTTP requests for `src` and `href` actions.
+
+*   **`data-method`**: Specify the HTTP verb (e.g., `POST`, `PUT`, `DELETE`). Defaults to `GET`.
+*   **`data-body`**: The data to send with the request.
+    *   **CSS Selector (Default)**: Grabs the data from the DOM.
+        *   `form`: Serialized as `FormData`.
+        *   `input`/`select`/`textarea`: Sends the current `value`.
+        *   `checkbox`/`radio`: Sends `value` only if checked.
+        *   Other elements: Sends `innerText`.
+    *   **`javascript:expr`**: Evaluates a Javascript expression (has access to `state` and `signal`).
+    *   **`json:{...}`**: Sends a literal JSON string (sets `Content-Type: application/json`).
+    *   **`text:...`**: Sends raw text (sets `Content-Type: text/plain`).
+*   **GET Requests**: If the method is `GET`, the data from `data-body` is automatically converted into **URL Query Parameters**.
+
+**Usage**:
+```html
+<!-- Post a form -->
+<button href="/api/user/save" data-method="POST" data-body="#user-form">Save</button>
+
+<!-- Fetch with query params from an input -->
+<button href="/api/search" data-body="#search-input" target="#results">Search</button>
+```
+
+*   **Template Literals**: Supported in HTML, vDOM, and oDOM strings (e.g., `class="${ val > 10 ? 'red' : 'blue' }"`) via `lightview-x.js`.
+*   **Gating**: 
+    1.  **`Lightview.hooks.validateUrl`**: Intercept/block URLs.
+    2.  **`lv-before`**: Attribute that gates events (e.g., `lv-before="click: throttle(500)"` or custom functions).
+
+### Logic in Attributes (`template literals`)
+Lightview X allows embedded `${}` expressions in attributes for simple reactivity
+```javascript
+{
+  div: {
+    class: "${ count.value > 10 ? 'text-red-500' : 'text-green-500' }",
+    children: ["Status"]
+  }
+}
+```
+
+---
+
+<a name="jprx-cdom"></a>
+## 4. JPRX & cDOM (Safe Dynamic UI Generation For Humans and AIs)
+
+**cDOM (Computed DOM)** and **JPRX (JSON Reactive Expressions)** allow you to build fully reactive UIs using **only JSON**.
+
+### Syntax Prefixes
+*   **`=` (JPRX)**: Navigates **reactive state** (Signals/States). Starts with `=/` for absolute paths.
+*   **`#` (cDOM XPath)**: Navigates the **DOM tree** during construction. Use `#../../@id` to skip the text node parent and reach an ancestor's attribute.
+
+### 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 |
+| :--- | :--- |
+| **Math** | `add`, `subtract`, `multiply`, `divide`, `mod`, `pow`, `abs`, `round`, `ceil`, `floor`, `sqrt`, `negate`, `toPercent` |
+| **Logic** | `and`, `or`, `not`, `if`, `eq`, `neq`, `gt`, `lt`, `gte`, `lte` |
+| **String** | `join`, `concat`, `upper`, `lower`, `trim`, `len`, `split`, `replace`, `capitalize`, `contains` |
+| **Array** | `map`, `filter`, `reduce`, `push`, `pop`, `sort`, `reverse`, `slice`, `find` |
+| **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** | `#path` (XPath Navigation), `move(target, loc)` |
+| **Net** | `fetchHelper(url, opts)`, `mount(url, opts)` |
+
+### The "Decentralized Layout" Pattern (AI Strategy)
+1.  **Define**: Create a self-contained component with state.
+2.  **Move**: Use `=move('#target')` in `onmount` to teleport it.
+3.  **Stream**: Determine the update needed, generate the `.cdomc`, and let it patch itself.
+
+```javascript
+/* .cdomc format */
+{
+  div: {
+    id: "widget-1",
+    onmount: ["=state({val:0}, {name:'w1', scope:$this})", "=move('#sidebar')"],
+    children: [ { p: "Val: =/w1/val" } ]
+  }
+}
+```
+
+---
+
+<a name="component-system"></a>
+## 5. Component System
+
+Built on **DaisyUI** and **Tailwind CSS**.
+
+*   **Import**: `import { Button } from './components/index.js';`
+*   **Init**: `LightviewX.initComponents()` (Shadow DOM).
+*   **Theming**: `Lightview.setTheme('dark')` or `localStorage.setItem('lightview-theme', 'dark')`.
+
+---
+
+<a name="routing-navigation"></a>
+## 6. Routing & Navigation
+
+The `LightviewRouter` uses a pipeline (chain) architecture.
+
+### Advanced: Middleware Chains
+You can chain multiple handlers for a single route. This is powerful for authentication or data pre-loading.
+```javascript
+const checkAuth = async (ctx) => {
+    const user = await getUser();
+    if (!user) {
+        LightviewRouter.navigate('/login');
+        return null; // Stop chain
+    }
+    return { ...ctx, user }; // Pass data to next handler
+};
+
+router.use(
+  '/admin/*', 
+  checkAuth,            // 1. Guard
+  '/views/admin.html'   // 2. Render
+);
+```
+
+### Route Patterns
+*   **Static**: `router.use('/about', 'about.html')`
+*   **Wildcard**: `router.use('/docs/*', handler)` -> matches `/docs/api/v1`
+*   **Parameters**: `router.use('/users/:id', handler)` -> `ctx.params.id`
+*   **Replacement**: `router.use('/blog/:slug', '/content/posts/:slug.html')` -> Maps URL params to file path automatically.
+
+---
+
+<a name="ai-development-strategies"></a>
+## 7. AI Development Strategies
+
+**Scenario A: "I need a full web application."**
+*   **Strategy**: Use **Tagged API** + **lightview-router.js**.
+*   **Output**: Generate `.js` files.
+
+**Scenario B: "I need a dynamic dashboard widget of unknown nature at app development time."**
+*   **Strategy**: Use **cDOM/JPRX**.
+*   **Output**: Stream `.cdomc` chunks.
+
+**Scenario C: "I need a config-driven UI."**
+*   **Strategy**: Use **oDOM**.
+*   **Output**: Generate `.json` config files.
+
+---
+
+<a name="deep-links"></a>
+## 8. Deep Links & Resources
+
+*   **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

@@ -4,6 +4,8 @@ A lightweight reactive UI library with signal-based reactivity and a clean API.
 
 Access the full documentation and interactive examples at [lightview.dev](https://lightview.dev).
 
+LLMs should read [AI-GUIDANCE.md](AI-GUIDANCE.md) for instructions on how to use Lightview.
+
 ## Modular Architecture
 
 **Core Library**: ~7.75KB | **Extended (Hypermedia + Components)**: ~20KB | **Router**: ~3KB
@@ -25,6 +27,39 @@ Lightview supports multiple ways to build UIs, allowing you to pick the style th
 
 All syntaxes share the same underlying reactive engine based on **Signals** and **State**.
 
+## cDOM & JPRX: AI-Assisted Declarative UIs
+
+Lightview includes **cDOM** (Computed DOM) powered by **JPRX** (JSON Pointer Reactive eXpressions)—a fully declarative UI layer that requires **zero custom JavaScript**. Much like **XPath** provides a powerful query language for XML, JPRX provides a reactive, formula-based language for JSON state.
+
+### Why This Matters for AI Collaboration
+
+Traditional UI development requires AI agents to generate imperative JavaScript code, which introduces security risks (XSS, code injection) and unpredictable behavior. cDOM flips this model:
+
+- **Pure Data, No Code**: UIs are defined as JSON structures with reactive expressions—no `eval()`, no `new Function()`, no executable strings.
+- **Safe by Design**: AI agents can generate, modify, and compose UIs without producing potentially harmful code.
+- **Auditable Output**: Every generated UI is a transparent data structure that can be validated, diffed, and sandboxed.
+
+### Example: A Reactive Counter (No JavaScript)
+
+```json
+{
+  "state": { "count": 0 },
+  "div": {
+    "children": [
+      { "p": "{$count}" },
+      { "button": { "onclick": "{set('count', add(count, 1))}", "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.
+
+### Learn More
+
+- [cDOM Documentation](https://lightview.dev/docs/cdom)
+- [JPRX Expression Reference](https://lightview.dev/docs/cdom#jprx)
+
 ## Quick Start
 
 ### 1. Tagged API (Concise & Expressive)