# Bindings & Evaluation

VoltX’s binding layer is the glue between declarative `data-volt-*` attributes and the reactivity primitives that drive them.
Here we explain how the binder walks the DOM, how directives are dispatched, how expressions are compiled and executed, and the guardrails we erected while hardening the evaluator.

## Mount Pipeline

1. **Scope preparation** - `mount(root, scope)` first injects VoltX’s helper variables (`$store`, `$uid`, `$pins`, `$probe`, etc.) into the caller-provided scope.
   Helpers are frozen before exposure so user code cannot tamper with framework utilities.
2. **Tree walk** - We perform a DOM walk rooted at `root`, skipping subtrees marked with `data-volt-skip`.
   Elements cloaked with `data-volt-cloak` are un-cloaked during traversal.
3. **Attribute collection** - `getVoltAttrs()` extracts `data-volt-*` attributes and normalises modifiers (e.g. `data-volt-on-click.prevent` -> `on-click` with `.prevent`).
4. **Directive dispatch** - Structural directives (`data-volt-for`, `data-volt-if`) short-circuit the attribute loop because they clone/remove nodes.
   Everything else is routed through `bindAttribute()` which:
   - Routes `on-*` attributes to the event binding pipeline.
   - Routes `bind:*` aliases (e.g. `bind:value`) to attribute binding helpers.
   - For colon-prefixed segments (`data-volt-http:get`), hands control to plugin handlers.
   - Falls back to the directive registry or plugin registry, then logs an unknown binding warning.
5. **Lifecycle hooks** - Each bound element fires the global lifecycle callbacks (`beforeMount`, `afterMount`, etc.).
   Per-plugin lifecycles are surfaced via `PluginContext.lifecycle`.

Each directive registers clean-up callbacks so `mount()` can return a disposer that un-subscribes signals, removes event listeners, and runs plugin uninstall hooks.

## Directive Registry

We expose `registerDirective(name, handler)` to allow plugins to self-register.
Core only ships the structural directives and the minimal attribute/event set required for the base runtime.
This keeps the lib bundle slim and allows tree shaking to drop unused features.

`registerDirective()` is side-effectful at module evaluation time. Optional packages import the binder, call `registerDirective()`, and expose their entry point via Vite’s plugin system.
Consumers that never import the module never pay for its directives.

## Expression Compilation

All binding expressions funnel through `evaluate(expr, scope)` (or `evaluateStatements()` for multi-statement handlers).
The evaluator implements a few layers of defense:

### Cached `new Function`

- Expressions are compiled into functions with `new Function("$scope", "$unwrap", ...)`.
- We wrap execution in a `with ($scope) { ... }` block to preserve ergonomic access to identifiers.
- Compiled functions are cached in a `Map` keyed by the expression string + mode (`expr` vs `stmt`)
   Cache hits avoid re-parsing and reduce GC churn.

### Hardened Scope Proxy

`createScopeProxy(scope)` builds an `Object.create(null)` proxy that:

- Returns `undefined` for dangerous identifiers and properties (`constructor`, `__proto__`, `globalThis`, `Function`, etc.).
- Reuses VoltX’s `wrapValue()` utility to auto-unwrap signals while guarding against prototype pollution.
- Treats setters specially: if a scope entry is a signal, assignments route to `signal.set()`.
- Spoofs `has` so the `with` block never falls through to `globalThis`.

Every call to `evaluate()` constructs this proxy and iss fast because signals and helpers are stored on the original scope, not the proxy.

### Safe Negation & `$unwrap`

Logical negation (`!signal`) is tricky when signals are proxied objects.
Before compilation we run `transformExpression()` which rewrites top-level `!identifier` patterns into `!$unwrap(identifier)`.
`$unwrap()` dereferences signals without exposing their methods, making boolean coercion reliable even when the underlying value is a reactive proxy or computed signal.

### Signal-Aware Wrapping

`wrapValue()` enforces blocking rules and auto-unwrapping:

- Signal reads return a small proxy exposing `get`, `set`, and `subscribe` while delegating property reads to the underlying value.
- Nested values re-enter `wrapValue()` so the entire object graph respects the hazardous-key deny list.
- When `unwrapSignals` is enabled (default for read contexts), signal reads return their current value so DOM bindings can treat them like plain data.
- Statement contexts (event handlers, `data-volt-init`) pass `{ unwrapSignals: false }` so authors can still call `count.set()` or `store.set()` directly.

### Error Surfacing

Any runtime error thrown by the compiled function is wrapped in `EvaluationError` which carries the original expression for better debugging.
Reference errors (missing identifiers) return `undefined` to mimic plain JavaScript.

## Event Handlers

`data-volt-on-*` bindings support modifiers (`prevent`, `stop`, `self`, `once`, `window`, `document`, `debounce`, `throttle`, `passive`). Before executing the handler we assemble an `eventScope` that inherits the original scope but adds `$el` and `$event`. Statements run sequentially; the last value is returned. If the handler returns a function we invoke it with the triggering event to mimic inline handler ergonomics (`data-volt-on-click="(ev) => fn(ev)"`).

Debounce/throttle modifiers wrap the execute function with cancellable helpers. Clean-up hooks clear timers when the element unmounts.

## Structural/Control Directives

### `data-volt-if`

- Clones/discards `if` and optional `else` templates.
- Evaluates the condition reactively; dependencies are tracked via `extractDeps()` which scans expressions for signals.
- Supports surge transitions by awaiting `executeSurgeEnter/Leave()` when available.
- Maintains branch state so redundant renders are skipped. Clean-up disposes child mounts when a branch is swapped out.

### `data-volt-for`

- Parses `"item in items"` or `"(item, index) in items"` grammar.
- Uses a placeholder comment to maintain insertion position.
- Re-renders on dependency changes by clearing existing clones and re-mounting with a child scope containing the loop variables.
- Registers per-item clean-up disposers so each clone tears down correctly.

## Data Flow & Dependency Tracking

Reactive updates rely on `updateAndRegister(ctx, update, expr)`:

1. Executes the update function immediately for initial DOM synchronisation.
2. Calls `extractDeps()` to gather signals referenced within the expression (with special handling for `$store.get()` lookups).
3. Subscribes to each signal and pushes the unsubscribe callback into the directive’s clean-up list.

This pattern is used by text/html bindings, class/style bindings, show/if/for, and plugin-provided directives.

## Challenges & Lessons

- **Security vs ergonomics** - Moving from a hand-rolled parser to `new Function` simplified expression support but introduced sandboxing risks.
   The scope proxy and whitelists were essential to close off prototype pollution and global escape hatches.
- **Signal negation** - `!signal` originally returned `false` because the proxy object was truthy.
   The `$unwrap` transformation ensures boolean logic matches user expectations without forcing explicit `.get()` calls.
- **Plugin isolation** - Allowing plugins to register directives meant we had to guarantee that the core binder stays stateless.
   Directive handlers receive a `PluginContext` with controlled capabilities so they can integrate without mutating internal machinery.
- **Error visibility** - Swallowing exceptions made debugging inline expressions painful.
   `EvaluationError` and consistent logging in directives give developers actionable stack traces while keeping the runtime resilient.

With these guardrails the binder provides a secure, extensible bridge between declarative templates and VoltX’s reactive runtime.