lego-dom 1.5.0 → 2.1.1-alpha

package/.todo

@@ -0,0 +1,73 @@
+P0
+
+P1
+
+P2
+Add TypeScript definitions
+Build DevTools extension
+Implement proper plugin architecture
+
+P3
+SSR/hydration support
+Code-splitting for routes
+Integration with APM tools
+
+
+A DevTools extension for LegoDOM would be a game-changer because it allows developers to "peek behind the plastic" of the Web Components. Since LegoDOM uses native Shadow DOM and Constructable Stylesheets, a standard "Elements" panel often hides the reactive logic.
+
+Here is a vision for what Lego Studio DevTools could look like:
+
+1. The "Lego Tree" (Block Inspector)
+Instead of a generic DOM tree, this panel would filter out the noise and show the structure of your application in terms of Blocks.
+
+Visual Distinction: Lego blocks (Custom Elements) would be highlighted with a unique icon/color (e.g., a Lego brick icon).
+Breadcrumbs: See the hierarchy of a block: App > Dashboard > Sidebar > UserProfile.
+Select to Inspect: Click a block in the browser to automatically jump to its state and logic in the DevTools.
+2. Reactive State Monitor ($state & $db)
+The "Heart" of the extension.
+
+Live Store View: A real-time JSON tree of the current $db (persistent) and local $state.
+Direct Modification: Edit a value in the DevTools (e.g., change this.user.name to "Admin") and watch the UI update instantly.
+Update Flash: When a block re-renders because its state changed, it should briefly "flash" in the UI so you can track unnecessary renders.
+3. "Style Cascade" Explorer
+Since LegoDOM has unique features like b-cascade and Constructable Stylesheets, tracking where a style came from is crucial.
+
+Sheet Breakdown: For any selected block, show exactly which sheets are applied:
+Explicit: Defined in the <style> tag of the 
+.lego
+ file.
+External: Added via b-stylesheets.
+Inherited: Passed down via b-cascade from a parent.
+Toggle Switch: A checkbox next to each stylesheet to temporarily disable it for debugging.
+4. Directives Debugger
+A specialized view to see how directives are behaving:
+
+b-for: See the original array and the current "index" and "item" for the specific iteration you are hovering over.
+b-if: See the expression that evaluated to true or false.
+b-error: A "Heat Map" of error boundaries. If a block crashes, the DevTools should turn red and show you the exact $error object (message, stack trace) captured by the nearest boundary.
+5. "Open in Editor" Integration
+Since LegoDOM maps blocks to 
+.lego
+ files:
+
+Add a small button (or Ctrl+Click shortcut) on a block in DevTools that opens the corresponding file directly in VS Code or Lego Studio.
+6. Event Timeline (The "Radio" Tab)
+LegoDOM uses 
+$emit
+ and 
+$ancestors
+ for communication.
+
+A "Log" of all events flying through the app.
+See who fired the event (
+$emit
+) and who handled it.
+Filter by event name to track specific user flows.
+7. Performance & "Snap" Profiler
+LegoDOM uses the 
+snap()
+ function to sync state to DOM.
+Snap Count: See how many times a block has "snapped". If a block is snapping 100 times in a second, you’ve found a reactivity loop!
+Visual Aesthetic: The extension should feel like a "Command Center." Dark mode by default, vibrant primary colors for Lego bricks (Red for Errors, Blue for State, Yellow for Warnings), and smooth micro-animations when state updates.
+
+How it would work technically: It would likely inject a small script (a "bridge") that hooks into Lego.registry and Lego.db to pipe data to the Extension's background script!

package/CHANGELOG.md

@@ -1,8 +1,156 @@
 # Changelog
 
-## [1.5.0] - 2026-01-19
+## [2.1.1] - 2026-01-23
+Welcome to **LegoDOM v2**! This release represents a massive architectural shift to align the codebase and mental model with the "Lego" metaphor. We have moved away from Vue-centric terminology ("SFC", "Component", "Data") to Lego-centric terminology ("Lego File", "Block", "Logic").
+
+
+### 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.
+
+- **Vite Plugin DX:** Default `blocksDir` is now `./src` (was `./src/blocks`), allowing auto-discovery of `.lego` files anywhere in the source tree (as long as they follow the kebab-case hyphenation rule).
+
+- **`$index` in `b-for`:** Access the current item's 0-based index in loops.
+  ```html
+  <li b-for="item in items">
+    #[[ $index + 1 ]]: [[ item.name ]]
+  </li>
+  ```
+
+- **`b-key` Directive:** Optimized rendering for lists by providing stable identities for elements.
+
+- **Error Boundaries (`b-error`):** Gracefully handle block crashes with cascading error boundaries!
+  ```html
+  <template b-error="error-card">
+    <user-profile></user-profile>
+    <activity-feed></activity-feed>
+  </template>
+  ```
+  - **Cascading:** Errors bubble up to the nearest parent boundary (template or instance level).
+  - **Error Context:** Error blocks receive `$error` object with `message`, `stack`, and `component` properties.
+  - **Automatic Recovery:** Replace crashed blocks with custom fallback UI instead of blank screens.
+  - **Global Fallback:** Falls back to `config.onError` if no boundary is found.
+
+- **Cascading Stylesheets (`b-cascade`):** New attribute for selective stylesheet inheritance!
+  ```html
+  <body b-stylesheets="theme" b-cascade="theme">
+    <!-- All children inherit 'theme' automatically -->
+    <app-root></app-root>
+  </body>
+  ```
+  - **Inheritance:** Child blocks inherit stylesheets listed in `b-cascade` from their ancestors.
+  - **Explicit Override:** Adding `b-stylesheets` to a child merges with inherited styles (child-specific styles take precedence).
+  - **Debug API:** inspect inheritance with `Lego.debug.stylesheets($0)`.
+
+- **New CLI Tooling:** Released `create-legodom` for instant project scaffolding.
+  ```bash
+  npm create legodom@latest
+  ```
+
+- **Scoped Props (`b-logic`):** `b-logic` attributes now inherit the parent block's scope! You can pass state naturally to children without global variables.
+  ```html
+  <!-- 'user' is resolved from the parent block's state -->
+  <user-avatar b-logic="{ user: user }"></user-avatar>
+  ```
+
+- **`$parent` Helper:** Added `this.$parent` (and template access) to easily find the nearest ancestor Block. It intelligently skips non-block elements (divs, spans) and handles Shadow DOM boundaries.
+  ```javascript
+  const parentBlock = this.$parent;
+
+- **Public State API:**
+  - `element.state` is now the official public API for accessing the reactive proxy.
+  - `element._studs` is considered internal/private.
+
+- **Lego Studio Audit:**
+  - `lego-studio` has been refactored to use "Block" terminology throughout the UI and codebase.
+
 
-### Breaking Changes 🚨
+### Fixes
+
+- **Init Optimization:** Fixed double render on initialization. Route is now initialized before DOM scan, preventing reactive updates from triggering a second render pass.
+  - **Before:** Elements rendered twice (once during `snap()`, once when `_matchRoute()` updated `Lego.globals.$route`).
+  - **After:** Elements render once with correct route data already available.
+  - **Impact:** Faster initial load, cleaner error logs (no duplicate errors).
+
+- **Vite Plugin `b-cascade`/`b-error`:** Fixed a bug where `b-cascade` and `b-error` attributes defined in `.lego` files were not passed to `Lego.block()`, causing stylesheet inheritance and error boundaries to fail.
+
+- **Lego Studio Scaffolding:** Fixed an issue where `.lego` files were expected to be in `src/block`, causing a blank screen upon scaffolding.
+
+- **Global State Subscription Tracking:** Optimized global state updates from O(N) to O(K) complexity.
+  - Previously scanned all active blocks to check for global dependencies.
+  - Now maintains a dedicated `globalSubscribers` Set for instant lookups.
+  - Significantly faster for apps with thousands of blocks.
+
+- **Fixed Circular Reference Leaks:** Enhanced `unsnap()` to clear all closure-captured references.
+  - Explicitly nulls `$emit`, and deletes `$parent`, `$route`, `$go` getters.
+  - Prevents memory leaks from closures capturing element references.
+  - Ensures complete garbage collection of removed blocks.
+
+- **Auto-Discovery Logic:** Fixed a bug where elements present in the initial HTML were not detected by the `config.loader`. The discovery logic now scans the DOM during `Lego.init()` as well as on subsequent mutations.
+- **b-stylesheets Support:** Fully implemented `b-stylesheets` to allow blocks to adopt constructable stylesheets.
+- **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.
+
+- **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.
+
+### Breaking Changes 
+
+- **`b-for` Sibling Rendering:** The element with `b-for` is now **replaced** by its clones as siblings, instead of nesting clones inside itself. This fixes invalid HTML like `<p><p>...</p></p>` and ensures correct CSS behavior (hover, focus, etc.).
+  ```html
+  <!-- Template -->
+  <ul>
+    <li b-for="item in items">[[ item ]]</li>
+  </ul>
+  
+  <!-- Now renders as: -->
+  <ul>
+    <!--b-for: item in items-->
+    <li>Apple</li>
+    <li>Banana</li>
+  </ul>
+  ```
+
+- **Terminological Refactor (Runtime & Docs):**
+  - **Components → Blocks:** The fundamental unit of UI is now a "Block".
+  - **SFC → Lego File:** Protocol-agnostic Single File Blocks.
+
+- **API Renames:**
+  - `Lego.define()` is now **`Lego.block()`**. (Legacy alias maintained)
+  - `Lego.defineSFC()` is now **`Lego.defineLegoFile()`**.
+  - Internal: `deriveComponentName` is now `deriveBlockName`.
+
+- **Attribute Renames:**
+  - `b-data` is now **`b-logic`**. (Legacy alias maintained)
+  - `b-styles` is now **`b-stylesheets`**.
+
+
+### Developer Experience
+
+- **Error Logging:** Fixed 4 silent catch blocks that swallowed errors without any console output:
+  - `parseJSObject` now logs `b-data`/`b-logic` syntax errors.
+  - `b-key` warns when it resolves to `undefined`.
+  - localStorage hydration errors are now logged.
+  - Cross-tab sync errors are now logged.
+
+- **b-cascade Guide:** Added documentation for cascading stylesheets, best practices for global themes vs block styles.
+- **Directives:** Merged cascade docs into the main Directives guide.
+
+- Added `docs/guide/persistence.md` covering the `$db` API, namespacing best practices, and performance warnings.
+
+
+## [1.5.1] - 2026-01-19
+
+### Breaking Changes
 
 - **Renamed `b-styles` to `b-stylesheets`:** The directive for injecting shared stylesheets into shadow roots has been renamed from `b-styles` to `b-stylesheets` to avoid confusion with the `style` attribute and better reflect its purpose (injecting Constructable Stylesheets).
   ```html
@@ -18,6 +166,11 @@
 - **New "Helper Utilities" Guide:** Added a dedicated page at `/docs/guide/helpers.md` documenting core instance methods like `$ancestors`, `$emit`, `$route`, `$go`, `$vars`, `$element`, and `$registry`.
 - **Performance Tips Updated:** Revised the "Performance Tips" section in the Directives guide to correctly compare `b-show` (toggle visibility) vs `b-if` (DOM insertion/removal) instead of the outdated `b-show` vs CSS comparison.
 
+## [1.5.0] - 2026-01-19
+
+> [!WARNING] DEPRECATED
+> This version has been deprecated due to an incomplete rename of `b-styles`. Please use `1.5.1`.
+
 ## [1.4.0] - 2026-01-16
 
 ### Breaking Changes

package/README.md

@@ -19,6 +19,21 @@ Lego embraces the web platform. It turns standard HTML `<template>` tags into re
 
 ---
 
+## Quick Start
+
+The fastest way to create a new LegoDOM project:
+
+```bash
+npm create legodom@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+This scaffolds a complete project with Vite, the LegoDOM plugin, and a sample component!
+
+---
+
 ## Quick Start (No Build Required)
 
 ```html

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);