lume-js 0.2.1 → 0.3.0

package/README.md

@@ -1,51 +1,440 @@
-# lume-js
+# Lume.js
 
-Minimal reactive state + DOM binding with **zero runtime** overhead.  
-Inspired by Go-style simplicity.
+**Reactivity that follows web standards.**
 
-## Philosophy
-- ⚡ Zero runtime, direct DOM updates (no VDOM, no diffing).
-- 🔑 Simple `state()` and `bindDom()` — that's it.
-- 🧩 Explicit nesting (`state({ user: state({ name: "Alice" }) })`).
-- ✨ Works anywhere — plain JS, or alongside other frameworks.
+Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required, no framework lock-in.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.2.1-green.svg)](package.json)
+
+## Why Lume.js?
+
+- 🎯 **Standards-Only** - Uses only `data-*` attributes and standard JavaScript
+- 📦 **Tiny** - <2KB gzipped
+- ⚡ **Fast** - Direct DOM updates, no virtual DOM overhead  
+- 🔧 **No Build Step** - Works directly in the browser
+- 🎨 **No Lock-in** - Works with any library (GSAP, jQuery, D3, etc.)
+- ♿ **Accessible** - HTML validators love it, screen readers work perfectly
+- 🧹 **Clean API** - Cleanup functions prevent memory leaks
+
+### vs Other Libraries
+
+| Feature | Lume.js | Alpine.js | Vue | React |
+|---------|---------|-----------|-----|-------|
+| Custom Syntax | ❌ No | ✅ `x-data`, `@click` | ✅ `v-bind`, `v-model` | ✅ JSX |
+| Build Step | ❌ Optional | ❌ Optional | ⚠️ Recommended | ✅ Required |
+| Bundle Size | ~2KB | ~15KB | ~35KB | ~45KB |
+| HTML Validation | ✅ Pass | ⚠️ Warnings | ⚠️ Warnings | ❌ JSX |
+| Cleanup API | ✅ Yes | ⚠️ Limited | ✅ Yes | ✅ Yes |
+
+**Lume.js is essentially "Modern Knockout.js" - standards-only reactivity for 2025.**
+
+---
+
+## Installation
 
-## Install
+### Via npm
 
 ```bash
 npm install lume-js
 ```
 
-## Example
+### Via CDN
+
+```html
+<script type="module">
+  import { state, bindDom } from 'https://cdn.jsdelivr.net/npm/lume-js/src/index.js';
+</script>
+```
+
+---
+
+## Quick Start
+
+**HTML:**
+```html
+<div>
+  <p>Count: <span data-bind="count"></span></p>
+  <input data-bind="name" placeholder="Enter name">
+  <p>Hello, <span data-bind="name"></span>!</p>
+  
+  <button id="increment">+</button>
+</div>
+```
 
-**main.js**
-```js
-import { state, bindDom } from "lume-js";
+**JavaScript:**
+```javascript
+import { state, bindDom } from 'lume-js';
 
+// Create reactive state
 const store = state({
   count: 0,
-  user: state({ name: "Alice" })
+  name: 'World'
 });
 
-bindDom(document.body, store);
+// Bind to DOM
+const cleanup = bindDom(document.body, store);
 
-document.getElementById("inc").addEventListener("click", () => {
+// Update state with standard JavaScript
+document.getElementById('increment').addEventListener('click', () => {
   store.count++;
 });
 
-document.getElementById("changeName").addEventListener("click", () => {
-  store.user.name = store.user.name === "Alice" ? "Bob" : "Alice";
+// Cleanup when done (important!)
+window.addEventListener('beforeunload', () => cleanup());
+```
+
+That's it! No build step, no custom syntax, just HTML and JavaScript.
+
+---
+
+## Core API
+
+### `state(object)`
+
+Creates a reactive state object using Proxy.
+
+```javascript
+const store = state({
+  count: 0,
+  user: state({           // Nested state must be wrapped
+    name: 'Alice',
+    email: 'alice@example.com'
+  })
 });
+
+// Update state
+store.count++;
+store.user.name = 'Bob';
+```
+
+**Features:**
+- ✅ Validates input (must be plain object)
+- ✅ Only triggers updates when value actually changes
+- ✅ Returns cleanup function from `$subscribe`
+
+### `bindDom(root, store)`
+
+Binds reactive state to DOM elements with `data-bind` attributes.
+
+```javascript
+const cleanup = bindDom(document.body, store);
+
+// Later: cleanup all bindings
+cleanup();
+```
+
+**Supports:**
+- ✅ Text content: `<span data-bind="count"></span>`
+- ✅ Input values: `<input data-bind="name">`
+- ✅ Textareas: `<textarea data-bind="bio"></textarea>`
+- ✅ Selects: `<select data-bind="theme"></select>`
+- ✅ Checkboxes: `<input type="checkbox" data-bind="enabled">`
+- ✅ Numbers: `<input type="number" data-bind="age">`
+- ✅ Radio buttons: `<input type="radio" data-bind="choice">`
+- ✅ Nested paths: `<span data-bind="user.name"></span>`
+
+**NEW in v0.3.0:**
+- Returns cleanup function
+- Better error messages with `[Lume.js]` prefix
+- Handles edge cases (empty bindings, invalid paths)
+
+### `$subscribe(key, callback)`
+
+Manually subscribe to state changes. Returns unsubscribe function.
+
+```javascript
+const unsubscribe = store.$subscribe('count', (value) => {
+  console.log('Count changed:', value);
+  
+  // Integrate with other libraries
+  if (value > 10) {
+    showNotification('Count is high!');
+  }
+});
+
+// Cleanup
+unsubscribe();
+```
+
+**NEW in v0.3.0:**
+- Returns unsubscribe function (was missing in v0.2.x)
+- Validates callback is a function
+- Only notifies on actual value changes
+
+---
+
+## Examples
+
+### Basic Counter
+
+```javascript
+const store = state({ count: 0 });
+const cleanup = bindDom(document.body, store);
+
+document.getElementById('inc').addEventListener('click', () => {
+  store.count++;
+});
+
+// Cleanup on unmount
+window.addEventListener('beforeunload', () => cleanup());
 ```
 
-**index.html**
 ```html
 <p>Count: <span data-bind="count"></span></p>
-<p>User Name: <span data-bind="user.name"></span></p>
-
 <button id="inc">Increment</button>
-<button id="changeName">Change Name</button>
 ```
 
-## Status
+### Form Handling with Validation
+
+```javascript
+const form = state({
+  email: '',
+  age: 25,
+  theme: 'light',
+  errors: {}
+});
+
+const cleanup = bindDom(document.querySelector('form'), form);
+
+// Validate on change
+const unsubEmail = form.$subscribe('email', (value) => {
+  const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+  form.errors = {
+    ...form.errors,
+    email: isValid ? '' : 'Invalid email'
+  };
+});
+
+// Cleanup
+window.addEventListener('beforeunload', () => {
+  cleanup();
+  unsubEmail();
+});
+```
+
+```html
+<form>
+  <input type="email" data-bind="email">
+  <span data-bind="errors.email" style="color: red;"></span>
+  
+  <input type="number" data-bind="age">
+  
+  <select data-bind="theme">
+    <option value="light">Light</option>
+    <option value="dark">Dark</option>
+  </select>
+</form>
+```
+
+### Nested State
+
+```javascript
+const store = state({
+  user: state({
+    profile: state({
+      name: 'Alice',
+      bio: 'Developer'
+    }),
+    settings: state({
+      notifications: true
+    })
+  })
+});
+
+const cleanup = bindDom(document.body, store);
+
+// Subscribe to nested changes
+const unsub = store.user.profile.$subscribe('name', (name) => {
+  console.log('Profile name changed:', name);
+});
+
+// Cleanup
+window.addEventListener('beforeunload', () => {
+  cleanup();
+  unsub();
+});
+```
+
+```html
+<input data-bind="user.profile.name">
+<textarea data-bind="user.profile.bio"></textarea>
+<input type="checkbox" data-bind="user.settings.notifications">
+```
+
+### Integration with GSAP
+
+```javascript
+import gsap from 'gsap';
+import { state } from 'lume-js';
+
+const ui = state({ x: 0, y: 0 });
+
+const unsubX = ui.$subscribe('x', (value) => {
+  gsap.to('.box', { x: value, duration: 0.5 });
+});
+
+// Now ui.x = 100 triggers smooth animation
+
+// Cleanup
+window.addEventListener('beforeunload', () => unsubX());
+```
+
+### Cleanup Pattern (Important!)
+
+```javascript
+const store = state({ data: [] });
+const cleanup = bindDom(root, store);
+
+const unsub1 = store.$subscribe('data', handleData);
+const unsub2 = store.$subscribe('status', handleStatus);
+
+// Cleanup when component unmounts
+function destroy() {
+  cleanup();      // Remove DOM bindings
+  unsub1();       // Remove subscription 1
+  unsub2();       // Remove subscription 2
+}
+
+// For SPA frameworks
+onUnmount(destroy);
+
+// For vanilla JS
+window.addEventListener('beforeunload', destroy);
+```
+
+---
+
+## Philosophy
+
+### Standards-Only
+- Uses only `data-*` attributes (HTML5 standard)
+- Uses only standard JavaScript APIs (Proxy, addEventListener)
+- No custom syntax that breaks validators
+- Works with any tool/library
+
+### No Artificial Limitations
+```javascript
+// ✅ Use with jQuery
+$('.modal').fadeIn();
+store.modalOpen = true;
+
+// ✅ Use with GSAP
+gsap.to(el, { x: store.position });
+
+// ✅ Use with any router
+router.on('/home', () => store.route = 'home');
+
+// ✅ Mix with vanilla JS
+document.addEventListener('click', () => store.clicks++);
+```
+
+**Lume.js doesn't hijack your architecture - it enhances it.**
+
+### Progressive Enhancement
+
+```html
+<!-- Works without JavaScript (server-rendered) -->
+<form action="/submit" method="POST">
+  <input name="email" value="alice@example.com">
+  <button type="submit">Save</button>
+</form>
+
+<script type="module">
+  // Enhanced when JS loads
+  import { state, bindDom } from 'lume-js';
+  
+  const form = state({ email: 'alice@example.com' });
+  const cleanup = bindDom(document.querySelector('form'), form);
+  
+  // Prevent default, use AJAX
+  document.querySelector('form').addEventListener('submit', async (e) => {
+    e.preventDefault();
+    await fetch('/submit', {
+      method: 'POST',
+      body: JSON.stringify({ email: form.email })
+    });
+  });
+  
+  window.addEventListener('beforeunload', () => cleanup());
+</script>
+```
+
+---
+
+## Who Should Use Lume.js?
+
+### ✅ Perfect For:
+- WordPress/Shopify theme developers
+- Accessibility-focused teams (government, healthcare, education)
+- Legacy codebases that can't do full rewrites
+- Developers who hate learning framework-specific syntax
+- Progressive enhancement advocates
+- Projects requiring HTML validation
+- Adding reactivity to server-rendered apps
+
+### ⚠️ Consider Alternatives:
+- **Complex SPAs** → Use React, Vue, or Svelte
+- **Need routing/SSR** → Use Next.js, Nuxt, or SvelteKit
+- **Prefer terse syntax** → Use Alpine.js (if custom syntax is okay)
+
+---
+
+## What's New in v0.3.0?
+
+### Breaking Changes
+- ✅ `subscribe` → `$subscribe` (restored from v0.1.0)
+- ✅ `$subscribe` now returns unsubscribe function
+
+### New Features
+- ✅ TypeScript definitions (`index.d.ts`)
+- ✅ `bindDom()` returns cleanup function
+- ✅ Better error handling with `[Lume.js]` prefix
+- ✅ Input validation (only plain objects)
+- ✅ Only triggers on actual value changes
+- ✅ Support for checkboxes, radio buttons, number inputs
+- ✅ Comprehensive example in `/examples/comprehensive/`
+
+### Bug Fixes
+- ✅ Fixed memory leaks (no cleanup in v0.2.x)
+- ✅ Fixed addon examples (used wrong API)
+- ✅ Better path resolution with detailed errors
+
+---
+
+## Browser Support
+
+- Chrome/Edge 49+
+- Firefox 18+
+- Safari 10+
+- No IE11 (Proxy can't be polyfilled)
+
+**Basically: Modern browsers with ES6 Proxy support.**
+
+---
+
+## Contributing
+
+We welcome contributions! Please:
+
+1. **Focus on:** Examples, documentation, bug fixes, performance
+2. **Avoid:** Adding core features without discussion (keep it minimal!)
+3. **Check:** Project specification for philosophy
+
+---
+
+## License
+
+MIT © Sathvik C
+
+---
+
+## Inspiration
+
+Lume.js is inspired by:
+- **Knockout.js** - The original `data-bind` approach
+- **Alpine.js** - Minimal, HTML-first philosophy
+- **Go** - Simplicity and explicit design
+- **The Web Platform** - Standards over abstractions
 
-🚧 Early alpha (`0.1.0`). API may change. Feedback welcome!
+**Built for developers who want reactivity without the framework tax.**

package/package.json

@@ -1,16 +1,53 @@
 {
   "name": "lume-js",
-  "version": "0.2.1",
+  "version": "0.3.0",
+  "description": "Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "echo 'No build step yet, zero-runtime already!'"
+    "build": "echo 'No build step needed - zero-runtime library!'",
+    "preview": "vite preview"
   },
   "files": [
-    "src"
+    "src",
+    "README.md",
+    "LICENSE"
   ],
+  "keywords": [
+    "reactive",
+    "state",
+    "dom",
+    "binding",
+    "standards",
+    "minimal",
+    "no-build",
+    "vanilla-js",
+    "data-bind",
+    "proxy",
+    "knockout",
+    "html-first",
+    "framework-agnostic",
+    "minimal-runtime",
+    "no-vdom",
+    "web-standards",
+    "lightweight"
+  ],
+  "author": "Sathvik C",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sathvikc/lume-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sathvikc/lume-js/issues"
+  },
+  "homepage": "https://github.com/sathvikc/lume-js#readme",
   "devDependencies": {
     "vite": "^7.1.9"
+  },
+  "engines": {
+    "node": ">=20.19.0"
   }
 }

package/src/addons/computed.js

@@ -1,7 +1,21 @@
 /**
  * computed - creates a derived value based on state
+ * 
+ * NOTE: This is a basic implementation. For production use,
+ * consider more robust solutions with automatic dependency tracking.
+ * 
  * @param {Function} fn - function that computes value from state
- * @returns {Object} - { get: () => value, recompute: () => void, subscribe: (cb) => unsubscribe }
+ * @returns {Object} - { value, recompute, subscribe }
+ * 
+ * @example
+ * const store = state({ count: 0 });
+ * const doubled = computed(() => store.count * 2);
+ * 
+ * // Subscribe to changes
+ * doubled.subscribe(val => console.log('Doubled:', val));
+ * 
+ * // Manually trigger recomputation after state changes
+ * store.$subscribe('count', () => doubled.recompute());
  */
 export function computed(fn) {
   let value;
@@ -20,7 +34,7 @@ export function computed(fn) {
   };
 
   return {
-    get: () => {
+    get value() {
       if (dirty) recalc();
       return value;
     },
@@ -32,7 +46,8 @@ export function computed(fn) {
       subscribers.add(cb);
       // Immediately notify subscriber with current value
       if (!dirty) cb(value);
+      else recalc(); // Compute first time
       return () => subscribers.delete(cb); // unsubscribe function
     },
   };
-}
+}

package/src/addons/watch.js

@@ -3,10 +3,11 @@
  * @param {Object} store - reactive store created with state()
  * @param {string} key - key in store to watch
  * @param {Function} callback - called with new value
+ * @returns {Function} unsubscribe function
  */
 export function watch(store, key, callback) {
-  if (!store.subscribe) {
+  if (!store.$subscribe) {
     throw new Error("store must be created with state()");
   }
-  store.subscribe(key, callback);
-}
+  return store.$subscribe(key, callback);
+}

package/src/core/bindDom.js

@@ -1,50 +1,128 @@
+// src/core/bindDom.js
 /**
- * Lume-JS Zero-runtime DOM binding
+ * Lume-JS DOM Binding
  *
  * Binds reactive state to DOM elements using [data-bind].
- * Supports two-way binding for INPUT/TEXTAREA.
+ * Supports two-way binding for INPUT/TEXTAREA/SELECT.
  *
  * Usage:
  *   import { bindDom } from "lume-js";
- *   bindDom(document.body, store);
+ *   const cleanup = bindDom(document.body, store);
+ *   // Later: cleanup();
  *
  * HTML:
  *   <span data-bind="count"></span>
  *   <input data-bind="user.name">
+ *   <select data-bind="theme"></select>
  */
 
 import { resolvePath } from "./utils.js";
 
 /**
- * Zero-runtime DOM binding for a reactive store
+ * DOM binding for reactive state
  * 
- * @param {HTMLElement} root - root element to scan for [data-bind]
- * @param {object} store - reactive state object
+ * @param {HTMLElement} root - Root element to scan for [data-bind]
+ * @param {object} store - Reactive state object
+ * @returns {function} Cleanup function to remove all bindings
  */
 export function bindDom(root, store) {
+  if (!(root instanceof HTMLElement)) {
+    throw new Error('bindDom() requires a valid HTMLElement as root');
+  }
+
+  if (!store || typeof store !== 'object') {
+    throw new Error('bindDom() requires a reactive state object');
+  }
+
   const nodes = root.querySelectorAll("[data-bind]");
+  const unsubscribers = [];
 
   nodes.forEach(el => {
-    const pathArr = el.getAttribute("data-bind").split(".");
+    const bindPath = el.getAttribute("data-bind");
+    
+    if (!bindPath) {
+      console.warn('[Lume.js] Empty data-bind attribute found', el);
+      return;
+    }
+
+    const pathArr = bindPath.split(".");
     const lastKey = pathArr.pop();
 
     let target;
     try {
-      target = resolvePath(store, pathArr); // must be wrapped with state() if nested
+      target = resolvePath(store, pathArr);
     } catch (err) {
-      console.warn(`Skipping binding for ${el}: ${err.message}`);
+      console.warn(`[Lume.js] Invalid binding path "${bindPath}":`, err.message);
       return;
     }
 
-    // Subscribe once
-    target.subscribe(lastKey, val => {
-      if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") el.value = val;
-      else el.textContent = val;
+    if (!target || typeof target.$subscribe !== 'function') {
+      console.warn(`[Lume.js] Target for "${bindPath}" is not a reactive state object`);
+      return;
+    }
+
+    // Subscribe to changes
+    const unsub = target.$subscribe(lastKey, val => {
+      updateElement(el, val);
     });
 
-    // 2-way binding for inputs
-    if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") {
-      el.addEventListener("input", e => target[lastKey] = e.target.value);
+    unsubscribers.push(unsub);
+
+    // Two-way binding for form inputs
+    if (isFormInput(el)) {
+      el.addEventListener("input", e => {
+        target[lastKey] = getInputValue(e.target);
+      });
     }
   });
+
+  // Return cleanup function
+  return () => {
+    unsubscribers.forEach(unsub => unsub());
+  };
+}
+
+/**
+ * Update DOM element with new value
+ * @private
+ */
+function updateElement(el, val) {
+  if (el.tagName === "INPUT") {
+    if (el.type === "checkbox") {
+      el.checked = Boolean(val);
+    } else if (el.type === "radio") {
+      el.checked = el.value === String(val);
+    } else {
+      el.value = val ?? '';
+    }
+  } else if (el.tagName === "TEXTAREA") {
+    el.value = val ?? '';
+  } else if (el.tagName === "SELECT") {
+    el.value = val ?? '';
+  } else {
+    el.textContent = val ?? '';
+  }
 }
+
+/**
+ * Get value from form input
+ * @private
+ */
+function getInputValue(el) {
+  if (el.type === "checkbox") {
+    return el.checked;
+  } else if (el.type === "number" || el.type === "range") {
+    return el.valueAsNumber;
+  }
+  return el.value;
+}
+
+/**
+ * Check if element is a form input
+ * @private
+ */
+function isFormInput(el) {
+  return el.tagName === "INPUT" || 
+         el.tagName === "TEXTAREA" || 
+         el.tagName === "SELECT";
+}

package/src/core/state.js

@@ -1,32 +1,41 @@
+// src/core/state.js
 /**
  * Lume-JS Reactive State Core
  *
- * Provides minimal, zero-runtime reactive state.
+ * Provides minimal reactive state with standard JavaScript.
  * 
  * Features:
  * - Lightweight and Go-style
  * - Explicit nested states
- * - subscribe for listening to key changes
+ * - $subscribe for listening to key changes
+ * - Cleanup with unsubscribe
  *
  * Usage:
  *   import { state } from "lume-js";
  *   const store = state({ count: 0 });
- *   store.subscribe("count", val => console.log(val));
+ *   const unsub = store.$subscribe("count", val => console.log(val));
+ *   unsub(); // cleanup
  */
 
-
 /**
  * Creates a reactive state object.
  * 
  * @param {Object} obj - Initial state object
- * @returns {Proxy} Reactive proxy with subscribe method
+ * @returns {Proxy} Reactive proxy with $subscribe method
  */
 export function state(obj) {
+  // Validate input
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error('state() requires a plain object');
+  }
+
   const listeners = {};
 
   // Notify subscribers of a key
   function notify(key, val) {
-    if (listeners[key]) listeners[key].forEach(fn => fn(val));
+    if (listeners[key]) {
+      listeners[key].forEach(fn => fn(val));
+    }
   }
 
   const proxy = new Proxy(obj, {
@@ -34,8 +43,13 @@ export function state(obj) {
       return target[key];
     },
     set(target, key, value) {
+      const oldValue = target[key];
       target[key] = value;
-      notify(key, value);
+      
+      // Only notify if value actually changed
+      if (oldValue !== value) {
+        notify(key, value);
+      }
       return true;
     }
   });
@@ -43,15 +57,30 @@ export function state(obj) {
   /**
    * Subscribe to changes for a specific key.
    * Calls the callback immediately with the current value.
+   * Returns an unsubscribe function for cleanup.
    * 
-   * @param {string} key 
-   * @param {function} fn 
+   * @param {string} key - Property key to watch
+   * @param {function} fn - Callback function
+   * @returns {function} Unsubscribe function
    */
-  proxy.subscribe = (key, fn) => {
+  proxy.$subscribe = (key, fn) => {
+    if (typeof fn !== 'function') {
+      throw new Error('Subscriber must be a function');
+    }
+
     if (!listeners[key]) listeners[key] = [];
     listeners[key].push(fn);
-    fn(proxy[key]); // initialize
+    
+    // Call immediately with current value
+    fn(proxy[key]);
+
+    // Return unsubscribe function
+    return () => {
+      if (listeners[key]) {
+        listeners[key] = listeners[key].filter(subscriber => subscriber !== fn);
+      }
+    };
   };
 
   return proxy;
-}
+}

package/src/core/utils.js

@@ -1,14 +1,41 @@
+/**
+ * Utility functions for Lume.js
+ */
+
 /**
  * Resolve a nested path in an object.
- * Example: path "user.name" returns obj.user.name
+ * Example: resolvePath(obj, ['user', 'address']) returns obj.user.address
  *
  * @param {object} obj - The root object
  * @param {string[]} pathArr - Array of keys
  * @returns {object} Last object in the path
+ * @throws {Error} If path is invalid or doesn't exist
  */
 export function resolvePath(obj, pathArr) {
-  return pathArr.reduce((acc, key) => {
-    if (!acc) throw new Error(`Invalid path: ${pathArr.join(".")}`);
-    return acc[key];
-  }, obj);
-}
+  // If no path, return the object itself
+  if (!pathArr || pathArr.length === 0) {
+    return obj;
+  }
+
+  let current = obj;
+  
+  for (let i = 0; i < pathArr.length; i++) {
+    const key = pathArr[i];
+    
+    if (current === null || current === undefined) {
+      throw new Error(
+        `Cannot access property "${key}" of ${current} at path: ${pathArr.slice(0, i + 1).join('.')}`
+      );
+    }
+    
+    if (!(key in current)) {
+      throw new Error(
+        `Property "${key}" does not exist at path: ${pathArr.slice(0, i + 1).join('.')}`
+      );
+    }
+    
+    current = current[key];
+  }
+  
+  return current;
+}

package/src/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Lume.js TypeScript Definitions
+ * 
+ * Provides type safety for reactive state management
+ */
+
+/**
+ * Unsubscribe function returned by $subscribe
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * Subscriber callback function
+ */
+export type Subscriber<T> = (value: T) => void;
+
+/**
+ * Reactive state object with $subscribe method
+ */
+export type ReactiveState<T extends object> = T & {
+  /**
+   * Subscribe to changes on a specific property key
+   * @param key - Property key to watch
+   * @param callback - Function called when property changes
+   * @returns Unsubscribe function for cleanup
+   */
+  $subscribe<K extends keyof T>(
+    key: K,
+    callback: Subscriber<T[K]>
+  ): Unsubscribe;
+};
+
+/**
+ * Create a reactive state object
+ * 
+ * @param obj - Plain object to make reactive
+ * @returns Reactive proxy with $subscribe method
+ * @throws {Error} If obj is not a plain object
+ * 
+ * @example
+ * ```typescript
+ * const store = state({
+ *   count: 0,
+ *   user: state({
+ *     name: 'Alice'
+ *   })
+ * });
+ * 
+ * store.count++; // Triggers reactivity
+ * 
+ * const unsub = store.$subscribe('count', (val) => {
+ *   console.log('Count:', val);
+ * });
+ * 
+ * // Cleanup
+ * unsub();
+ * ```
+ */
+export function state<T extends object>(obj: T): ReactiveState<T>;
+
+/**
+ * Bind reactive state to DOM elements
+ * 
+ * @param root - Root element to scan for [data-bind] attributes
+ * @param store - Reactive state object
+ * @returns Cleanup function to remove all bindings
+ * @throws {Error} If root is not an HTMLElement
+ * @throws {Error} If store is not a reactive state object
+ * 
+ * @example
+ * ```typescript
+ * const store = state({ count: 0 });
+ * const cleanup = bindDom(document.body, store);
+ * 
+ * // Later: cleanup all bindings
+ * cleanup();
+ * ```
+ * 
+ * HTML:
+ * ```html
+ * <span data-bind="count"></span>
+ * <input data-bind="name">
+ * ```
+ */
+export function bindDom(
+  root: HTMLElement,
+  store: ReactiveState<any>
+): Unsubscribe;