@daz4126/helium 1.0.0-beta.4 → 1.0.0-rc.1

package/.claude/settings.local.json

@@ -11,7 +11,8 @@
       "Bash(npm install)",
       "Bash(npm link helium)",
       "Bash(ls:*)",
-      "Bash(wc:*)"
+      "Bash(wc:*)",
+      "WebFetch(domain:codepen.io)"
     ]
   }
 }

package/README.md

@@ -12,7 +12,7 @@ Here's a simple example of a button that counts the number of times it has been
 
 It's really simple to use - just sprinkle the magic @attributes into your HTML and watch it come alive!
 
-[See more examples here](https://codepen.io/daz4126/pen/ogxGMX)
+[See more examples here](https://codepen.io/daz4126/pen/ogxGMX) | [TodoMVC Example](https://codepen.io/daz4126/pen/gbMjdZO)
 
 ## Why Helium?
 
@@ -20,8 +20,68 @@ Helium is designed for developers who want:
 
 - **Lightweight** - Just over 3KB minified and gzipped
 - **Powerful** - Declarative JavaScript in your HTML
-- **Zero build step** Works directly in the browser with no compiling
-- **Easy to learn** If you know HTML and basic JavaScript, you're ready
+- **Zero build step** - Works directly in the browser with no compiling
+- **Easy to learn** - If you know HTML and basic JavaScript, you're ready
+
+## Versions
+
+Helium comes in three versions so you can pick the right balance of features and size for your project:
+
+### Helium (Standard)
+
+The full-featured version with everything included.
+
+- All directives (`@text`, `@html`, `@bind`, `@data`, `@ref`, `@calculate`, `@effect`, `@init`, etc.)
+- Event handlers with modifiers
+- HTTP requests (`@get`, `@post`, `@put`, `@patch`, `@delete`)
+- Module imports (`@import`)
+- Server-Sent Events (SSE)
+- Turbo/Hotwire integration
+
+**Best for:** Most projects where you want the full power of Helium without worrying about CSP restrictions.
+
+```javascript
+import helium from "@daz4126/helium"
+```
+
+### Helium Lite
+
+A slimmed-down version with just the core reactivity features.
+
+- Core directives (`@text`, `@html`, `@bind`, `@data`, `@ref`, `@calculate`, `@effect`, `@init`)
+- Event handlers with modifiers
+- No HTTP requests, imports, SSE, or Turbo integration
+
+**Best for:** Simple interactive pages where you only need reactivity and don't need server communication or module imports.
+
+```javascript
+import helium from "@daz4126/helium/lite"
+```
+
+### Helium CSP
+
+A Content Security Policy safe version that doesn't require `unsafe-eval`. It uses [jexpr](https://github.com/nicolo-ribaudo/jexpr) as its expression engine instead of `new Function()`, while keeping the full feature set.
+
+- All the same features as the standard version
+- CSP-compliant — no `unsafe-eval` needed
+
+**Best for:** Projects with strict Content Security Policies that prohibit `unsafe-eval`.
+
+```javascript
+import helium from "@daz4126/helium/csp"
+```
+
+### Comparison
+
+| Feature | Standard | Lite | CSP |
+|---------|----------|------|-----|
+| Core directives | ✅ | ✅ | ✅ |
+| Event handlers | ✅ | ✅ | ✅ |
+| HTTP requests | ✅ | ❌ | ✅ |
+| `@import` | ✅ | ❌ | ✅ |
+| SSE | ✅ | ❌ | ✅ |
+| Turbo integration | ✅ | ❌ | ✅ |
+| CSP safe | ❌ | ❌ | ✅ |
 
 ## Installation
 
@@ -30,9 +90,20 @@ Helium is designed for developers who want:
 Just import from the CDN in a script tag directly in your HTML page:
 
 ```html
+<!-- Standard -->
 <script type="module">
   import helium from 'https://cdn.jsdelivr.net/gh/daz-codes/helium/helium.js';
 </script>
+
+<!-- Lite -->
+<script type="module">
+  import helium from 'https://cdn.jsdelivr.net/gh/daz-codes/helium/helium-lite.js';
+</script>
+
+<!-- CSP -->
+<script type="module">
+  import helium from 'https://cdn.jsdelivr.net/gh/daz-codes/helium/helium-csp.js';
+</script>
 ```
 
 ### NPM
@@ -41,10 +112,12 @@ Just import from the CDN in a script tag directly in your HTML page:
 npm install @daz4126/helium
 ```
 
-Then include it in your JavaScript file and call the helium() function:
+Then import the version you need:
 
 ```javascript
-import helium from "@daz4126/helium"
+import helium from "@daz4126/helium"       // Standard
+import helium from "@daz4126/helium/lite"   // Lite
+import helium from "@daz4126/helium/csp"    // CSP
 ```
 
 ### Automatic Initialization

package/helium-lite.js

@@ -120,10 +120,6 @@ async function helium(initialState = {}) {
   };
 
   const state = new Proxy({}, handler);
-  if (storageKey)
-    try {
-      Object.assign(state, JSON.parse(localStorage.getItem(storageKey)));
-    } catch {}
   Object.assign(state, initialState);
 
   const createScope = (el, event = {}) => {
@@ -455,7 +451,11 @@ async function helium(initialState = {}) {
   });
   HELIUM.observer.observe(root, { childList: true, subtree: true });
 
+  // Read localStorage before processElements (which sets @data defaults and triggers saves via proxy)
+  const savedState = storageKey ? (() => { try { return JSON.parse(localStorage.getItem(storageKey)); } catch { return null; } })() : null;
   const initialBindings = await processElements(root);
+  // Merge saved values after @data defaults, so localStorage takes priority
+  if (savedState) Object.assign(state, savedState);
   initialBindings.forEach(applyBinding);
   inits.forEach(({ compiled, el }) => {
     const scope = createScope(el);

package/helium.js

@@ -238,9 +238,6 @@ export function createHelium(options = {}) {
     // Initialize state if it doesn't exist
     const state = new Proxy({}, handler);
 
-    // Load from localStorage if key exists
-    if (storageKey) try { Object.assign(state, JSON.parse(localStorage.getItem(storageKey))); } catch {}
-
     // Merge initial state
     Object.assign(state, initialState);
 
@@ -569,7 +566,11 @@ export function createHelium(options = {}) {
     });
     HELIUM.observer.observe(root, { childList: true, subtree: true });
 
+    // Read localStorage before processElements (which sets @data defaults and triggers saves via proxy)
+    const savedState = storageKey ? (() => { try { return JSON.parse(localStorage.getItem(storageKey)); } catch { return null; } })() : null;
     const initialBindings = await processElements(root);
+    // Merge saved values after @data defaults, so localStorage takes priority
+    if (savedState) Object.assign(state, savedState);
     initialBindings.forEach(applyBinding);
     inits.forEach(({ compiled, el }) => {
       const scope = createScope(el);

package/helium.test.js

@@ -788,4 +788,83 @@ describe('@calculate', () => {
     await new Promise(r => setTimeout(r, 10));
     expect(container.querySelector('#result').textContent).toBe('Strong');
   });
+
+  describe('@local-storage', () => {
+    afterEach(() => {
+      localStorage.clear();
+    });
+
+    it('should not overwrite localStorage values with @data defaults', async () => {
+      // Simulate saved state from a previous session
+      localStorage.setItem('test-todos', JSON.stringify({ todos: ['buy milk', 'walk dog'], filter: 'active', nextId: 3 }));
+
+      container.setAttribute('data-he-local-storage', 'test-todos');
+      container.innerHTML = `
+        <div @data="{ todos: [], filter: 'all', nextId: 1 }">
+          <span id="count" @text="todos.length"></span>
+          <span id="filter" @text="filter"></span>
+          <span id="nextId" @text="nextId"></span>
+        </div>
+      `;
+      await helium();
+      await new Promise(r => setTimeout(r, 10));
+
+      // localStorage values should be preserved, not overwritten by @data defaults
+      expect(container.querySelector('#count').textContent).toBe('2');
+      expect(container.querySelector('#filter').textContent).toBe('active');
+      expect(container.querySelector('#nextId').textContent).toBe('3');
+    });
+
+    it('should set @data values that are not in localStorage', async () => {
+      // Saved state only has some keys
+      localStorage.setItem('test-partial', JSON.stringify({ count: 42 }));
+
+      container.setAttribute('data-he-local-storage', 'test-partial');
+      container.innerHTML = `
+        <div @data="{ count: 0, name: 'default' }">
+          <span id="count" @text="count"></span>
+          <span id="name" @text="name"></span>
+        </div>
+      `;
+      await helium();
+      await new Promise(r => setTimeout(r, 10));
+
+      // count should come from localStorage, name should come from @data
+      expect(container.querySelector('#count').textContent).toBe('42');
+      expect(container.querySelector('#name').textContent).toBe('default');
+    });
+
+    it('should save state changes to localStorage', async () => {
+      container.setAttribute('data-he-local-storage', 'test-save');
+      container.innerHTML = `
+        <div @data="{ count: 0 }">
+          <button @click="count++">Inc</button>
+          <span @text="count"></span>
+        </div>
+      `;
+      await helium();
+
+      container.querySelector('button').click();
+      await new Promise(r => setTimeout(r, 10));
+
+      const saved = JSON.parse(localStorage.getItem('test-save'));
+      expect(saved.count).toBe(1);
+    });
+
+    it('should preserve functions from @data when localStorage is active', async () => {
+      localStorage.setItem('test-funcs', JSON.stringify({ count: 5 }));
+
+      container.setAttribute('data-he-local-storage', 'test-funcs');
+      container.innerHTML = `
+        <div @data="{ count: 0, double(n) { return n * 2 } }">
+          <span id="result" @text="double(count)"></span>
+        </div>
+      `;
+      await helium();
+      await new Promise(r => setTimeout(r, 10));
+
+      // count from localStorage (5), function from @data
+      expect(container.querySelector('#result').textContent).toBe('10');
+    });
+  });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daz4126/helium",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-rc.1",
   "main": "helium.js",
   "type": "module",
   "exports": {