lego-dom 2.0.2 → 2.0.4-alpha

package/.md

@@ -0,0 +1,78 @@
+# LegoDOM Codebase Audit Report
+
+## 1. Component to Block Renaming
+The renaming of "Concept" from `Component` to `Block` appears to be consistent across the core codebase.
+
+- **Core Logic (`main.js`)**:
+  - `Lego.block()` is correctly defined and used.
+  - `registry` and logic maps are clean.
+  - No residual `Component` terminology found in core logic.
+  - `Lego.define` is safely aliased to `Lego.block` for backward compatibility.
+
+- **Vite Plugin (`vite-plugin.js`)**:
+  - Uses `virtual:lego-blocks`.
+  - Scans for `.lego` files in `src/blocks`.
+  - Imports helper functions from `parse-lego.js`.
+
+- **Tests**:
+  - `tests/naming.test.js` and `tests/parse-lego.test.js` utilize correct `Block` terminology.
+  - All tests passed successfully.
+
+- **Minor Inconsistencies (Non-Critical)**:
+  - `examples/vite-app/src/app.js`: Imports the virtual module as `registerComponents`.
+  - `examples/benchmark.html`: User-facing text still refers to "Components".
+
+## 2. `.lego` File Parsing Logic Issues (Critical)
+
+A significant fragility was identified in how `.lego` files (Single File Blocks) are parsed in both `main.js` (runtime loader) and `parse-lego.js` (build-time plugin).
+
+### The Issue
+The parsing logic relies on a regex that strictly expects an object literal export:
+```javascript
+/export\s+default\s+({[\s\S]*})/
+```
+This fails if a user defines a variable and exports it, or uses any other export syntax.
+
+**Example Failure Case:**
+```javascript
+<script>
+  const logic = {
+    data: { count: 0 }
+  };
+  export default logic;
+</script>
+```
+
+**Consequences:**
+1.  **Runtime (`defineLegoFile` in `main.js`)**:
+    The fallback mechanism tries to execute the entire script content inside a `new Function('return ' + script)`. This results in a `SyntaxError` because statements like `const` or `export` are not valid in a return statement.
+
+2.  **Build-time (`vite-plugin.js`)**:
+    The generated code becomes invalid JavaScript:
+    ```javascript
+    Lego.block('name', `tpl`, const logic = ...; export default logic;, 'styles');
+    ```
+    This causes the build or runtime execution to crash with a SyntaxError.
+
+### Recommendation
+Refactor the parsing logic to be more robust.
+- **For Build-time**: Parse the script properly or strip the `export default` text and wrap the rest in an IIFE or leave it as a valid expression if possible. A true JS parser would be safest.
+- **For Runtime**: Similar logic needed.
+
+## 3. Code Duplication
+There is significant logic duplication between `main.js` (`defineLegoFile`) and `parse-lego.js`.
+- Both contain identical regex for parsing `<template>`, `<script>`, `<style>`.
+- Both contain identical `deriveBlockName` logic.
+- Both contain the flawed `export default` extraction logic.
+
+**Recommendation**: Extract the parsing logic into a shared module that can be used by both `main.js` (if bundled or imported) and `vite-plugin.js`, or verify if `parse-lego.js` can be imported by `main.js` (currently `main.js` is a single file likely for CDN usage, complicating imports).
+
+## 4. Security Warning
+`main.js` line 915 uses `new Function` to evaluate the script block.
+```javascript
+const logicObj = new Function(`return ${script}`)();
+```
+While this is standard for some lightweight Runtime compilations, it assumes trusted content. The duplication of this risky logic (duplicated from `parse-lego.js` intent) increases the surface area for bugs.
+
+## Summary
+The renaming is successful. However, the `Single File Block` logic (`.lego` files) is brittle regarding script exports and should be addressed to prevent user frustration.

package/CHANGELOG.md

@@ -1,6 +1,31 @@
 # Changelog
 
 # Changelog
+## [2.0.4-alpha] - 2026-01-20
+
+### Fixes
+
+- **SSR/Node Compatibility:** Added checks for `window`, `document`, and `Node` throughout the core to ensure LegoDOM can be imported and executed in Node.js/SSR environments without crashing.
+- **Global Export:** `Lego` is now correctly exported to `global` in Node.js environments.
+
+## [2.0.3] - 2026-01-19
+
+### Features
+
+- **Reactive Persistence (`$db`):** New helper for persisting state to `localStorage` with automatic hydration, debouncing, and cross-tab synchronization.
+  ```html
+  <user-prefs b-logic="{
+    theme: $db('app.theme').default('light'),
+    volume: $db('app.vol').default(50).debounce(300)
+  }"></user-prefs>
+  ```
+  - **Auto-Load:** Values are automatically hydrated from `localStorage` on block creation.
+  - **Auto-Save:** Changes are automatically persisted (with optional debounce).
+  - **Cross-Tab Sync:** Updates in one tab automatically reflect in other tabs.
+
+### Documentation
+
+- Added `docs/guide/persistence.md` covering the `$db` API, namespacing best practices, and performance warnings.
 
 ## [2.0.2] - 2026-01-19
 

package/lego.js

@@ -1,2 +1,2 @@
 import './main.js';
-export const Lego = window.Lego;
+export const Lego = (typeof window !== 'undefined' ? window.Lego : global.Lego);

package/main.js

@@ -5,7 +5,47 @@ const Lego = (() => {
 
   const legoFileLogic = new Map();
   const sharedStates = new Map();
-  const expressionCache = new Map(); // Cache for compiled expressions
+
+  // LRU Cache for compiled expressions (prevents unbounded memory growth)
+  class LRUCache {
+    constructor(limit = 1000) {
+      this.limit = limit;
+      this.cache = new Map();
+    }
+
+    get(key) {
+      if (!this.cache.has(key)) return undefined;
+
+      // Move to end (most recently used) by deleting and re-inserting
+      const value = this.cache.get(key);
+      this.cache.delete(key);
+      this.cache.set(key, value);
+      return value;
+    }
+
+    set(key, value) {
+      // If key exists, delete it first so we can re-insert at end
+      if (this.cache.has(key)) {
+        this.cache.delete(key);
+      } else if (this.cache.size >= this.limit) {
+        // Evict oldest (first item in Map)
+        const firstKey = this.cache.keys().next().value;
+        this.cache.delete(firstKey);
+      }
+
+      this.cache.set(key, value);
+    }
+
+    get size() {
+      return this.cache.size;
+    }
+
+    clear() {
+      this.cache.clear();
+    }
+  }
+
+  const expressionCache = new LRUCache(1000); // Max 1000 cached expressions
 
   const styleRegistry = new Map();
   let styleConfig = {};
@@ -98,10 +138,13 @@ const Lego = (() => {
 
   const createBatcher = () => {
     let queued = false;
-    const componentsToUpdate = new Set();
+    const blocksToUpdate = new Set();
     let isProcessing = false;
 
-    // Optimization: Single timer for all updated hooks instead of one per component
+    // FIX: Queue for updates arriving during processing (prevents drops)
+    const pendingQueue = new Set();
+
+    // Optimization: Single timer for all updated hooks instead of one per block
     let updatedTimer = null;
     const pendingUpdated = new Set();
 
@@ -119,41 +162,200 @@ const Lego = (() => {
       }, 50); // Global debounce
     };
 
+    const processPendingQueue = () => {
+      if (pendingQueue.size > 0) {
+        // Move pending to main queue
+        pendingQueue.forEach(el => blocksToUpdate.add(el));
+        pendingQueue.clear();
+
+        // Trigger next batch if not already queued
+        if (!queued && blocksToUpdate.size > 0) {
+          queued = true;
+          requestAnimationFrame(processBatch);
+        }
+      }
+    };
+
+    const processBatch = () => {
+      isProcessing = true;
+      const batch = Array.from(blocksToUpdate);
+      blocksToUpdate.clear();
+      queued = false;
+
+      // Simple synchronous render loop (faster for small batches, no overhead)
+      batch.forEach(el => {
+        if (el.isConnected) render(el);
+      });
+
+      // Batch complete: Queue updated hooks efficiently
+      batch.forEach(el => pendingUpdated.add(el));
+      scheduleUpdatedHooks();
+      isProcessing = false;
+
+      // FIX: Process pending queue after batch completes
+      processPendingQueue();
+    };
+
     return {
       add: (el) => {
-        if (!el || isProcessing) return;
-        componentsToUpdate.add(el);
+        if (!el) return;
+
+        // FIX: Queue during processing instead of dropping
+        if (isProcessing) {
+          pendingQueue.add(el);
+          return;
+        }
+
+        blocksToUpdate.add(el);
         if (queued) return;
         queued = true;
 
-        requestAnimationFrame(() => {
-          isProcessing = true;
-          const batch = Array.from(componentsToUpdate);
-          componentsToUpdate.clear();
-          queued = false;
+        requestAnimationFrame(processBatch);
+      }
+    };
+  };
+
+  const globalBatcher = createBatcher();
+
+  // --- Persistence Layer ($db) ---
+  const dbBindings = new Map(); // storageKey -> Set<{target, prop}>
+  const dbTimers = new Map();   // storageKey -> timerId
+
+  const registerDbBinding = (target, prop, key) => {
+    if (!dbBindings.has(key)) dbBindings.set(key, new Set());
+    dbBindings.get(key).add({ target, prop });
+  };
+
+  // Storage quota management (FIFO eviction)
+  const storageKeys = new Map(); // key -> { timestamp, size }
+
+  const evictOldestKeys = (bytesNeeded) => {
+    const entries = Array.from(storageKeys.entries())
+      .filter(([key]) => key.startsWith('lego:')) // Only evict Lego keys
+      .sort((a, b) => a[1].timestamp - b[1].timestamp); // Oldest first
+
+    let freedBytes = 0;
+    const evicted = [];
 
-          // Simple synchronous render loop (faster for small batches, no overhead)
-          batch.forEach(el => render(el));
+    for (const [key, meta] of entries) {
+      if (freedBytes >= bytesNeeded) break;
+
+      try {
+        localStorage.removeItem(key);
+        freedBytes += meta.size;
+        evicted.push(key);
+        storageKeys.delete(key);
+      } catch (e) {
+        console.error(`[Lego] Failed to evict ${key}:`, e);
+      }
+    }
 
-          // Batch complete: Queue updated hooks efficiently
-          batch.forEach(el => pendingUpdated.add(el));
-          scheduleUpdatedHooks();
-          isProcessing = false;
+    return evicted;
+  };
+
+  const scheduleSave = (key, value, debounce) => {
+    if (dbTimers.has(key)) clearTimeout(dbTimers.get(key));
+    const save = () => {
+      try {
+        const serialized = JSON.stringify(value);
+        const sizeBytes = new Blob([serialized]).size;
+
+        // Attempt write
+        localStorage.setItem(key, serialized);
+
+        // Track for eviction (prefix with 'lego:' for identification)
+        const storageKey = key.startsWith('lego:') ? key : `lego:${key}`;
+        storageKeys.set(storageKey, {
+          timestamp: Date.now(),
+          size: sizeBytes
         });
+
+        dbTimers.delete(key);
+      } catch (e) {
+        if (e.name === 'QuotaExceededError') {
+          console.warn(`[Lego] Storage quota exceeded for key: ${key}`);
+
+          // Attempt eviction and retry
+          try {
+            const serialized = JSON.stringify(value);
+            const sizeBytes = new Blob([serialized]).size;
+            const evicted = evictOldestKeys(sizeBytes * 2); // Free 2x needed space
+
+            if (evicted.length > 0) {
+              console.log(`[Lego] Evicted ${evicted.length} old keys, retrying save`);
+              localStorage.setItem(key, serialized);
+
+              const storageKey = key.startsWith('lego:') ? key : `lego:${key}`;
+              storageKeys.set(storageKey, {
+                timestamp: Date.now(),
+                size: sizeBytes
+              });
+            } else {
+              config.onError(new Error(`Storage quota exceeded and no keys available for eviction`), 'quota', key);
+            }
+          } catch (retryErr) {
+            config.onError(new Error(`Critical: Could not save ${key} even after eviction`), 'quota-critical', key);
+          }
+        } else {
+          console.error(`[Lego] Storage Error (${key}):`, e);
+        }
       }
     };
+    if (debounce > 0) {
+      dbTimers.set(key, setTimeout(save, debounce));
+    } else {
+      save();
+    }
   };
 
-  const globalBatcher = createBatcher();
+  // Cross-tab Synchronization
+  if (typeof window !== 'undefined') {
+    window.addEventListener('storage', (e) => {
+      if (!e.key || !dbBindings.has(e.key)) return;
+      try {
+        const newValue = JSON.parse(e.newValue);
+        dbBindings.get(e.key).forEach(({ target, prop, el, batcher }) => {
+          target[prop] = newValue; // Update raw data
+          if (el && batcher) batcher.add(el); // Trigger re-render
+        });
+      } catch (e) { }
+    });
+  }
+
+  const dbMetadata = new WeakMap(); // target -> { prop: { key, debounce } }
+
+  const isNode = (val) => typeof Node !== 'undefined' && val instanceof Node;
 
   const reactive = (obj, el, batcher = globalBatcher) => {
-    if (obj === null || typeof obj !== 'object' || obj instanceof Node) return obj;
+    if (obj === null || typeof obj !== 'object' || isNode(obj)) return obj;
     if (proxyCache.has(obj)) return proxyCache.get(obj);
 
+    // Hydrate $db descriptors
+    for (const k in obj) {
+      const desc = obj[k];
+      if (desc && desc.__type === 'lego-db') {
+        let val = desc._default;
+        try {
+          const item = localStorage.getItem(desc.key);
+          if (item !== null) val = JSON.parse(item);
+        } catch (e) { }
+
+        obj[k] = val; // Replace descriptor with value
+
+        // Register metadata
+        if (!dbMetadata.has(obj)) dbMetadata.set(obj, {});
+        dbMetadata.get(obj)[k] = { key: desc.key, debounce: desc._debounce };
+
+        // Register for cross-tab updates
+        if (!dbBindings.has(desc.key)) dbBindings.set(desc.key, new Set());
+        dbBindings.get(desc.key).add({ target: obj, prop: k, el, batcher });
+      }
+    }
+
     const handler = {
       get: (t, k) => {
         const val = Reflect.get(t, k);
-        if (val !== null && typeof val === 'object' && !(val instanceof Node)) {
+        if (val !== null && typeof val === 'object' && !isNode(val)) {
           return reactive(val, el, batcher);
         }
         return val;
@@ -161,7 +363,14 @@ const Lego = (() => {
       set: (t, k, v) => {
         const old = t[k];
         const r = Reflect.set(t, k, v);
-        if (old !== v) batcher.add(el);
+        if (old !== v) {
+          batcher.add(el);
+          // Check for DB binding
+          const meta = dbMetadata.get(t);
+          if (meta && meta[k]) {
+            scheduleSave(meta[k].key, v, meta[k].debounce);
+          }
+        }
         return r;
       },
       deleteProperty: (t, k) => {
@@ -618,15 +827,69 @@ const Lego = (() => {
   };
 
   const unsnap = (el) => {
+    // 1. Call unmounted lifecycle hook first
     if (el._studs && typeof el._studs.unmounted === 'function') {
       try { el._studs.unmounted.call(el._studs); } catch (e) { console.error(`[Lego] Error in unmounted:`, e); }
     }
 
+    // 2. Recursively unsnap children in shadowRoot
     if (el.shadowRoot) {
       [...el.shadowRoot.children].forEach(unsnap);
     }
 
+    // 3. Remove from active blocks tracking
     activeBlocks.delete(el);
+
+    // 4. Break circular references
+    if (el._studs) {
+      // Clear element references in state object
+      el._studs.$element = null;
+
+      // Clear $vars references to DOM elements
+      if (el._studs.$vars) {
+        Object.keys(el._studs.$vars).forEach(key => {
+          el._studs.$vars[key] = null;
+        });
+        el._studs.$vars = null;
+      }
+
+      // Break the proxy -> element reference
+      el._studs = null;
+    }
+
+    if (el.hasOwnProperty('state')) delete el.state;
+    // 6. Clear private data (bindings, flags, etc.)
+    // This removes references to DOM nodes in bindings array
+    const data = privateData.get(el);
+    if (data) {
+      // Clear bindings that hold node references
+      if (data.bindings) {
+        data.bindings.forEach(binding => {
+          binding.node = null;
+          binding.anchor = null;
+        });
+        data.bindings = null;
+      }
+      data.anchor = null;
+      privateData.delete(el);
+    }
+
+    // 7. Clear from for-loop pools (prevents pooled nodes from keeping refs)
+    if (forPools.has(el)) {
+      const pool = forPools.get(el);
+      pool.forEach((node, key) => {
+        if (node && node._studs) {
+          node._studs = null;
+        }
+      });
+      pool.clear();
+      forPools.delete(el);
+    }
+
+    // 8. Note: proxyCache is a WeakMap so we can't delete from it,
+    // but breaking the circular refs above allows GC to clean it up
+
+    // 9. Recursively unsnap light DOM children
     [...el.children].forEach(unsnap);
   };
 
@@ -665,14 +928,25 @@ const Lego = (() => {
 
     resolvedElements.forEach(el => {
       if (el) {
-        const component = document.createElement(match.tagName);
+        const block = document.createElement(match.tagName);
         // Atomic swap: MutationObserver in init() will pick this up
-        el.replaceChildren(component);
+        el.replaceChildren(block);
       }
     });
   };
 
+  // $db Factory
+  const dbFactory = (key) => ({
+    __type: 'lego-db',
+    key,
+    _default: undefined,
+    _debounce: 0,
+    default(v) { this._default = v; return this; },
+    debounce(ms) { this._debounce = ms; return this; }
+  });
+
   const publicAPI = {
+    db: dbFactory,
     snap,
     unsnap,
     init: async (root = document.body, options = {}) => {
@@ -740,7 +1014,7 @@ const Lego = (() => {
           document.head.appendChild(script);
         }
         Lego.route('/_/studio', 'lego-studio');
-        Lego.route('/_/studio/:component', 'lego-studio');
+        Lego.route('/_/studio/:block', 'lego-studio');
       }
 
       if (routes.length > 0) {
@@ -772,15 +1046,16 @@ const Lego = (() => {
     },
     globals: reactive({
       $route: {
-        url: window.location.pathname,
+        url: typeof window !== 'undefined' ? window.location.pathname : '/',
         route: '',
         params: {},
         query: {},
         method: 'GET',
         body: null
       },
-      $go: (path, ...targets) => _go(path, ...targets)(document.body)
-    }, document.body),
+      $go: (path, ...targets) => _go(path, ...targets)(document.body),
+      $db: dbFactory
+    }, typeof document !== 'undefined' ? document.body : null),
     defineLegoFile: (content, filename = 'block.lego') => {
       let template = '';
       let script = '{}';
@@ -828,8 +1103,7 @@ const Lego = (() => {
       }
 
       const name = deriveBlockName(filename);
-      // We must eval the script to get the object. 
-      // Safe-ish because it's coming from the "Server" (trusted source in this architecture)
+      // Inject $db helper into the scope
       const logicObj = new Function(`return ${script}`)();
 
       if (style) {
@@ -883,4 +1157,8 @@ const Lego = (() => {
 
 if (typeof window !== 'undefined') {
   window.Lego = Lego;
+} else if (typeof global !== 'undefined') {
+  global.Lego = Lego;
 }
+
+

package/monitoring-plugin.js

@@ -9,7 +9,7 @@ export const Monitoring = {
     renders: 0,
     errors: 0,
     slowRenders: 0,
-    components: new Map(), // tagName -> { count, avgTime }
+    blocks: new Map(), // tagName -> { count, avgTime }
   },
 
   // Configuration options
@@ -83,7 +83,7 @@ export const Monitoring = {
         this.metrics.renders = 0;
         this.metrics.errors = 0;
         this.metrics.slowRenders = 0;
-        this.metrics.components.clear();
+        this.metrics.blocks.clear();
       }
     };
 
@@ -99,11 +99,11 @@ export const Monitoring = {
       }
     }
 
-    if (!this.metrics.components.has(tagName)) {
-      this.metrics.components.set(tagName, { count: 0, totalTime: 0, avg: 0 });
+    if (!this.metrics.blocks.has(tagName)) {
+      this.metrics.blocks.set(tagName, { count: 0, totalTime: 0, avg: 0 });
     }
 
-    const stats = this.metrics.components.get(tagName);
+    const stats = this.metrics.blocks.get(tagName);
     stats.count++;
     stats.totalTime += duration;
     stats.avg = stats.totalTime / stats.count;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lego-dom",
-  "version": "2.0.2",
+  "version": "2.0.4-alpha",
   "license": "MIT",
   "description": "A feature-rich web components + SFC frontend framework",
   "main": "main.js",