@daz4126/helium 1.0.0-rc.1 → 1.0.0-rc.3

package/README.md

@@ -18,24 +18,24 @@ It's really simple to use - just sprinkle the magic @attributes into your HTML a
 
 Helium is designed for developers who want:
 
-- **Lightweight** - Just over 3KB minified and gzipped
+- **Lightweight** - About 5.5–13.3KB minified and gzipped, depending on the build
 - **Powerful** - Declarative JavaScript in your HTML
 - **Zero build step** - Works directly in the browser with no compiling
 - **Easy to learn** - If you know HTML and basic JavaScript, you're ready
 
 ## Versions
 
-Helium comes in three versions so you can pick the right balance of features and size for your project:
+Helium comes in three core versions, with SSE available as an optional add-on, so you can pick the right balance of features and size for your project:
 
 ### Helium (Standard)
 
 The full-featured version with everything included.
 
-- All directives (`@text`, `@html`, `@bind`, `@data`, `@ref`, `@calculate`, `@effect`, `@init`, etc.)
+- All directives (`@text`, `@html`, `@for`, `@if`, `@bind`, `@data`, `@ref`, `@calculate`, `@effect`, `@init`, etc.)
 - Event handlers with modifiers
 - HTTP requests (`@get`, `@post`, `@put`, `@patch`, `@delete`)
 - Module imports (`@import`)
-- Server-Sent Events (SSE)
+- Optional Server-Sent Events (SSE) add-on
 - Turbo/Hotwire integration
 
 **Best for:** Most projects where you want the full power of Helium without worrying about CSP restrictions.
@@ -50,7 +50,8 @@ A slimmed-down version with just the core reactivity features.
 
 - Core directives (`@text`, `@html`, `@bind`, `@data`, `@ref`, `@calculate`, `@effect`, `@init`)
 - Event handlers with modifiers
-- No HTTP requests, imports, SSE, or Turbo integration
+- One global state namespace
+- No local `@data`, keyed `@for`, HTTP requests, imports, SSE, or Turbo integration
 
 **Best for:** Simple interactive pages where you only need reactivity and don't need server communication or module imports.
 
@@ -60,11 +61,38 @@ import helium from "@daz4126/helium/lite"
 
 ### Helium CSP
 
-A Content Security Policy safe version that doesn't require `unsafe-eval`. It uses [jexpr](https://github.com/nicolo-ribaudo/jexpr) as its expression engine instead of `new Function()`, while keeping the full feature set.
+A Content Security Policy safe version that doesn't require `unsafe-eval`. It uses [jexpr](https://github.com/nicolo-ribaudo/jexpr) as its expression engine instead of `new Function()`.
 
-- All the same features as the standard version
+- All the same directives and HTTP/Turbo/`@import` features as the standard version
+- Optional Server-Sent Events (SSE) add-on
+- `&&` / `||` / `??` short-circuit correctly, and optional chaining (`a?.b`) is supported
 - CSP-compliant — no `unsafe-eval` needed
 
+Because expressions run through a custom parser rather than the JS engine, a couple of syntax features differ from the standard build:
+
+- No `new` keyword — use the `$Date(...)` and `$FormData(...)` helpers instead
+- Expressions are single expressions, not arbitrary statements
+
+Expressions also run in a **restricted scope**: only side-effect-free builtins
+(`Math`, `Date`, `JSON`, `Object`, `Array`, `parseInt`, `URL`, and friends) are
+available. Capability-bearing globals — `window`, `document`, `fetch`,
+`localStorage`, `sessionStorage`, `navigator`, `location`, `history`, timers,
+and dialogs — are not reachable from expressions, so markup injected by an
+attacker can't use them to read cookies or storage. If a page legitimately
+needs one, opt in explicitly by passing the reference:
+
+```javascript
+import helium, { allowGlobals } from "@daz4126/helium/csp";
+
+allowGlobals({ localStorage, fetch });      // expose to expressions
+allowGlobals({ fetch: undefined });         // revoke again
+```
+
+(`helium.allowGlobals(...)` works too when using the global script build.)
+Note this reduces the attack surface but is not a sandbox: the `$get`/`$post`
+helpers and `$`/`$el`/`$html` magics remain available to any expression that
+can run at all.
+
 **Best for:** Projects with strict Content Security Policies that prohibit `unsafe-eval`.
 
 ```javascript
@@ -76,12 +104,25 @@ import helium from "@daz4126/helium/csp"
 | Feature | Standard | Lite | CSP |
 |---------|----------|------|-----|
 | Core directives | ✅ | ✅ | ✅ |
+| Element-local `@data` | ✅ | ❌ | ✅ |
+| Keyed `@for` | ✅ | ❌ | ✅ |
+| Conditional `@if` | ✅ | ❌ | ✅ |
 | Event handlers | ✅ | ✅ | ✅ |
 | HTTP requests | ✅ | ❌ | ✅ |
 | `@import` | ✅ | ❌ | ✅ |
-| SSE | ✅ | ❌ | ✅ |
+| SSE | Add-on | ❌ | Add-on |
 | Turbo integration | ✅ | ❌ | ✅ |
 | CSP safe | ❌ | ❌ | ✅ |
+| Approx. min+gzip size | 8.79KB | 5.52KB | 12.89KB |
+
+Sizes are enforced against the production Terser builds with gzip level 9. The
+CSP figure includes its expression parser. Adding SSE produces 9.17KB Standard
+and 13.27KB CSP bundles.
+
+Lite is generated from the same global-state reactive core as Standard. It has
+identical deep/shared reactivity, lifecycle, binding, and cleanup behavior for
+root state, but intentionally excludes element-local data and Standard's other
+extensions.
 
 ## Installation
 
@@ -104,6 +145,11 @@ Just import from the CDN in a script tag directly in your HTML page:
 <script type="module">
   import helium from 'https://cdn.jsdelivr.net/gh/daz-codes/helium/helium-csp.js';
 </script>
+
+<!-- Standard + SSE -->
+<script type="module">
+  import helium from 'https://cdn.jsdelivr.net/gh/daz-codes/helium/helium-sse.js';
+</script>
 ```
 
 ### NPM
@@ -115,14 +161,57 @@ npm install @daz4126/helium
 Then import the version you need:
 
 ```javascript
-import helium from "@daz4126/helium"       // Standard
-import helium from "@daz4126/helium/lite"   // Lite
-import helium from "@daz4126/helium/csp"    // CSP
+import helium from "@daz4126/helium"         // Standard
+import helium from "@daz4126/helium/lite"    // Lite
+import helium from "@daz4126/helium/csp"     // CSP
+import helium from "@daz4126/helium/sse"     // Standard + SSE
+import helium from "@daz4126/helium/csp/sse" // CSP + SSE
+```
+
+For a pre-minified, self-contained bundle, append `/min` to an entry point:
+
+```javascript
+import helium from "@daz4126/helium/min"
+import helium from "@daz4126/helium/sse/min"
 ```
 
+The source entry points remain browser-ready ES modules, so consuming Helium
+does not require a build step.
+
 ### Automatic Initialization
 
-Helium automatically initializes on `DOMContentLoaded`, so you typically don't need to call `helium()` manually unless you're providing default values or functions.
+Helium automatically initializes on `DOMContentLoaded`, so you typically don't need to call `helium()` manually. Calling it manually to provide initial values or functions suppresses the pending automatic initialization, so your state is not replaced when the DOM becomes ready.
+
+### Explicit Mounting
+
+Use `helium.mount()` when a page has multiple independent Helium roots. It
+accepts a selector or an element and returns the root's state plus an idempotent
+`unmount()` function:
+
+```html
+<section id="counter-a">
+  <button @click="count++">Increment</button>
+  <span @text="count"></span>
+</section>
+
+<section id="counter-b">
+  <button @click="count++">Increment</button>
+  <span @text="count"></span>
+</section>
+```
+
+```javascript
+const a = await helium.mount("#counter-a", { count: 0 })
+const b = await helium.mount("#counter-b", { count: 10 })
+
+a.state.count++ // Updates only #counter-a
+a.unmount()     // Safe to call more than once
+```
+
+Explicit roots have independent state, bindings, observers, listeners, refs,
+and cleanup. Calling `mount()` suppresses the pending automatic initialization;
+existing single-root pages can continue relying on auto-initialization or
+calling `helium(initialState)` directly.
 
 ## Helium Attributes
 
@@ -130,7 +219,10 @@ Helium uses custom attributes to add interactivity to HTML elements. To identify
 
 ### @helium
 
-This attribute sets the root element. Helium attributes can only be used on this element and its children. If not set then it defaults to `document.body`.
+This attribute sets the automatically initialized root element. Helium
+attributes are processed on that element and its children. If it is omitted,
+automatic initialization defaults to `document.body`. Explicit
+`helium.mount()` roots do not need this attribute.
 
 ```html
 <div @helium>
@@ -173,6 +265,69 @@ Similar to `@text`, but inserts HTML content into the element's innerHTML. Suppo
 
 **Alias:** `data-he-html`
 
+### @for with :key
+
+Standard and CSP can render arrays and other iterables as keyed DOM rows. Put
+`@for` and `:key` on a `<template>`; Lite deliberately excludes this feature.
+
+```html
+<ul>
+  <template @for="item, index in items" :key="item.id">
+    <li>
+      <span @text="index + 1"></span>.
+      <span @text="item.name"></span>
+      <button @click="item.done = !item.done">Toggle</button>
+    </li>
+  </template>
+</ul>
+```
+
+The optional second alias is the current zero-based index:
+
+```html
+<template @for="item in items" :key="item.id">
+  <!-- item is available to every Helium expression in this row -->
+</template>
+```
+
+Keys must be stable and unique. When the collection changes, Helium moves and
+reuses rows with matching keys, creates new rows, and removes missing rows. This
+preserves element identity, focus, listeners, and `@init` lifecycle state while
+still updating `item`, `index`, and normal root-state dependencies. Cleanup
+functions returned by `@init` run when their keyed row is removed.
+
+`@html="items.map(...).join('')"` remains useful for simple generated markup,
+but keyed `@for` avoids HTML-string interpolation and lets each row use normal
+`@text`, dynamic attributes, events, and other directives.
+
+**Alias:** `data-he-for` (the key remains `:key`)
+
+### @if
+
+Standard and CSP can conditionally render a `<template>`'s content. Unlike
+`@hidden`/`@visible`, which only toggle visibility, `@if` adds the content to
+the DOM when the expression is truthy and fully removes it — bindings,
+listeners, and `@init` cleanup included — when it becomes falsy:
+
+```html
+<template @if="loggedIn">
+  <p>Welcome back, <span @text="user.name"></span>!</p>
+  <button @click="logout($data)">Log out</button>
+</template>
+```
+
+Content that is switched off costs nothing: its expressions never evaluate and
+its listeners don't exist. Use `@if` for anything conditional-but-expensive
+(modals, tab panels, admin-only markup) and `@hidden`/`@visible` for cheap
+show/hide toggles where you want to preserve element state such as form input.
+
+`@if` requires a `<template>` element (like `@for`, and like Alpine's `x-if`)
+because template content is inert until inserted — that's what makes the "off"
+state free. It cannot be combined with `@for` on the same template; nest one
+template inside the other instead. Lite excludes this feature.
+
+**Alias:** `data-he-if`
+
 ### @bind
 
 Creates a 2-way binding between an input element's value and a variable. Whatever is entered in the following input field will be stored as a variable called name:
@@ -187,6 +342,13 @@ Works with:
 - Radio buttons (binds to `value`, checking the one that matches)
 - Select elements (binds to `value`)
 
+Nested paths work too — the parent object must already exist in state:
+
+```html
+<input @bind="user.name">
+<p @text="user.name"></p>
+```
+
 **Examples:**
 ```html
 <!-- Text input -->
@@ -209,7 +371,38 @@ Works with:
 </select>
 ```
 
-**Alias:** `data-he-bind`
+**`.number` modifier:** append `.number` to coerce the bound value to a number
+(handy for `type="number"` inputs, which otherwise bind as strings). An empty
+field stays `""`, and non-numeric input is left untouched so partial typing
+still works.
+
+```html
+<input type="number" @bind.number="age">
+<p @text="age + 1"></p> <!-- numeric addition, not string concatenation -->
+```
+
+**`.trim` modifier:** trim leading and trailing whitespace before storing user
+input in state:
+
+```html
+<input @bind.trim="name">
+```
+
+**`.lazy` modifier:** update state on the element's `change` event rather than
+on every `input` event. For text fields this normally means when the edit is
+committed or the field loses focus:
+
+```html
+<input @bind.lazy="search">
+```
+
+Modifiers can be combined in any order:
+
+```html
+<input @bind.lazy.trim.number="amount">
+```
+
+**Alias:** `data-he-bind` (for example `data-he-bind.lazy.trim`)
 
 ### @hidden & @visible
 
@@ -224,32 +417,76 @@ Makes the element hidden or visible depending on the result of a JavaScript expr
 
 ### @data
 
-Initializes variables that can be used in JavaScript expressions. This is useful for setting up initial state.
+Initializes variables that can be used in JavaScript expressions. In Standard
+and CSP, `@data` behaves like Alpine's `x-data`: root-level `@data` initializes
+the mounted root state, while nested `@data` creates local state for that
+element and its descendants. Lite always uses one global state namespace, so
+every `@data` merges into root state.
 
 ```html
-<div @data="{ count: 0, open: false, name: 'Helium' }"></div>
+<main @helium @data="{ count: 100, name: 'Helium' }">
+  <p @text="name + ': ' + count"></p>
+</main>
 ```
 
-You can then use these variables in other Helium attributes:
+Nested `@data` is local in Standard/CSP:
 
 ```html
-<div @data="{ count: 0 }">
-  <button @click="count++">Increment</button>
-  <p @text="count"></p>
+<main @helium @data="{ count: 100 }">
+  <section @data="{ count: 0, open: false }">
+    <button @click="count++">Increment local count</button>
+    <button @click="open = !open">Toggle</button>
+    <p @text="count"></p>
+    <p @visible="open">Local content</p>
+  </section>
+
+  <p @text="count"></p> <!-- Still 100 -->
+</main>
+```
+
+The object is evaluated once in its parent context, so local defaults can use
+outer values. Nested data objects inherit outer names, and assignment updates
+the nearest data object that declares that name:
+
+```html
+<div @data="{ count: startingCount, label: 'outer' }">
+  <div @data="{ label: 'inner' }">
+    <button @click="count++">Updates the outer local count</button>
+    <span @text="label"></span> <!-- inner -->
+  </div>
 </div>
 ```
 
-**Alias:** `data-he-data`
+Declare every name that should remain local. Assigning an undeclared name writes
+to root state. The same applies to `@bind` and `@calculate` targets: declare
+their target names in local `@data` when they should be local. Inside the
+subtree, `$data` is the scoped state view. Local values are not returned from
+`helium()` and are not included in root `@local-storage` persistence.
+
+**Alias:** `data-he-data` (the legacy bare `data-he` alias is also accepted)
 
 ### @ref
 
-Creates a reference to the element that can be used in JavaScript expressions. References are prefixed with `$` when accessed.
+Creates a scoped reference to an element. The first matching element is
+available through `$name`, and every matching element is available as the
+always-array `$refs.name` in current DOM order:
 
 ```html
-<ul @ref="list"></ul>
+<section @data="{ items: [] }">
+  <ul @ref="list"></ul>
+  <div @ref="row"></div>
+  <div @ref="row"></div>
+  <button @click="console.log($list, $refs.row)">Inspect refs</button>
+</section>
 ```
 
-This element can then be accessed in other JavaScript expressions as `$list`:
+Ref lookup starts in the nearest explicit `@data` scope and falls back through
+parent scopes. A ref with the same name in a nested scope shadows the outer
+name. Lite has one root scope, so all of its refs belong to the mounted root.
+When refs are removed or reordered, singular and plural lookup follows the
+current DOM.
+
+This element can be accessed in other JavaScript expressions as `$list`:
 
 ```html
 <button @click="$list.appendChild($html('<li>New item</li>'))">Add Task</button>
@@ -266,6 +503,22 @@ A JavaScript expression that will run once when Helium initializes. Useful for s
 <div @init="console.log('Helium initialized!')"></div>
 ```
 
+If the expression returns a function, Helium calls it when the element is removed or when Helium is torn down. This is useful for releasing timers, observers, subscriptions, and other resources:
+
+```html
+<div @init="start_clock($el, $data)"></div>
+```
+
+```js
+function start_clock(element, data) {
+  const timer = setInterval(() => {
+    element.textContent = new Date().toLocaleTimeString()
+  }, 1000)
+
+  return () => clearInterval(timer)
+}
+```
+
 **Alias:** `data-he-init`
 
 ### @calculate
@@ -423,11 +676,22 @@ You can add modifiers by appending them with a dot (`.`) after the event name:
 - **once** - Only runs the event handler once, then removes the listener
 - **outside** - Only fires when the event happens outside the element
 - **document** - Attaches the listener to the document instead of the element
+- **window** - Attaches the listener to `window` instead of the element
+- **self** - Only fires when the element itself is the event target
+- **capture** - Handles the event during the capture phase
+- **passive** - Registers a native passive listener
 - **debounce** - Debounces the event handler (default 300ms)
 - **debounce:500** - Debounces with custom delay in milliseconds
+- **throttle** - Runs immediately, then at most once per interval (default 300ms)
+- **throttle:500** - Throttles with a custom interval in milliseconds
 - **shift, ctrl, alt, meta** - Only fires if the modifier key is pressed
 - **Key names** - For keyboard events, specify which key (e.g., `enter`, `esc`, `space`)
 
+Throttle uses leading and trailing calls: the first matching event runs
+immediately, and events received during the interval are coalesced into one
+final call using the latest event. `.passive.prevent` is invalid because a
+passive listener cannot cancel an event; Helium warns and does not register it.
+
 **Examples:**
 
 ```html
@@ -457,9 +721,15 @@ You can add modifiers by appending them with a dot (`.`) after the event name:
 
 <!-- Listen on document level -->
 <div @keydown.document.esc="closeModal()">Press ESC anywhere</div>
+
+<!-- Window listener with throttled updates -->
+<div @resize.window.throttle:100="measureLayout()"></div>
+
+<!-- Ignore clicks that originated in descendants -->
+<button @click.self="select()"><span>Select</span></button>
 ```
 
-**Alias:** Prepend the event name with `data-he-on`, for example `data-he-onclick="count++"`
+**Alias:** Prepend the event name with `data-he-`, for example `data-he-click="count++"`
 
 ## HTTP Requests
 
@@ -643,6 +913,44 @@ Additional fetch options (as an object):
 - `data-he-loading`
 - `data-he-options`
 
+### Server-Sent Events (optional)
+
+SSE parsing is kept out of the core build. Select the add-on entry point when a
+page needs it:
+
+```javascript
+import helium from "@daz4126/helium/sse"
+// Strict CSP: import helium from "@daz4126/helium/csp/sse"
+```
+
+Use the normal HTTP directives. An explicit `@target` is applied to every SSE
+message:
+
+```html
+<button @get="/api/events" @target="#events:append">Connect</button>
+<div id="events"></div>
+```
+
+When `@target` is omitted, an SSE `event:` field can name a CSS selector or a
+state property:
+
+```text
+event: #status
+data: Connected
+```
+
+Set `retryMode` and an optional initial `retry` delay through `@options` to
+reconnect after the stream closes or fails. A server-supplied `retry:` field
+updates the delay and `id:` is sent back as `Last-Event-ID` on reconnection.
+
+```html
+<button @get="/api/events"
+  @target="#events:append"
+  @options="{ retryMode: 'error', retry: 3000 }">
+  Connect
+</button>
+```
+
 ### Complete Example
 
 ```html
@@ -737,13 +1045,26 @@ You can also use a string:
 These special variables are available in all JavaScript expressions:
 
 ### $
-Alias for `document.querySelector` - quickly select elements:
+The `$` query helper preserves `document.querySelector` as its default and adds
+array-returning plural and scoped forms:
 
 ```html
 <div @click="$('#header').classList.add('active')">Activate Header!</div>
 <button @click="$('.sidebar').style.display = 'none'">Hide Sidebar</button>
 ```
 
+```js
+$(selector)                 // first match in document
+$.all(selector)             // all matches in document
+$.root(selector)            // first descendant match in $root
+$.root.all(selector)        // all descendant matches in $root
+$.scope(selector)           // first descendant match in $scope
+$.scope.all(selector)       // all descendant matches in $scope
+```
+
+The plural forms return normal arrays. Like `querySelector`, the root and scope
+forms search descendants and do not include `$root` or `$scope` themselves.
+
 ### $el
 Reference to the current element:
 
@@ -753,6 +1074,17 @@ Reference to the current element:
 <input @input="console.log($el.value)">
 ```
 
+### $root
+
+The actual root element owned by the current Helium instance. This is the
+element selected by `@helium`/`data-helium`, the element passed to
+`helium.mount()`, or `document.body` for the default fallback root.
+
+### $scope
+
+The nearest element that declares local `@data` state, falling back to `$root`.
+Lite has no local data scopes, so `$scope` and `$root` are always the same.
+
 ### $event
 The event object (available in event handlers):
 
@@ -762,6 +1094,21 @@ The event object (available in event handlers):
 <form @submit="$event.preventDefault(); handleSubmit()">
 ```
 
+### $dispatch
+
+Dispatch a bubbling, cancelable `CustomEvent` from the current element. The
+event is returned, so callers can inspect `defaultPrevented`:
+
+```html
+<section @cart:add="total += $event.detail.price">
+  <button @click="$dispatch('cart:add', { price: 12 })">Add</button>
+</section>
+```
+
+The signature is `$dispatch(name, detail = {}, options = {})`. Options can set
+`target` (default `$el`), `bubbles` (default `true`), and `cancelable` (default
+`true`).
+
 ### $data
 The reactive data object containing all Helium variables:
 
@@ -795,12 +1142,19 @@ HTTP request functions that can be called programmatically:
 
 The arguments are `url`,`params` (not for `$get`) and `options`. `options` is an object that can include the properties `loading`,`target`, `template`
 
-### $refs
-Object containing all elements marked with `@ref` (prefixed with `$`):
+### Named refs
+
+The first element marked with `@ref="name"` in the nearest defining scope is
+available as `$name`. `$refs.name` is an array of every matching ref in that
+scope, in current DOM order:
 
 ```html
 <input @ref="username">
 <button @click="console.log($username.value)">Log Username</button>
+
+<div @ref="item"></div>
+<div @ref="item"></div>
+<button @click="console.log($refs.item.length)">Log item count</button>
 ```
 
 ## Functions
@@ -899,6 +1253,29 @@ This is the recommended approach when you need to update variables:
 
 ## Advanced Features
 
+### Batched Updates
+
+State changes are batched: a burst of synchronous mutations triggers a single
+DOM update on the next microtask, and each affected binding runs once no matter
+how many mutations fed it. This keeps loops over state cheap — updating 100
+items in a keyed list re-renders the list once, not 100 times:
+
+```javascript
+// One DOM update, not 100
+for (let i = 0; i < 100; i++) state.items[i].done = true;
+```
+
+Two practical consequences:
+
+- **Reading the DOM right after a mutation shows the old value.** Await a
+  microtask first: `state.count = 5; await Promise.resolve();` (in tests, a
+  `setTimeout(0)` tick also covers content inserted by `@if`/`@for`, which is
+  processed asynchronously by the MutationObserver).
+- **Assigning a value that is already current is a no-op** — it doesn't
+  re-trigger bindings, so effects that write unchanged state settle instead of
+  looping. A binding cascade that *never* stops writing new values (e.g.
+  `@effect:*="count++"`) is detected and reported after 100 passes.
+
 ### DOM Morphing with Idiomorph
 
 By default, when you update innerHTML with `@html`, Helium replaces the entire content. This can cause issues like losing focus, resetting scroll positions, or interrupting animations.
@@ -1004,7 +1381,11 @@ The token is automatically included in POST, PUT, PATCH, and DELETE requests to
 
 ### Content Security Policy
 
-If you're using a Content Security Policy, note that Helium uses `new Function()` to evaluate expressions. You'll need to allow `unsafe-eval` or use a build step to pre-compile expressions (coming in a future version).
+The standard and lite builds use `new Function()` and therefore require `unsafe-eval`. For a strict Content Security Policy, use the CSP build instead:
+
+```js
+import helium from "@daz4126/helium/csp"
+```
 
 ## Best Practices
 
@@ -1037,6 +1418,18 @@ If you're using a Content Security Policy, note that Helium uses `new Function()
 <div @effect:page="analytics.track('page_view', { page })"></div>
 ```
 
+**Benchmarking:**
+
+The repo includes a head-to-head runtime benchmark against Alpine.js, React,
+and Datastar (keyed list create/update/swap/clear plus rapid counter updates,
+run in real Chromium; Datastar only runs the counter test since it renders
+lists server-side). Run it with:
+
+```bash
+npm run bench                    # defaults: 1000 rows, 7 runs
+node scripts/benchmark.mjs --rows 5000 --runs 5
+```
+
 ### Structuring Larger Apps
 
 **Organize state at the root:**
@@ -1093,22 +1486,19 @@ If you're using a Content Security Policy, note that Helium uses `new Function()
 
 ### Common Pitfalls
 
-**❌ Don't mutate arrays/objects without triggering reactivity:**
+**Arrays and objects are reactive:**
 
-```javascript
-helium({
-  addItem(items, item) {
-    items.push(item); // ❌ Won't trigger updates
-  }
-})
+```html
+<button @click="items.push(newItem)">Add item</button>
+<span @text="items.length"></span>
 ```
 
-**✅ Pass $data and update through it:**
+Nested mutations made through `$data` are reactive too:
 
 ```javascript
 helium({
   addItem(data, item) {
-    data.items.push(item); // ✅ Triggers updates
+    data.items.push(item); // Triggers updates
   }
 })
 ```
@@ -1141,58 +1531,15 @@ helium({
 <button @click="goodFunction($data)">Works!</button>
 ```
 
-## Security Considerations
-
-### XSS Protection
-
-**Always sanitize user input when using @html:**
-
-```html
-<!-- ❌ Dangerous if userInput contains scripts -->
-<div @html="userInput"></div>
-
-<!-- ✅ Sanitize first -->
-<div @html="sanitize(userInput)"></div>
-```
-
-Consider using a sanitization library like [DOMPurify](https://github.com/cure53/DOMPurify):
-
-```javascript
-import DOMPurify from 'dompurify';
-
-helium({
-  sanitize(html) {
-    return DOMPurify.sanitize(html);
-  }
-});
-```
-
-**Use @text for plain text:**
-
-```html
-<!-- ✅ Safe - automatically escapes HTML -->
-<div @text="userInput"></div>
-```
-
-### CSRF Protection
-
-Helium automatically includes CSRF tokens in same-origin requests. Add this meta tag to your HTML:
-
-```html
-<meta name="csrf-token" content="your-csrf-token">
-```
-
-All POST, PUT, PATCH, and DELETE requests will include the `X-CSRF-Token` header automatically.
-
-### Content Security Policy
-
-If you're using a strict CSP, you may need to allow `'unsafe-eval'` since Helium uses `new Function()` to compile expressions, or use a hash/nonce for the script.
-
 ## Error Handling
 
 ### JavaScript Expression Errors
 
-If an expression throws an error, Helium catches it silently and continues. Check the browser console for error messages.
+If a binding expression throws at runtime, Helium logs the error and continues
+without updating that binding. Failed compilation keeps Helium's literal-string
+ergonomics: plain text such as `@text="Loading..."` stays quiet, while
+expression-looking failures such as `@text="user.name."` or
+`@click="count +"` emit a `console.warn` with the attribute and expression.
 
 ```html
 <!-- If items is undefined, this won't crash the page -->
@@ -1201,13 +1548,12 @@ If an expression throws an error, Helium catches it silently and continues. Chec
 
 ### HTTP Request Errors
 
-Failed requests log errors to the console. Handle them in your expressions:
+HTTP directives log failed requests to the console. Programmatic helpers return
+promises, so you can handle failures explicitly:
 
 ```html
-<button 
-  @post="/api/save"
-  @params="{ data: formData }"
-  @target="#message">
+<button @click="$post('/api/save', { data: formData }, '#message')
+  .catch(error => saveError = error.message)">
   Save
 </button>
 
@@ -1216,8 +1562,50 @@ Failed requests log errors to the console. Handle them in your expressions:
 
 ### Invalid Attribute Syntax
 
-Helium gracefully handles invalid syntax. If an expression can't be compiled, it treats it as a literal value.
-
+Helium keeps plain malformed value expressions as literal values. If a failed
+expression looks like broken JavaScript, Helium emits a warning with directive
+context. Event handlers, HTTP options, `@data`, `@for`, `@if`, `@calculate`,
+`@effect`, and `@init` are treated strictly and warn on compile failure.
+
+
+## Roadmap & Known Limitations
+
+Helium aims to stay tiny, so some conveniences found in larger frameworks are
+intentionally absent (or still on the roadmap). Current gaps:
+
+### Not yet supported
+
+- **No `$watch`/`$nextTick`, and no cross-root shared store** — each mounted
+  instance has its own isolated state namespace.
+- **No transition helper** — use CSS transitions/classes directly with
+  `@hidden`, `@visible`, or `@if`.
+
+### Roadmap
+
+Ordered by recommended implementation sequence:
+
+1. **Document function and `this` context limitations** alongside the existing
+   magic-variable guidance, with correct patterns for passing `$data`, `$el`,
+   and other context explicitly.
+2. **Add opt-in required-CSRF validation for POST/PUT/PATCH** — fail before the
+   request when an application declares that a token is mandatory, without
+   breaking tokenless APIs and cross-origin requests.
+3. **Add request cancellation and explicit success/error hooks** using
+   `AbortController`; define the request lifecycle before expanding loading and
+   error-state APIs.
+4. **Document a form-validation pattern first**, using native constraint
+   validation and Helium state; add helpers only if examples reveal recurring
+   boilerplate.
+5. **Create a complete error-state example** covering validation, HTTP failure,
+   retry, accessible messaging, and clearing stale errors.
+6. **Complete HTTP loading-state lifecycle behavior** — `@loading` already
+   exists, so define consistent success, error, cancellation, and restoration
+   behavior rather than adding a second loading mechanism.
+7. **Add debounced two-way binding updates if needed** after reproducing a real
+    feedback/caret loop; event-handler debouncing already covers ordinary input
+    throttling.
+8. **Add a minimal watch/middleware system** together with a clear size budget;
+    avoid adopting Alpine-scale surface area without demonstrated use cases.
 
 ## Contributing
 
@@ -1227,6 +1615,18 @@ Helium is open source! Contributions, issues, and feature requests are welcome.
 - Report issues: Create an issue on GitHub
 - Suggest features: Open a discussion on GitHub
 
+Before submitting a change, run `npm run check`. It executes the full jsdom test
+suite, creates the production bundles, smoke-tests them, and fails if any gzip
+size budget is exceeded. `npm run test:browser` runs the Chromium smoke suite
+used by CI for CSP, Turbo, SSE, keyed focus preservation, late imports, Lite
+generation, and browser entry imports. `npm run check:ci` runs both paths.
+`npm run size` also reports raw, gzip, and Brotli sizes.
+
+`helium.js` contains the shared runtime plus sections marked Standard-only.
+`npm run generate` derives `helium-lite.js`; do not edit the generated Lite file
+directly. Standard keeps keyed lists, HTTP, imports, and Turbo, while SSE remains
+an optional module.
+
 ## License
 
 MIT License - feel free to use Helium in personal and commercial projects.