@daz4126/helium 1.0.0-beta.3 → 1.0.0-beta.5

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/examples/index.html

@@ -220,17 +220,11 @@
 </head>
 <body>
 
-<div class="page" data-helium @data="{ count: 0 }">
+<div class="page" data-helium>
   <h1>Helium Examples</h1>
 
   <div class="examples">
 
-  <!-- @data Test -->
-    <div class="card" data-he="{ word: 'Hello',number: 42 }">
-      <h2 data-he-text="word"></h2>
-      <p>Number: <b @text="number"></b></p>
-    </div>
-
     <!-- Counter -->
     <div class="card">
       <h2>Counter</h2>
@@ -328,7 +322,7 @@
     </div>
 
     <!-- Debounced Input -->
-    <div class="card" @data="{ search: '', debouncedSearch: '' }">
+    <div class="card">
       <h2>Debounced Input</h2>
       <p>Type and wait 500ms to see the debounced value update.</p>
       <input placeholder="Search..." @bind="search" @input.debounce:500="debouncedSearch = search">
@@ -340,13 +334,13 @@
     <div class="card" @data="{ tab: 'one' }">
       <h2>Tabs</h2>
       <div class="tabs">
-        <button class="tab" :class="{ active: tab === 'one' }" @click="tab = 'one'">Tab 1</button>
-        <button class="tab" :class="{ active: tab === 'two' }" @click="tab = 'two'">Tab 2</button>
-        <button class="tab" :class="{ active: tab === 'three' }" @click="tab = 'three'">Tab 3</button>
+        <button class="tab" :class="{ active: tab == 'one' }" @click="tab = 'one'">Tab 1</button>
+        <button class="tab" :class="{ active: tab == 'two' }" @click="tab = 'two'">Tab 2</button>
+        <button class="tab" :class="{ active: tab == 'three' }" @click="tab = 'three'">Tab 3</button>
       </div>
-      <div class="tab-content" @visible="tab === 'one'">Content for Tab 1</div>
-      <div class="tab-content" @visible="tab === 'two'">Content for Tab 2</div>
-      <div class="tab-content" @visible="tab === 'three'">Content for Tab 3</div>
+      <div class="tab-content" @visible="tab == 'one'">Content for Tab 1</div>
+      <div class="tab-content" @visible="tab == 'two'">Content for Tab 2</div>
+      <div class="tab-content" @visible="tab == 'three'">Content for Tab 3</div>
     </div>
 
     <!-- Element References -->
@@ -395,7 +389,7 @@
     </div>
 
     <!-- Character Counter -->
-    <div class="card" @data="{ text: '', maxLength: 100 }">
+    <div class="card" @data="{ maxLength: 100 }">
       <h2>Character Counter</h2>
       <textarea @bind="text" placeholder="Type something..." rows="3"></textarea>
       <span @calculate:remaining="maxLength - text.length"></span>
@@ -405,7 +399,7 @@
     </div>
 
     <!-- Password Strength (uses @import) -->
-    <div class="card" @data="{ password: '' }" @import="password-utils">
+    <div class="card" @import="https://codepen.io/daz4126/pen/xbOzGNO.js">
       <h2>Password Strength</h2>
       <input type="password" @bind="password" placeholder="Enter password">
       <span @calculate:result="checkStrength(password)"></span>
@@ -418,7 +412,7 @@
     </div>
 
     <!-- Init Example -->
-    <div class="card" @data="{ loadTime: '' }">
+    <div class="card">
       <h2>Init Example</h2>
       <p @init="loadTime = new Date().toLocaleTimeString()">
         Page loaded at: <b @text="loadTime"></b>
@@ -427,7 +421,7 @@
     </div>
 
     <!-- Effect Example -->
-    <div class="card" @data="{ clicks: 0, history: [] }">
+    <div class="card" @data="{ history: [] }">
       <h2>Effect (Side Effects)</h2>
       <p>Click the button and watch the history build up.</p>
       <button @click="clicks++">Click Me</button>
@@ -436,21 +430,12 @@
       <p>History: <span @text="history.join(', ') || 'None yet'">None yet</span></p>
     </div>
 
-    <!-- Clipboard Copy -->
-    <div class="card" @data="{ copied: false, textToCopy: 'Hello from Helium!' }">
-      <h2>Copy to Clipboard</h2>
-      <input @bind="textToCopy" placeholder="Text to copy">
-      <button @click="navigator.clipboard.writeText(textToCopy).then(() => { copied = true; setTimeout(() => copied = false, 2000) })">
-        <span @text="copied ? 'Copied!' : 'Copy'"></span>
-      </button>
-    </div>
-
   </div>
 
 <!-- AJAX Examples Section -->
 <div class="page" style="margin-top: 2rem;" @data="{
   templates: {
-    post: data => `<section class='post'><h1>${data && data.title || 'Loading...'}</h1><p>${data && data.body || ''}</p></section>`
+    post: data => `<section class='post'><h1>${data?.title || 'Loading...'}</h1><p>${data?.body || ''}</p></section>`
   }
 }">
   <h1>AJAX Examples</h1>

package/examples/todo.css

@@ -0,0 +1,109 @@
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body {
+  font: 14px 'Helvetica Neue', Helvetica, Arial, sans-serif;
+  background: #f5f5f5;
+  min-height: 100vh;
+}
+.todoapp {
+  max-width: 550px;
+  margin: 40px auto;
+  background: #fff;
+  box-shadow: 0 2px 4px rgba(0,0,0,0.2), 0 25px 50px rgba(0,0,0,0.1);
+}
+.todoapp h1 {
+  font-size: 80px;
+  font-weight: 200;
+  text-align: center;
+  color: #b83f45;
+  padding: 10px 0;
+}
+.new-todo {
+  width: 100%;
+  padding: 16px 16px 16px 20px;
+  font-size: 24px;
+  border: none;
+  border-bottom: 1px solid #ededed;
+  font-family: inherit;
+  outline: none;
+}
+.new-todo::placeholder { color: #d9d9d9; font-style: italic; }
+.toggle-all-container {
+  display: flex;
+  align-items: center;
+  padding: 12px 15px;
+  border-bottom: 1px solid #ededed;
+  color: #777;
+  cursor: pointer;
+}
+.toggle-all-container input { margin-right: 10px; }
+.todo-list { list-style: none; }
+.todo-item {
+  display: flex;
+  align-items: center;
+  padding: 15px;
+  border-bottom: 1px solid #ededed;
+  font-size: 24px;
+}
+.todo-item.completed .todo-text {
+  color: #949494;
+  text-decoration: line-through;
+}
+.toggle {
+  width: 24px;
+  height: 24px;
+  margin-right: 15px;
+  cursor: pointer;
+  flex-shrink: 0;
+  accent-color: #85cda8;
+}
+.todo-text { flex: 1; word-break: break-all; }
+.destroy {
+  display: none;
+  background: none;
+  border: none;
+  color: #cc9a9a;
+  font-size: 28px;
+  cursor: pointer;
+  padding: 0 10px;
+  line-height: 1;
+}
+.destroy:hover { color: #af5b5e; }
+.todo-item:hover .destroy { display: block; }
+.footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 15px;
+  color: #777;
+  font-size: 14px;
+  border-top: 1px solid #e6e6e6;
+}
+.filters { display: flex; gap: 3px; }
+.filters button {
+  background: none;
+  border: 1px solid transparent;
+  padding: 3px 7px;
+  border-radius: 3px;
+  cursor: pointer;
+  font-size: 14px;
+  color: inherit;
+  font-family: inherit;
+}
+.filters button:hover { border-color: #db7676; }
+.filters button.selected { border-color: #ce4646; }
+.clear-completed {
+  background: none;
+  border: none;
+  cursor: pointer;
+  color: inherit;
+  font-size: 14px;
+  font-family: inherit;
+}
+.clear-completed:hover { text-decoration: underline; }
+.info {
+  text-align: center;
+  margin: 30px 0;
+  color: #bbb;
+  font-size: 12px;
+}
+.info a { color: inherit; }

package/examples/todo.html

@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Helium TodoMVC</title>
+  <link rel="stylesheet" href="todo.css">
+</head>
+<body>
+
+<section class="todoapp" data-helium @local-storage="helium-todos" @import="todo"
+  @data="{ todos: [], newTodo: '', filter: 'all', nextId: 1 }">
+
+  <span hidden @calculate:remaining="todos.filter(t => !t.completed).length"></span>
+  <span hidden @calculate:filtered="filter === 'all' ? todos : filter === 'active' ? todos.filter(t => !t.completed) : todos.filter(t => t.completed)"></span>
+
+  <header>
+    <h1>todos</h1>
+    <input class="new-todo" @bind="newTodo" @keydown.enter="addTodo($data)" placeholder="What needs to be done?" autofocus>
+  </header>
+
+  <section @visible="todos.length > 0">
+    <label class="toggle-all-container">
+      <input type="checkbox" @click="toggleAll($data)" :checked="todos.length > 0 && todos.every(t => t.completed)">
+      Mark all as complete
+    </label>
+    <ul class="todo-list" @html="renderTodos(filtered)"></ul>
+  </section>
+
+  <footer class="footer" @visible="todos.length > 0">
+    <span @text="remaining + (remaining === 1 ? ' item' : ' items') + ' left'"></span>
+    <nav class="filters">
+      <button :class="{ selected: filter === 'all' }" @click="filter = 'all'">All</button>
+      <button :class="{ selected: filter === 'active' }" @click="filter = 'active'">Active</button>
+      <button :class="{ selected: filter === 'completed' }" @click="filter = 'completed'">Completed</button>
+    </nav>
+    <button class="clear-completed" @click="clearCompleted($data)" @visible="todos.some(t => t.completed)">Clear completed</button>
+  </footer>
+
+</section>
+
+<p class="info">Built with <a href="https://github.com/daz-codes/helium">Helium</a></p>
+
+<script type="module" src="../helium.js"></script>
+</body>
+</html>

package/examples/todo.js

@@ -0,0 +1,36 @@
+function esc(s) {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+export function renderTodos(list) {
+  return list.map(t => `<li class='todo-item${t.completed ? ' completed' : ''}'>
+    <input type='checkbox' class='toggle'${t.completed ? ' checked' : ''} @click='toggleTodo($data, ${t.id})'>
+    <span class='todo-text'>${esc(t.text)}</span>
+    <button class='destroy' @click='removeTodo($data, ${t.id})'>&#215;</button>
+  </li>`).join('');
+}
+
+export function addTodo($data) {
+  const text = $data.newTodo.trim();
+  if (text) {
+    $data.todos = [...$data.todos, { id: $data.nextId++, text, completed: false }];
+    $data.newTodo = '';
+  }
+}
+
+export function toggleTodo($data, id) {
+  $data.todos = $data.todos.map(t => t.id === id ? { ...t, completed: !t.completed } : t);
+}
+
+export function removeTodo($data, id) {
+  $data.todos = $data.todos.filter(t => t.id !== id);
+}
+
+export function toggleAll($data) {
+  const allDone = $data.todos.every(t => t.completed);
+  $data.todos = $data.todos.map(t => ({ ...t, completed: !allDone }));
+}
+
+export function clearCompleted($data) {
+  $data.todos = $data.todos.filter(t => !t.completed);
+}

package/helium-lite.js

@@ -4,19 +4,47 @@
  * No AJAX, no @import, no SSE, no Turbo
  */
 
-const parseEx = v => { try { return Function(`return(${v})`)() } catch { return v } };
-const tryNum = v => { const t = String(v).trim(), n = +t; return t && !isNaN(n) ? n : v };
-const isValidIdentifier = v => /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(v);
-const RESERVED = new Set(['undefined', 'null', 'true', 'false', 'NaN', 'Infinity', 'this', 'arguments']);
-const KEY_MODS = { shift: "shiftKey", ctrl: "ctrlKey", alt: "altKey", meta: "metaKey" };
-const debounce = (f, d) => { let t; return (...a) => (clearTimeout(t), t = setTimeout(f, d, ...a)) };
+const parseEx = (v) => {
+  try {
+    return Function(`return(${v})`)();
+  } catch {
+    return v;
+  }
+};
+const tryNum = (v) => {
+  const t = String(v).trim(),
+    n = +t;
+  return t && !isNaN(n) ? n : v;
+};
+const isValidIdentifier = (v) => /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(v);
+const RESERVED = new Set([
+  "undefined",
+  "null",
+  "true",
+  "false",
+  "NaN",
+  "Infinity",
+  "this",
+  "arguments",
+]);
+const KEY_MODS = {
+  shift: "shiftKey",
+  ctrl: "ctrlKey",
+  alt: "altKey",
+  meta: "metaKey",
+};
+const debounce = (f, d) => {
+  let t;
+  return (...a) => (clearTimeout(t), (t = setTimeout(f, d, ...a)));
+};
 
 const ATTR_REGEX = /^(@|:|data-he)/;
 
 const match = (name, ...attrs) => {
   const p = name.split(/[.:]/)[0];
-  if (p === ":" || p === "") return false;
-  return attrs.some(a => p === `@${a}` || p === `data-he-${a}`);
+  return p == ":" || p == ""
+    ? false
+    : attrs.some((a) => p === `@${a}` || p === `data-he-${a}`);
 };
 
 let HELIUM = null;
@@ -24,8 +52,13 @@ let HELIUM = null;
 async function helium(initialState = {}) {
   const inits = [];
   const ALL = Symbol("all");
-  const root = document.querySelector('[\\@helium]') || document.querySelector('[data-helium]') || document.body;
-  const storageKey = root.getAttribute('@local-storage') || root.getAttribute('data-he-local-storage');
+  const root =
+    document.querySelector("[\\@helium]") ||
+    document.querySelector("[data-helium]") ||
+    document.body;
+  const storageKey =
+    root.getAttribute("@local-storage") ||
+    root.getAttribute("data-he-local-storage");
 
   if (!HELIUM) {
     HELIUM = {
@@ -36,12 +69,14 @@ async function helium(initialState = {}) {
       processed: new WeakSet(),
       parentKeys: new WeakMap(),
       fnCache: new Map(),
-      proxyCache: new WeakMap()
+      proxyCache: new WeakMap(),
     };
   }
 
-  const $ = s => document.querySelector(s);
-  const html = s => Object.assign(document.createElement("template"), { innerHTML: s.trim() }).content.firstChild;
+  const $ = (s) => document.querySelector(s);
+  const html = (s) =>
+    Object.assign(document.createElement("template"), { innerHTML: s.trim() })
+      .content.firstChild;
 
   const applyingBindings = new Set();
 
@@ -57,9 +92,9 @@ async function helium(initialState = {}) {
 
   const handler = {
     has(t, p) {
-      if (typeof p === 'string' && p.startsWith('$')) return false;
+      if (typeof p === "string" && p.startsWith("$")) return false;
       if (Reflect.has(t, p)) return true;
-      if (typeof globalThis[p] !== 'undefined') return false;
+      if (typeof globalThis[p] !== "undefined") return false;
       return true;
     },
     get(t, p, r) {
@@ -81,21 +116,12 @@ async function helium(initialState = {}) {
       HELIUM.bindings.get(ALL)?.forEach(safeApplyBinding);
       if (storageKey) localStorage.setItem(storageKey, JSON.stringify(state));
       return res;
-    }
+    },
   };
 
   const state = new Proxy({}, handler);
-  if (storageKey) try { Object.assign(state, JSON.parse(localStorage.getItem(storageKey))); } catch {}
   Object.assign(state, initialState);
 
-  const getRefsObject = () => {
-    const refs = {};
-    for (const [name, element] of HELIUM.refs) {
-      refs[name] = element;
-    }
-    return refs;
-  };
-
   const createScope = (el, event = {}) => {
     return {
       $,
@@ -103,7 +129,7 @@ async function helium(initialState = {}) {
       $event: event,
       $el: el,
       $html: html,
-      ...getRefsObject()
+      ...Object.fromEntries(HELIUM.refs),
     };
   };
 
@@ -115,7 +141,7 @@ async function helium(initialState = {}) {
         "$scope",
         withReturn
           ? `with($scope){with($scope.$data){return(${expr.trim()})}}`
-          : `with($scope){with($scope.$data){${expr.trim()}}}`
+          : `with($scope){with($scope.$data){${expr.trim()}}}`,
       );
       const compiled = { execute: (scope) => fn(scope), getIds: null };
       HELIUM.fnCache.set(key, compiled);
@@ -136,18 +162,22 @@ async function helium(initialState = {}) {
     if (prop === "innerHTML") {
       const content = Array.isArray(r) ? r.join`` : r;
       return typeof Idiomorph === "object"
-        ? Idiomorph.morph(el, content, { morphStyle: 'innerHTML' })
-        : el.innerHTML = content;
+        ? Idiomorph.morph(el, content, { morphStyle: "innerHTML" })
+        : (el.innerHTML = content);
     }
     if (prop === "class" && r && typeof r === "object")
       return Object.entries(r).forEach(([k, v]) =>
-        k.split(/\s+/).forEach(c => el.classList.toggle(c, v)));
+        k.split(/\s+/).forEach((c) => el.classList.toggle(c, v)),
+      );
 
     if (prop === "style" && r && typeof r === "object")
-      return el.style.cssText = Object.entries(r)
+      return (el.style.cssText = Object.entries(r)
         .filter(([_, v]) => v != null && v !== false)
-        .map(([k, v]) => `${k.replace(/[A-Z]/g, m => '-' + m.toLowerCase())}:${v}`)
-        .join("; ");
+        .map(
+          ([k, v]) =>
+            `${k.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase())}:${v}`,
+        )
+        .join("; "));
 
     if (prop === "hidden") {
       el.hidden = isHiddenAttr ? !!r : !r;
@@ -156,8 +186,9 @@ async function helium(initialState = {}) {
 
     if (prop in el) {
       if (isRadio && prop !== "checked") el.checked = el.value === r;
-      else if (el.type === "radio" && prop !== "checked") el.checked = el.value === r;
-      else el[prop] = prop === "textContent" ? (r ?? '') : parseEx(r);
+      else if (el.type === "radio" && prop !== "checked")
+        el.checked = el.value === r;
+      else el[prop] = prop === "textContent" ? (r ?? "") : parseEx(r);
       return;
     }
 
@@ -171,12 +202,16 @@ async function helium(initialState = {}) {
         return true;
       },
       get(target, prop) {
-        if (typeof prop == 'string') {
-          excludeChanged ? !accessed.has(prop) && accessed.set(prop, target[prop]) : accessed.add(prop);
+        if (typeof prop == "string") {
+          excludeChanged
+            ? !accessed.has(prop) && accessed.set(prop, target[prop])
+            : accessed.add(prop);
         }
         const val = target[prop];
-        return typeof val == "object" && val != null ? new Proxy(val, this) : val;
-      }
+        return typeof val == "object" && val != null
+          ? new Proxy(val, this)
+          : val;
+      },
     });
 
     try {
@@ -186,21 +221,29 @@ async function helium(initialState = {}) {
         $event: {},
         $el: el,
         $html: html,
-        ...getRefsObject()
+        ...Object.fromEntries(HELIUM.refs),
       };
       compiled.execute(scope);
     } catch {}
 
-    return excludeChanged ? [...accessed.keys()].filter(prop => state[prop] === accessed.get(prop)) : [...accessed];
+    return excludeChanged
+      ? [...accessed.keys()].filter(
+          (prop) => state[prop] === accessed.get(prop),
+        )
+      : [...accessed];
   };
 
   const getDependencies = (compiled, el, excludeChanged = false) => {
     return trackDependenciesProxy(compiled, el, excludeChanged);
   };
 
-  const cleanup = el => {
-    [el, ...el.querySelectorAll('*')].forEach(e => {
-      HELIUM.listeners.get(e)?.forEach(({ receiver, event, handler }) => receiver.removeEventListener(event, handler));
+  const cleanup = (el) => {
+    [el, ...el.querySelectorAll("*")].forEach((e) => {
+      HELIUM.listeners
+        .get(e)
+        ?.forEach(({ receiver, event, handler }) =>
+          receiver.removeEventListener(event, handler),
+        );
       HELIUM.listeners.delete(e);
     });
   };
@@ -209,91 +252,154 @@ async function helium(initialState = {}) {
     const newBindings = [];
     const deferredBindings = [];
 
-    const heElements = [element, ...element.querySelectorAll("*")].filter(e => {
-      if (HELIUM.processed.has(e)) return false;
-      for (let i = 0; i < e.attributes.length; i++) {
-        if (ATTR_REGEX.test(e.attributes[i].name)) return true;
-      }
-      return false;
-    });
+    const heElements = [element, ...element.querySelectorAll("*")].filter(
+      (e) => {
+        if (HELIUM.processed.has(e)) return false;
+        for (let i = 0; i < e.attributes.length; i++) {
+          if (ATTR_REGEX.test(e.attributes[i].name)) return true;
+        }
+        return false;
+      },
+    );
 
     const addBinding = (val, b) => {
-      HELIUM.bindings.set(val, b.calc ? [b, ...(HELIUM.bindings.get(val) || [])] : [...(HELIUM.bindings.get(val) || []), b]);
+      HELIUM.bindings.set(
+        val,
+        b.calc
+          ? [b, ...(HELIUM.bindings.get(val) || [])]
+          : [...(HELIUM.bindings.get(val) || []), b],
+      );
       b.calc ? newBindings.unshift(b) : newBindings.push(b);
     };
 
-    heElements.forEach(el => {
+    heElements.forEach((el) => {
       HELIUM.processed.add(el);
 
       const attrs = el.attributes;
       const inputType = el.type?.toLowerCase();
-      const isCheckbox = inputType == "checkbox", isRadio = inputType == "radio", isSelect = el.tagName == "SELECT";
+      const isCheckbox = inputType == "checkbox",
+        isRadio = inputType == "radio",
+        isSelect = el.tagName == "SELECT";
 
       for (let i = 0; i < attrs.length; i++) {
         const { name, value } = attrs[i];
 
-        if (!name.startsWith('@') && !name.startsWith(':') && !name.startsWith('data-he')) continue;
+        if (
+          !name.startsWith("@") &&
+          !name.startsWith(":") &&
+          !name.startsWith("data-he")
+        )
+          continue;
 
         // Initialize state first if needed (skip reserved words, only if not already set)
-        if (match(name, "text", "html", "bind") && isValidIdentifier(value) && !RESERVED.has(value) && state[value] == null) {
-          state[value] = match(name, "bind") ? (el.type == "checkbox" ? el.checked : tryNum(el.value)) : tryNum(el.textContent);
+        if (
+          match(name, "text", "html", "bind") &&
+          isValidIdentifier(value) &&
+          !RESERVED.has(value) &&
+          state[value] == null
+        ) {
+          state[value] = match(name, "bind")
+            ? el.type == "checkbox"
+              ? el.checked
+              : tryNum(el.value)
+            : tryNum(el.textContent);
         }
 
         // Process the attribute
         if (name === "@data" || name === "data-he") {
           Object.assign(state, parseEx(value));
-        }
-        else if (name.startsWith(":") || name.startsWith("data-he-attr:")) {
-          const propName = name.startsWith(":") ? name.slice(1) : name.slice(13);
-          deferredBindings.push({ el, prop: propName, compiled: compile(value, true) });
-        }
-        else if (match(name, "ref")) {
+        } else if (name.startsWith(":") || name.startsWith("data-he-attr:")) {
+          const propName = name.startsWith(":")
+            ? name.slice(1)
+            : name.slice(13);
+          deferredBindings.push({
+            el,
+            prop: propName,
+            compiled: compile(value, true),
+          });
+        } else if (match(name, "ref")) {
           HELIUM.refs.set("$" + value, el);
-        }
-        else if (match(name, "text", "html")) {
-          deferredBindings.push({ el, prop: match(name, "text") ? "textContent" : "innerHTML", compiled: compile(value, true) });
-        }
-        else if (match(name, "bind")) {
-          const event = (isCheckbox || isRadio || isSelect) ? "change" : "input";
+        } else if (match(name, "text", "html")) {
+          deferredBindings.push({
+            el,
+            prop: match(name, "text") ? "textContent" : "innerHTML",
+            compiled: compile(value, true),
+          });
+        } else if (match(name, "bind")) {
+          const event = isCheckbox || isRadio || isSelect ? "change" : "input";
           const prop = isCheckbox ? "checked" : "value";
-          const inputHandler = e => state[value] = isCheckbox ? e.target.checked : e.target.value;
+          const inputHandler = (e) =>
+            (state[value] = isCheckbox ? e.target.checked : e.target.value);
           el.addEventListener(event, inputHandler);
           if (!HELIUM.listeners.has(el)) HELIUM.listeners.set(el, []);
-          HELIUM.listeners.get(el).push({ receiver: el, event, handler: inputHandler });
-          deferredBindings.push({ el, prop, compiled: compile(value, true), isRadio });
+          HELIUM.listeners
+            .get(el)
+            .push({ receiver: el, event, handler: inputHandler });
+          deferredBindings.push({
+            el,
+            prop,
+            compiled: compile(value, true),
+            isRadio,
+          });
           if (isCheckbox) el.checked = !!state[value];
           else if (isRadio) el.checked = el.value == state[value];
           else el.value = state[value] ?? "";
-        }
-        else if (match(name, "hidden", "visible")) {
+        } else if (match(name, "hidden", "visible")) {
           const isHidden = match(name, "hidden");
-          deferredBindings.push({ el, prop: "hidden", compiled: compile(value, true), isHiddenAttr: isHidden });
-        }
-        else if (match(name, "calculate")) {
+          deferredBindings.push({
+            el,
+            prop: "hidden",
+            compiled: compile(value, true),
+            isHiddenAttr: isHidden,
+          });
+        } else if (match(name, "calculate")) {
           const calcName = name.split(":")[1];
           if (!(calcName in state)) state[calcName] = undefined;
-          deferredBindings.push({ el, calc: calcName, prop: null, compiled: compile(value, true) });
-        }
-        else if (match(name, "effect")) {
-          deferredBindings.push({ el, prop: null, compiled: compile(value, true), keys: name.split(":").slice(1) });
-        }
-        else if (match(name, "init")) {
+          deferredBindings.push({
+            el,
+            calc: calcName,
+            prop: null,
+            compiled: compile(value, true),
+          });
+        } else if (match(name, "effect")) {
+          deferredBindings.push({
+            el,
+            prop: null,
+            compiled: compile(value, true),
+            keys: name.split(":").slice(1),
+          });
+        } else if (match(name, "init")) {
           inits.push({ compiled: compile(value, true), el });
-        }
-        else if (name.startsWith("@") || name.startsWith("data-he")) {
+        } else if (name.startsWith("@") || name.startsWith("data-he")) {
           const fullName = name.startsWith("@") ? name.slice(1) : name.slice(8);
           const [event, ...mods] = fullName.split(".");
-          const receiver = mods.includes("outside") || mods.includes("document") ? document : el;
-          const debounceMod = mods.find(m => m.startsWith("debounce"));
-          const debounceDelay = debounceMod ? (t => t && !isNaN(t) ? Number(t) : 300)(debounceMod.split(":")[1]) : 0;
-          const _handler = e => {
+          const receiver =
+            mods.includes("outside") || mods.includes("document")
+              ? document
+              : el;
+          const debounceMod = mods.find((m) => m.startsWith("debounce"));
+          const debounceDelay = debounceMod
+            ? ((t) => (t && !isNaN(t) ? Number(t) : 300))(
+                debounceMod.split(":")[1],
+              )
+            : 0;
+          const _handler = (e) => {
             if (mods.includes("prevent")) e.preventDefault();
             if (mods.includes("stop")) e.stopPropagation();
-            for (const [mod, prop] of Object.entries(KEY_MODS)) if (mods.includes(mod) && !e[prop]) return;
+            for (const [mod, prop] of Object.entries(KEY_MODS))
+              if (mods.includes(mod) && !e[prop]) return;
             if (["keydown", "keyup", "keypress"].includes(event)) {
               const last = mods[mods.length - 1];
-              if (last && !["prevent", "once", "outside", "document", "stop"].includes(last) && !last.startsWith("debounce") && !Object.keys(KEY_MODS).includes(last)) {
-                const keyName = e.key == " " ? "Space" : e.key == "Escape" ? "Esc" : e.key;
+              if (
+                last &&
+                !["prevent", "once", "outside", "document", "stop"].includes(
+                  last,
+                ) &&
+                !last.startsWith("debounce") &&
+                !Object.keys(KEY_MODS).includes(last)
+              ) {
+                const keyName =
+                  e.key == " " ? "Space" : e.key == "Escape" ? "Esc" : e.key;
                 if (keyName.toLowerCase() !== last.toLowerCase()) return;
               }
             }
@@ -302,10 +408,14 @@ async function helium(initialState = {}) {
               const compiled = compile(value, true);
               compiled.execute(scope);
             }
-            if (mods.includes("once")) receiver.removeEventListener(event, handler);
+            if (mods.includes("once"))
+              receiver.removeEventListener(event, handler);
           };
-          const handler = debounceDelay > 0 ? debounce(_handler, debounceDelay) : _handler;
-          const eventOptions = mods.includes("once") ? { once: true } : undefined;
+          const handler =
+            debounceDelay > 0 ? debounce(_handler, debounceDelay) : _handler;
+          const eventOptions = mods.includes("once")
+            ? { once: true }
+            : undefined;
           receiver.addEventListener(event, handler, eventOptions);
           if (!HELIUM.listeners.has(el)) HELIUM.listeners.set(el, []);
           HELIUM.listeners.get(el).push({ receiver, event, handler });
@@ -313,9 +423,11 @@ async function helium(initialState = {}) {
       }
     });
 
-    deferredBindings.forEach(b => {
-      const tracked = b.keys?.includes("*") ? [ALL] : getDependencies(b.compiled, b.el, true).concat(b.keys || []);
-      tracked.forEach(key => addBinding(key, b));
+    deferredBindings.forEach((b) => {
+      const tracked = b.keys?.includes("*")
+        ? [ALL]
+        : getDependencies(b.compiled, b.el, true).concat(b.keys || []);
+      tracked.forEach((key) => addBinding(key, b));
       if (tracked.length === 0) {
         newBindings.push(b);
       }
@@ -339,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);
@@ -355,13 +471,13 @@ function heliumTeardown() {
 }
 
 // Browser globals
-if (typeof window !== 'undefined') {
+if (typeof window !== "undefined") {
   window.helium = helium;
   window.heliumTeardown = heliumTeardown;
 }
 
 // Auto-initialize
-if (typeof document !== 'undefined') {
+if (typeof document !== "undefined") {
   document.addEventListener("DOMContentLoaded", () => helium());
 }
 

package/helium.js

@@ -238,21 +238,9 @@ 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);
 
-    // Build refs object for scope
-    const getRefsObject = () => {
-      const refs = {};
-      for (const [name, element] of HELIUM.refs) {
-        refs[name] = element;
-      }
-      return refs;
-    };
-
     // Create scope for expression execution
     const createScope = (el, event = {}) => {
       return engine.createScope({
@@ -266,7 +254,7 @@ export function createHelium(options = {}) {
         put,
         patch,
         del,
-        refs: getRefsObject()
+        refs: Object.fromEntries(HELIUM.refs)
       });
     };
 
@@ -349,7 +337,7 @@ export function createHelium(options = {}) {
         put,
         patch,
         del,
-        refs: getRefsObject()
+        refs: Object.fromEntries(HELIUM.refs)
       });
       compiled.execute(scope);
     } catch {}
@@ -404,9 +392,7 @@ export function createHelium(options = {}) {
               const hasExtension = moduleName.endsWith(".js");
               const hasPathPrefix = moduleName.startsWith("/") || moduleName.startsWith("./") || moduleName.startsWith("../");
               const relativePath = (isUrl || hasPathPrefix ? "" : "./") + moduleName + (isUrl || hasExtension ? "" : ".js");
-              // Ensure base URL ends with / so relative paths resolve correctly
-              const baseUrl = location.href.endsWith('/') || location.href.includes('.html') ? location.href : location.href + '/';
-              const path = isUrl ? relativePath : new URL(relativePath, baseUrl).href;
+              const path = isUrl ? moduleName : new URL(relativePath, location.href).href;
               importPromises.push(
                 import(path)
                   .then((module) => {
@@ -580,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.3",
+  "version": "1.0.0-beta.5",
   "main": "helium.js",
   "type": "module",
   "exports": {