V0.4.0

.gitignore

@@ -181,6 +181,9 @@ out
 /examples/build
 
 package-lib.json
-src/scratch.js
+src/scratch*.js
 src/spike.js
-src/test.js
+src/test*.js
+src/assert.js
+src/runner.js
+.aider*

README.md

@@ -2,9 +2,9 @@
 
 ⚠️ Expect API changes until v1.0.0 ⚠️
 
-Current version: 0.3.23.
+Current version: 0.4.0
 
-Bundle Size: 14kb minified & gzipped.
+Bundle Size: 15kb minified & gzipped.
 
 A simple yet powerful toolkit for interactive islands in web applications. No build step required.
 
@@ -20,7 +20,7 @@ Note that Cami specializes in bringing rich interactivity to your web applicatio
   const { html, ReactiveElement } = cami;
 
   class CounterElement extends ReactiveElement {
-    count = 0
+    count = 0;
 
     template() {
       return html`
@@ -31,21 +31,21 @@ Note that Cami specializes in bringing rich interactivity to your web applicatio
     }
   }
 
-  customElements.define('cami-counter', CounterElement);
+  customElements.define("cami-counter", CounterElement);
 </script>
 ```
 
 [Documentation](https://camijs.com/) | [API Reference](https://camijs.com/api/) | [CDN Link](https://unpkg.com/cami@latest/build/cami.cdn.js) | [Introduction](https://camijs.com/)
 
 ## Learn By Example
 
-* [Counter](https://camijs.com/learn_by_example/counter/)
-* [Interactive Registration Form](https://camijs.com/learn_by_example/form_validation/)
-* [Todo List with Server State Management](https://camijs.com/learn_by_example/todo_list_server/)
-* [Cart with Client & Server State Management](https://camijs.com/learn_by_example/cart/)
-* [Blog with Optimistic UI](https://camijs.com/learn_by_example/blog/)
-* [Nested Key Updates](https://camijs.com/learn_by_example/nested_updates/)
-* [WAI-ARIA Compliant Modal](https://camijs.com/learn_by_example/modal/)
+- [Counter](https://camijs.com/learn_by_example/counter/)
+- [Interactive Registration Form](https://camijs.com/learn_by_example/form_validation/)
+- [Todo List with Server State Management](https://camijs.com/learn_by_example/todo_list_server/)
+- [Cart with Client & Server State Management](https://camijs.com/learn_by_example/cart/)
+- [Blog with Optimistic UI](https://camijs.com/learn_by_example/blog/)
+- [Nested Key Updates](https://camijs.com/learn_by_example/nested_updates/)
+- [WAI-ARIA Compliant Modal](https://camijs.com/learn_by_example/modal/)
 
 ## Key Concepts:
 
@@ -65,34 +65,34 @@ To use it, you'll need to create a custom element and register it with `customEl
 <script src="https://unpkg.com/cami@latest/build/cami.cdn.js"></script>
 <article>
   <h1>Counter</h1>
-  <counter-component
-  ></counter-component>
+  <counter-component></counter-component>
 </article>
 <script type="module">
   const { html, ReactiveElement } = cami;
 
-  class CounterElement extends ReactiveElement {
-    count = 0
-
-    template() {
-      return html`
-        <button @click=${() => this.count--}>-</button>
-        <button @click=${() => this.count++}>+</button>
-        <div>Count: ${this.count}</div>
-      `;
+  customElements.define(
+    "counter-component",
+    class extends ReactiveElement {
+      count = 0;
+
+      template() {
+        return html`
+          <button @click=${() => this.count--}>-</button>
+          <button @click=${() => this.count++}>+</button>
+          <div>Count: ${this.count}</div>
+        `;
+      }
     }
-  }
-
-  customElements.define('counter-component', CounterElement);
+  );
 </script>
 ```
 
 ## Features include:
 
-* **Reactive Web Components**: Simplifies front-end web development with `ReactiveElement`. This is done through [Observable Properties](https://camijs.com/features/observable_property). They are properties of a `ReactiveElement` instance that are automatically observed for changes. When a change occurs, the `ReactiveElement` instance is notified and can react accordingly by re-rendering the component. Observable properties support deep updates, array changes, and reactive attributes, making it easier to manage dynamic content. Lastly, this removes the boilerplate of `signal()`, `setState()`, or `reactive()` that you might find in other libraries.
-* **Async State Management**: Easily manage server data. Our library provides a simple API for fetching and updating data with [`query` and `mutation`](https://camijs.com/features/async_state_management). Use the `query` method to fetch and cache data, with options to control how often it refreshes. The `mutation` method lets you update data and immediately reflect those changes in the UI, providing a smooth experience without waiting for server responses.
-* **Cross-component State Management with  Stores**: Share state across different components with ease using a single store using [`cami.store`](https://camijs.com/features/client_state_management). By default, this uses `localStorage` to persist state across page refreshes. This is useful for storing user preferences, authentication tokens, and other data that needs to be shared across components. This is also useful for storing data that needs to be shared across tabs.
-* **Streams & Functional Reactive Programming (FRP)**: Handle asynchronous events gracefully with [Observable Streams](https://camijs.com/features/streams/). They offer powerful functions like `map`, `filter`, `flatMap`, and `debounce` to process events in a sophisticated yet manageable way, for clean & declarative code.
+- **Reactive Web Components**: Simplifies front-end web development with `ReactiveElement`. This is done through [Observable Properties](https://camijs.com/features/observable_property). They are properties of a `ReactiveElement` instance that are automatically observed for changes. When a change occurs, the `ReactiveElement` instance is notified and can react accordingly by re-rendering the component. Observable properties support deep updates, array changes, and reactive attributes, making it easier to manage dynamic content. Lastly, this removes the boilerplate of `signal()`, `setState()`, or `reactive()` that you might find in other libraries.
+- **Async State Management**: Easily manage server data. Our library provides a simple API for fetching and updating data with [`query` and `mutation`](https://camijs.com/features/async_state_management). Use the `query` method to fetch and cache data, with options to control how often it refreshes. The `mutation` method lets you update data and immediately reflect those changes in the UI, providing a smooth experience without waiting for server responses.
+- **Cross-component State Management with Stores**: Share state across different components with ease using a single store using [`cami.store`](https://camijs.com/features/client_state_management). By default, this uses `localStorage` to persist state across page refreshes. This is useful for storing user preferences, authentication tokens, and other data that needs to be shared across components. This is also useful for storing data that needs to be shared across tabs.
+- **Streams & Functional Reactive Programming (FRP)**: Handle asynchronous events gracefully with [Observable Streams](https://camijs.com/features/streams/). They offer powerful functions like `map`, `filter`, `flatMap`, and `debounce` to process events in a sophisticated yet manageable way, for clean & declarative code.
 
 Please visit our [Documentation](https://camijs.com/), [API Reference](https://camijs.com/api/), [Examples](https://camijs.com/learn_by_example/counter/), or [Core Concepts](https://camijs.com/features/observable_property/) to learn more.
 
@@ -109,7 +109,6 @@ That said, I like the idea of declarative templates, uni-directional data flow,
 - **Lean Teams or Solo Devs**: If you're building a small to medium-sized application, I built Cami with that in mind. You can start with `ReactiveElement`, and once you need to share state between components, you can add our store. It's a great choice for rich data tables, dashboards, calculators, and other interactive islands. If you're working with large applications with large teams, you may want to consider other frameworks.
 - **Developers of Multi-Page Applications**: For folks who have an existing server-rendered application, you can use Cami to add interactivity to your application.
 
-
 ## Examples
 
 To learn Cami by example, see our [examples](https://camijs.com/learn_by_example/counter/).
@@ -135,7 +134,6 @@ JSDoc is used to build the API reference. We use Material for MkDocs for the doc
 
 To make JSDoc be compatible with MkDocs, we use jsdoc2md to generate markdown files from JSDoc comments. We use then use MkDocs to build the documentation site.
 
-
 ### Testing
 
 We use Jasmine for testing. To run the tests, run:

analysis/bugs/20250709-1329_deepEqual_correctness_analysis.md

@@ -0,0 +1,226 @@
+# deepEqual Correctness Analysis
+
+**Date:** 2025-07-09 13:29  
+**File:** src/utils.ts  
+**Function:** _deepEqual  
+**Status:** Currently at 98.2% correctness (56/57 test cases passing)  
+**Goal:** Achieve 100% correctness without performance degradation
+
+## Overview
+
+Analysis of the `_deepEqual` implementation in comparison to Lodash's `isEqual` to identify and fix the remaining correctness issues while maintaining optimal performance.
+
+## Current State
+
+### Implementation Summary
+- **Data Shape**: Function takes `(a: any, b: any, visited?: Set<any>): boolean`
+- **Architecture**: Stack-based circular reference detection using `Set`
+- **Performance**: 92.4% of fast-deep-equal performance on simple objects
+- **Correctness**: 98.2% (56/57 test cases passing)
+
+### Data Flow Analysis
+
+1. **Entry Point**: `_deepEqual(a, b, visited?)`
+2. **Early Exits**: 
+   - `a === b` (reference equality)
+   - `a !== a` (NaN handling)
+   - `null/undefined` checks
+   - Type mismatches for primitives
+3. **Circular Reference Detection**: Initialize/check `visited` Set
+4. **Type-Specific Comparisons**: Arrays, Dates, RegExp, Maps, Sets, TypedArrays
+5. **Object Comparison**: Constructor check, key enumeration, recursive comparison
+
+## Critical Issues Identified
+
+### 1. Circular Reference Handling (Primary Bug)
+
+**Current Implementation:**
+```typescript
+// Check for circular references
+if (visited.has(a) || visited.has(b)) {
+  return true; // Assume equal for circular structures
+}
+```
+
+**Problem**: This assumes ALL circular references are equal, which is incorrect.
+
+**Lodash's Approach** (from provided code):
+```javascript
+// Check that cyclic values are equal.
+var objStacked = stack.get(object);
+var othStacked = stack.get(other);
+if (objStacked && othStacked) {
+  return objStacked == other && othStacked == object;
+}
+```
+
+**Impact**: Causes false positives when comparing different circular structures.
+
+### 2. Map Key Comparison Issue
+
+**Current Implementation:**
+```typescript
+for (const [key, val] of a.entries()) {
+  if (!b.has(key) || !_deepEqual(val, b.get(key), visited)) {
+    // ...
+  }
+}
+```
+
+**Problem**: Map keys are compared with strict equality (`has(key)`) but should use deep equality for object keys.
+
+**Lodash's Approach**: Uses deep comparison for both keys and values in Map structures.
+
+### 3. Set Comparison Inefficiency
+
+**Current Implementation**: O(n²) comparison with redundant `matched` array tracking.
+
+**Lodash's Approach**: More efficient comparison strategies for Sets.
+
+### 4. Constructor Comparison Edge Cases
+
+**Current Implementation:**
+```typescript
+if (a.constructor !== b.constructor) {
+  return false;
+}
+```
+
+**Problem**: Doesn't handle cases where constructor might be undefined or cases with inheritance.
+
+**Lodash's Approach**: More robust constructor handling with additional checks.
+
+## Performance-Neutral Fixes
+
+### 1. Fix Circular Reference Detection
+
+**Current (Incorrect):**
+```typescript
+if (visited.has(a) || visited.has(b)) {
+  return true; // Assume equal for circular structures
+}
+```
+
+**Fix (Performance-Neutral):**
+```typescript
+if (visited.has(a) || visited.has(b)) {
+  // For circular structures, check if they're the same circular reference
+  return visited.has(a) && visited.has(b) && 
+         a === b; // Same reference means same circular structure
+}
+```
+
+### 2. Improve Map Key Comparison
+
+**Current:**
+```typescript
+if (!b.has(key) || !_deepEqual(val, b.get(key), visited)) {
+```
+
+**Fix (Slight Performance Cost but Correct):**
+```typescript
+let found = false;
+for (const [bKey, bVal] of b.entries()) {
+  if (_deepEqual(key, bKey, visited)) {
+    if (!_deepEqual(val, bVal, visited)) {
+      return false;
+    }
+    found = true;
+    break;
+  }
+}
+if (!found) return false;
+```
+
+### 3. Optimize Set Comparison
+
+**Current O(n²) approach can be improved while maintaining correctness:**
+```typescript
+// More efficient Set comparison
+if (a instanceof Set) {
+  if (!(b instanceof Set) || a.size !== b.size) {
+    return false;
+  }
+
+  // Early exit for empty sets
+  if (a.size === 0) return true;
+
+  // For primitive sets, use Set operations
+  if (isPrimitiveSet(a) && isPrimitiveSet(b)) {
+    return [...a].every(val => b.has(val));
+  }
+
+  // For complex sets, use the current approach but optimize
+  // ... existing nested loop logic
+}
+```
+
+## Lodash Comparison Analysis
+
+### Key Differences from Lodash
+
+1. **Stack vs Set**: Lodash uses a Stack data structure for circular reference detection
+2. **Bitmask Flags**: Lodash uses bitmask flags for partial comparison support
+3. **Wrapper Object Handling**: Lodash handles `__wrapped__` objects
+4. **Constructor Validation**: More robust constructor checking
+
+### Performance Tradeoffs
+
+- **Lodash**: 100% correctness, 25.6% performance vs fast-deep-equal
+- **Current**: 98.2% correctness, 92.4% performance vs fast-deep-equal
+- **Target**: 100% correctness, maintain >90% performance
+
+## Recommendations
+
+### High Priority (Correctness Fixes)
+
+1. **Fix Circular Reference Detection**
+   - Implement proper circular reference comparison
+   - Use WeakMap for better performance than Set
+   - Match Lodash's approach for circular structure validation
+
+2. **Fix Map Key Comparison**
+   - Implement deep equality for Map keys
+   - Handle object keys correctly
+
+### Medium Priority (Edge Case Handling)
+
+3. **Improve Constructor Checking**
+   - Handle undefined constructors
+   - Add inheritance checks similar to Lodash
+
+4. **Add Wrapper Object Support**
+   - Handle `__wrapped__` objects if needed for full compatibility
+
+### Low Priority (Performance Optimizations)
+
+5. **Optimize Set Comparison**
+   - Implement primitive set fast path
+   - Reduce O(n²) complexity where possible
+
+## Implementation Strategy
+
+1. **Phase 1**: Fix circular reference detection (highest impact)
+2. **Phase 2**: Fix Map key comparison
+3. **Phase 3**: Optimize Set comparison
+4. **Phase 4**: Add remaining edge case handling
+
+## Test Cases to Focus On
+
+Based on the benchmark results, focus on:
+- Circular reference scenarios
+- Map with object keys
+- Complex Set comparisons
+- Constructor edge cases
+
+## Expected Outcome
+
+With these fixes, the implementation should achieve:
+- **100% correctness** (57/57 test cases passing)
+- **>90% performance** relative to fast-deep-equal
+- **Maintain compatibility** with existing usage patterns
+
+---
+
+*Analysis completed: 2025-07-09 13:29*  
+*Next steps: Implement Phase 1 fixes for circular reference detection*