fix: Plugin demo (#8)

* fix: ensure computed keys are emitted in kebab case in markup
* added shorthand attribute forms
* added CSS fallback for shift animations

* fix: spread handling of signals
* transformExpr automatically unwraps signals in obj
* docs: updated internal docs to reflect proxy & iterator handling

Author: desertthunder

docs/internals/proxies.md

@@ -33,7 +33,7 @@ When a consumer reads `proxy.key`:
     If it’s an object/function, we recursively call `reactive()` so nested access stays reactive.
     Otherwise we return `signal.get()` which unwraps the value.
 
-This layered approach means `reactive()` objects are safe to embed in evaluator scopes—the same dangerous keys are filtered and every nested property remains reactive.
+This layered approach means `reactive()` objects are safe to embed in evaluator scopes. The same dangerous keys are filtered and every nested property remains reactive.
 
 ## Property Mutation (set trap)
 
@@ -64,7 +64,7 @@ Methods that do not mutate (e.g. `slice`) pass through unwrapped.
 
 ## Integration with Signals
 
-Every reactive property is backed by a `signal`. This keeps the proxy layer thin—core logic lives in `signal.ts`, and the proxy simply orchestrates reads/writes against those signals.
+Every reactive property is backed by a `signal`. This keeps the proxy layer thin. Core logic lives in `signal.ts`, and the proxy simply orchestrates reads/writes against those signals.
 Because signals already integrate with dependency tracking, reactive object reads automatically wire into computeds, effects, and DOM bindings without extra bookkeeping.
 
 ## Interop Utilities
@@ -82,6 +82,21 @@ Bindings and expressions run via the hardened evaluator. When it encounters a re
 - Signals returned from proxy properties expose `get`, `set`, and `subscribe`, but property reads on the signal proxy delegate back to the underlying value.
 - Primitive coercion works because the wrapper defines `valueOf`, `toString`, and `Symbol.toPrimitive` on demand.
 - Boolean negation (`!signal`) is rewritten to `!$unwrap(signal)` before compilation so reactive values behave like plain booleans.
+- **Iteration support** - Signal wrappers implement `Symbol.iterator` to enable spread operations on signals containing iterable values.
+
+### Spread Operator Support
+
+When a signal contains an iterable value (like an array), the wrapper proxy delegates the `Symbol.iterator` property to the unwrapped value.
+This enables the JavaScript spread operator to work transparently:
+
+```javascript
+const todos = signal([{id: 1, text: "Learn"}, {id: 2, text: "Build"}]);
+const newTodos = [...todos, {id: 3, text: "Ship"}];
+```
+
+Without this, the spread operator would fail because the JS runtime can't iterate over the signal wrapper.
+The implementation returns the iterator from the unwrapped array directly, ensuring spread operations receive raw values rather than wrapped proxies.
+This is critical for immutable update patterns where new arrays are constructed from existing signal values.
 
 ## Challenges & Lessons
 

docs/internals/reactivity.md

@@ -1,6 +1,6 @@
 # Reactivity Architecture
 
-VoltX’s reactivity system is built around a small set of primitives—signals, computed signals, and effects—that coordinate via an explicit dependency tracker.
+VoltX’s reactivity system is built around a small set of primitives: signals, computed signals, and effects, that coordinate via an explicit dependency tracker.
 This document explains how those pieces fit together, how updates flow through the system, and the trade-offs we made while hardening the implementation.
 
 ## Signals
@@ -88,6 +88,33 @@ The evaluator uses a scope proxy that wraps signal objects differently based on
 
 This dual behavior is controlled by the `opts.unwrapSignals` parameter passed to `evaluate()`.
 
+### Object Literal Unwrapping
+
+A subtle challenge arises when event handlers create object literals using signal values. Consider this common pattern:
+
+```html
+<button data-volt-on-click="todos.set([...todos, {id: todoId, text: newText, done: false}])">
+  Add Todo
+</button>
+```
+
+Without special handling, the object literal `{id: todoId, text: newText, done: false}` would capture **wrapped signal proxies** as property values instead of their unwrapped values. This breaks equality comparisons later when trying to match todos by ID.
+
+To solve this, the `transformExpr` function applies a compile-time transformation: it automatically unwraps signal identifiers used directly as object property values. The expression above is rewritten to:
+
+```javascript
+{id: $unwrap(todoId), text: $unwrap(newText), done: false}
+```
+
+This transformation:
+
+- Only applies to simple identifiers after `:` in object literals (e.g., `{key: identifier}`)
+- Does not affect method calls (e.g., `{text: newText.trim()}` remains unchanged)
+- Does not affect property access or computed values (e.g., `{id: obj.id}` remains unchanged)
+- Ensures object literals created in write-mode contexts contain primitive values, not wrapper proxies
+
+This keeps the mental model simple: users write natural JavaScript object literals and the evaluator ensures signal values are materialized correctly, regardless of whether `unwrapSignals` is true or false.
+
 ## Scope Helpers
 
 When a scope is mounted, VoltX injects several helpers that lean on the reactive core:
@@ -114,13 +141,11 @@ When batching is needed, use `$pulse` or wrap updates in a custom queue.
 ## Challenges & Trade-offs
 
 - **Minimal core vs features** - The system intentionally avoids hidden mutation queues or scheduler magic.
-This keeps mental models simple but means users must explicitly batch when necessary.
+    This keeps mental models simple but means users must explicitly batch when necessary.
 - **Signal identity** - Equality checks are referential.
     While fast, it means that mutating nested objects without cloning can bypass change detection unless you touch the signal again.
     We emphasises immutable patterns or explicit `set()` calls with copies.
 - **Dependency discovery** - Parsing expressions to pre-collect dependencies (`extractDeps`) introduces heuristics (e.g. `$store.get()` handling).
     We balance accuracy with performance by focusing on common patterns and falling back to runtime evaluation if static analysis fails.
 - **Error resilience** - Subscriber callbacks, cleanup functions, and recompute bodies are wrapped in try/catch to prevent one failure from derailing the reactive loop.
-    The trade-off is noisy console logs, but the alternative—silently swallowing issues—was harder to debug.
-
-Despite the lightweight implementation, these primitives provide deterministic, traceable update flows that underpin VoltX’s declarative bindings and plugin ecosystem.
+    The trade-off is noisy console logs, but the alternative (silent errors & no observability) was harder to debug.

docs/spec/plugin-spec.md

@@ -249,6 +249,13 @@ Reads URL parameter on mount and sets signal value. Signal changes do not update
 <input data-volt-on-input="handleSearch" data-volt-url="sync:searchQuery" />
 ```
 
+You can also use the shorthand attribute form where the signal name is encoded in the attribute suffix:
+
+```html
+<!-- Equivalent to data-volt-url="sync:searchQuery" -->
+<input data-volt-url:searchQuery="query" />
+```
+
 Changes to signal update URL parameter, changes to URL update signal. Uses History API for clean URLs.
 
 **Hash Routing:**
@@ -267,6 +274,8 @@ Keeps hash portion of URL in sync with signal. Useful for client-side routing.
 - Listens to `popstate` for browser back/forward
 - Debounces URL updates to avoid excessive history entries
 - Automatically serializes/deserializes values (strings, numbers, booleans)
+- Accepts `data-volt-url="mode:signal"` or `data-volt-url:signal="mode"` forms
+- Supports `query`, `hash`, and `history` mode aliases in shorthand attributes (e.g., `data-volt-url:filter="query"`)
 
 ## Implementation
 

docs/usage/bindings.md

@@ -364,6 +364,7 @@ The binding syntax is `data-volt-url:signalName="urlPart"` where URL part is:
 
 - `query`: Sync with query parameter (e.g., `?page=1`)
 - `hash`: Sync with URL hash (e.g., `#section`)
+- `history`: Sync with the full pathname + search (e.g., `data-volt-url:route="history:/app"`)
 
 Signal changes update the URL, and URL changes (back/forward navigation) update signals. This enables client-side routing without additional libraries.
 

docs/usage/routing.md

@@ -31,7 +31,7 @@ This guide walks through building both hash-based and History API routers that s
     ```
 
     ```ts
-    // src/main.ts — bundled projects
+    // src/main.ts -> entry point for a bundled project
     import { charge, initNavigationListener, registerPlugin, urlPlugin } from "voltx.js";
 
     registerPlugin("url", urlPlugin);

docs/usage/state.md

@@ -64,6 +64,7 @@ The name becomes a signal in the scope, and the attribute value is the computati
 ```
 
 Computed values defined this way follow the same rules as programmatic computed signals: they track dependencies and update automatically.
+For multi-word signal names, prefer kebab-case in the attribute (e.g., `data-volt-computed:active-todos`) — HTML lowercases attribute names and Volt converts kebab-case back to camelCase (`activeTodos`) automatically.
 
 ## Programmatic State
 
@@ -105,6 +106,7 @@ VoltX automatically unwraps signals in read contexts, making expressions simpler
 ```
 
 **Read Contexts** (signals auto-unwrapped):
+
 - `data-volt-text`, `data-volt-html`
 - `data-volt-if`, `data-volt-else`
 - `data-volt-for`
@@ -113,6 +115,7 @@ VoltX automatically unwraps signals in read contexts, making expressions simpler
 - `data-volt-computed:*` expressions
 
 **Write Contexts** (signals not auto-unwrapped):
+
 - `data-volt-on-*` event handlers
 - `data-volt-init` initialization code
 - `data-volt-model` (handles both read and write automatically)

lib/README.md

@@ -66,7 +66,9 @@ Plugins are opt-in and can be combined declaratively or registered programmatica
 
 ## VoltX.css
 
-VoltX ships with an optional classless CSS framework inspired by Pico CSS and Tufte CSS. It provides beautiful, semantic styling without requiring any CSS classes—just write semantic HTML and it looks great. It's perfect for prototyping.
+VoltX ships with an optional classless CSS framework inspired by Pico CSS and Tufte CSS.
+It provides beautiful, semantic styling without requiring any CSS classes.
+Just write semantic HTML and it looks great. It's perfect for prototyping.
 
 ### Features
 
@@ -94,7 +96,7 @@ Or include via CDN:
 
 ### Usage
 
-No classes needed—just write semantic HTML:
+No classes needed. Just write semantic HTML:
 
 ```html
 <article>

lib/src/core/binder.ts

@@ -1,5 +1,5 @@
 /**
- * Binder system for mounting and managing VoltX.js bindings
+ * Binder system for mounting and managing VoltX bindings
  */
 
 import { executeSurgeEnter, executeSurgeLeave, hasSurge } from "$plugins/surge";
@@ -46,8 +46,25 @@ export function registerDirective(name: string, handler: DirectiveHandler): void
   directiveRegistry.set(name, handler);
 }
 
+function scheduleTransitionTask(cb: () => void): void {
+  let executed = false;
+  const wrapped = () => {
+    if (executed) {
+      return;
+    }
+    executed = true;
+    cb();
+  };
+
+  if (typeof requestAnimationFrame === "function") {
+    requestAnimationFrame(wrapped);
+  }
+
+  setTimeout(wrapped, 16);
+}
+
 /**
- * Mount VoltX.js on a root element and its descendants and binds all data-volt-* attributes to the provided scope.
+ * Mount VoltX on a root element and its descendants and binds all data-volt-* attributes to the provided scope.
  *
  * @param root - Root element to mount on
  * @param scope - Scope object containing signals and data
@@ -313,7 +330,7 @@ function bindShow(ctx: BindingContext, expr: string): void {
 
     isTransitioning = true;
 
-    requestAnimationFrame(() => {
+    scheduleTransitionTask(() => {
       void (async () => {
         try {
           if (shouldShow) {
@@ -874,6 +891,7 @@ function bindIf(ctx: BindingContext, expr: string): void {
   let currentCleanup: Optional<CleanupFunction>;
   let currentBranch: Optional<"if" | "else">;
   let isTransitioning = false;
+  let pendingRender = false;
 
   const render = () => {
     const condition = evaluate(expr, ctx.scope);
@@ -882,6 +900,9 @@ function bindIf(ctx: BindingContext, expr: string): void {
     const targetBranch = shouldShow ? "if" : (elseTempl ? "else" : undefined);
 
     if (targetBranch === currentBranch || isTransitioning) {
+      if (isTransitioning) {
+        pendingRender = true;
+      }
       return;
     }
 
@@ -915,55 +936,57 @@ function bindIf(ctx: BindingContext, expr: string): void {
 
     isTransitioning = true;
 
-    requestAnimationFrame(() => {
-      void (async () => {
-        try {
-          if (currentElement) {
-            const currentEl = currentElement as HTMLElement;
-            const currentHasSurge = currentBranch === "if" ? ifHasSurge : elseHasSurge;
-
-            if (currentHasSurge) {
-              await executeSurgeLeave(currentEl);
-            }
-
-            if (currentCleanup) {
-              currentCleanup();
-              currentCleanup = undefined;
-            }
-            currentElement.remove();
-            currentElement = undefined;
+    void (async () => {
+      try {
+        if (currentElement) {
+          const currentEl = currentElement as HTMLElement;
+          const currentHasSurge = currentBranch === "if" ? ifHasSurge : elseHasSurge;
+
+          if (currentHasSurge) {
+            await executeSurgeLeave(currentEl);
           }
 
-          if (targetBranch === "if") {
-            currentElement = ifTempl.cloneNode(true) as Element;
-            delete (currentElement as HTMLElement).dataset.voltIf;
-            placeholder.before(currentElement);
+          if (currentCleanup) {
+            currentCleanup();
+            currentCleanup = undefined;
+          }
+          currentElement.remove();
+          currentElement = undefined;
+        }
 
-            if (ifHasSurge) {
-              await executeSurgeEnter(currentElement as HTMLElement);
-            }
+        if (targetBranch === "if") {
+          currentElement = ifTempl.cloneNode(true) as Element;
+          delete (currentElement as HTMLElement).dataset.voltIf;
+          placeholder.before(currentElement);
 
-            currentCleanup = mount(currentElement, ctx.scope);
-            currentBranch = "if";
-          } else if (targetBranch === "else" && elseTempl) {
-            currentElement = elseTempl.cloneNode(true) as Element;
-            delete (currentElement as HTMLElement).dataset.voltElse;
-            placeholder.before(currentElement);
+          if (ifHasSurge) {
+            await executeSurgeEnter(currentElement as HTMLElement);
+          }
 
-            if (elseHasSurge) {
-              await executeSurgeEnter(currentElement as HTMLElement);
-            }
+          currentCleanup = mount(currentElement, ctx.scope);
+          currentBranch = "if";
+        } else if (targetBranch === "else" && elseTempl) {
+          currentElement = elseTempl.cloneNode(true) as Element;
+          delete (currentElement as HTMLElement).dataset.voltElse;
+          placeholder.before(currentElement);
 
-            currentCleanup = mount(currentElement, ctx.scope);
-            currentBranch = "else";
-          } else {
-            currentBranch = undefined;
+          if (elseHasSurge) {
+            await executeSurgeEnter(currentElement as HTMLElement);
           }
-        } finally {
-          isTransitioning = false;
+
+          currentCleanup = mount(currentElement, ctx.scope);
+          currentBranch = "else";
+        } else {
+          currentBranch = undefined;
         }
-      })();
-    });
+      } finally {
+        isTransitioning = false;
+        if (pendingRender) {
+          pendingRender = false;
+          render();
+        }
+      }
+    })();
   };
 
   updateAndRegister(ctx, render, expr);