@daz4126/helium 1.0.0-rc.2 → 1.0.0-rc.4

package/README.md

@@ -18,7 +18,7 @@ It's really simple to use - just sprinkle the magic @attributes into your HTML a
 
 Helium is designed for developers who want:
 
-- **Lightweight** - About 3.9–10.9KB minified and gzipped, depending on the build
+- **Lightweight** - About 6.2–14.2KB 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
@@ -31,7 +31,7 @@ Helium comes in three core versions, with SSE available as an optional add-on, s
 
 The full-featured version with everything included.
 
-- All directives (`@text`, `@html`, `@for`, `@bind`, `@data`, `@scope`, `@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`)
@@ -51,7 +51,7 @@ A slimmed-down version with just the core reactivity features.
 - Core directives (`@text`, `@html`, `@bind`, `@data`, `@ref`, `@calculate`, `@effect`, `@init`)
 - Event handlers with modifiers
 - One global state namespace
-- No `@scope`, keyed `@for`, HTTP requests, imports, SSE, or Turbo integration
+- 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.
 
@@ -104,23 +104,25 @@ import helium from "@daz4126/helium/csp"
 | Feature | Standard | Lite | CSP |
 |---------|----------|------|-----|
 | Core directives | ✅ | ✅ | ✅ |
-| Element-local `@scope` | ✅ | ❌ | ✅ |
+| Element-local `@data` | ✅ | ❌ | ✅ |
 | Keyed `@for` | ✅ | ❌ | ✅ |
+| Conditional `@if` | ✅ | ❌ | ✅ |
 | Event handlers | ✅ | ✅ | ✅ |
 | HTTP requests | ✅ | ❌ | ✅ |
 | `@import` | ✅ | ❌ | ✅ |
 | SSE | Add-on | ❌ | Add-on |
 | Turbo integration | ✅ | ❌ | ✅ |
 | CSP safe | ❌ | ❌ | ✅ |
-| Approx. min+gzip size | 6.49KB | 3.93KB | 10.56KB |
+| Approx. min+gzip size | 9.62KB | 6.18KB | 13.75KB |
 
 Sizes are enforced against the production Terser builds with gzip level 9. The
-CSP figure includes its expression parser. Adding SSE produces 6.86KB Standard
-and 10.94KB CSP bundles.
+CSP figure includes its expression parser. Adding SSE produces 10.00KB Standard
+and 14.12KB 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, but
-intentionally excludes element-local scopes and Standard's other extensions.
+identical deep/shared reactivity, lifecycle, binding, and cleanup behavior for
+root state, but intentionally excludes element-local data and Standard's other
+extensions.
 
 ## Installation
 
@@ -300,6 +302,32 @@ but keyed `@for` avoids HTML-string interpolation and lets each row use normal
 
 **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:
@@ -389,31 +417,23 @@ 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>
-```
-
-You can then use these variables in other Helium attributes:
-
-```html
-<div @data="{ count: 0 }">
-  <button @click="count++">Increment</button>
-  <p @text="count"></p>
-</div>
+<main @helium @data="{ count: 100, name: 'Helium' }">
+  <p @text="name + ': ' + count"></p>
+</main>
 ```
 
-**Alias:** `data-he-data`
-
-### @scope (Standard/CSP)
-
-Creates reactive state owned by an element and its descendants. Scoped names
-shadow root state without changing the object returned by `helium()`:
+Nested `@data` is local in Standard/CSP:
 
 ```html
-<main @data="{ count: 100 }">
-  <section @scope="{ count: 0, open: false }">
+<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>
@@ -424,41 +444,49 @@ shadow root state without changing the object returned by `helium()`:
 </main>
 ```
 
-The scope expression runs once in its parent context, so defaults can use outer
-values. Nested scopes inherit outer names, and assignment updates the nearest
-scope that declares that name:
+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 @scope="{ count: startingCount, label: 'outer' }">
-  <div @scope="{ label: 'inner' }">
+<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>
 ```
 
-Declare every name that should remain local. Assigning an undeclared name keeps
-the existing Helium behavior and writes to root state. The same applies to
-`@bind` and `@calculate` targets: declare their target names in `@scope` when
-they should be local. Inside the subtree, `$data` is the scoped state view.
-Local values are not included in root `@local-storage` persistence.
-
-`@data` continues to merge into root state; it has not changed semantics.
+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-scope`
-
-`@scope` is intentionally excluded from Lite, which always uses one global
-state namespace per mounted root.
+**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>
@@ -648,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
@@ -682,6 +721,12 @@ 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-`, for example `data-he-click="count++"`
@@ -1000,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:
 
@@ -1016,15 +1074,41 @@ 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):
 
 ```html
 <div @click="console.log($event.timeStamp)">Log the timestamp</div>
 <input @keydown="$event.key === 'Enter' && submit()">
-<form @submit="$event.preventDefault(); handleSubmit()">
+<form @submit.prevent="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:
 
@@ -1060,14 +1144,49 @@ The arguments are `url`,`params` (not for `$get`) and `options`. `options` is an
 
 ### Named refs
 
-Each element marked with `@ref="name"` is available as `$name`. There is no
-separate `$refs` object:
+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>
+```
+
+## Expression Contract
+
+Directive values are **single expressions**, in both Standard and CSP. Common
+expressions include property reads, assignments, function calls, object and
+array literals, ternaries, logical operators, and arrow functions:
+
+```html
+<button @click="open = !open">Toggle</button>
+<button @click="save($data, $el)">Save</button>
+<p @text="loading ? 'Loading…' : message"></p>
 ```
 
+Top-level statement lists, declarations, and control-flow statements are not
+directive syntax. Prefer event modifiers and move multi-step behavior into a
+named function:
+
+```html
+<!-- Not supported: two top-level statements -->
+<form @submit="$event.preventDefault(); save()"></form>
+
+<!-- Preferred -->
+<form @submit.prevent="save($data)"></form>
+```
+
+The Standard build uses the JavaScript expression grammar. The CSP build uses
+its restricted expression parser and additionally excludes `new` and some
+JavaScript expression forms; see the CSP build notes above. Functions declared inside
+an `@data` object or imported from a module are ordinary JavaScript functions
+and may contain statements internally.
+
 ## Functions
 
 Functions can be imported using `@import` or defined using the `@data` attribute.
@@ -1164,6 +1283,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.
@@ -1206,7 +1348,28 @@ Without keys, the entire list is re-rendered. With keys, only changed items are
 
 ### MutationObserver
 
-Helium automatically observes the DOM and processes new elements as they're added. This means Helium works seamlessly with:
+Helium automatically observes the DOM, processes new elements as they're added,
+and reconciles Helium directives when attributes on retained elements change.
+Adding, replacing, or removing an event, binding, ref, effect, initializer, or
+structural directive installs the new behavior and tears down the old behavior
+without rebuilding unrelated parts of the subtree.
+
+For programmatic changes, use the `data-he-*` aliases: DOM `setAttribute()`
+rejects names such as `@click` in some browsers and DOM implementations even
+though the HTML parser accepts them.
+
+```js
+button.setAttribute("data-he-click", "save()")
+button.setAttribute("data-he-click", "archive()") // replaces save
+button.removeAttribute("data-he-click")            // removes the listener
+```
+
+Changing local `data-he-data` recreates that local scope and re-tracks its
+descendant bindings. HTTP option attributes such as `data-he-target` are read
+when the request runs, so their current values are used automatically. Root
+selection and `@local-storage` remain mount-time configuration.
+
+This means Helium works seamlessly with:
 
 - Dynamically inserted content
 - Content loaded via AJAX
@@ -1306,6 +1469,18 @@ import helium from "@daz4126/helium/csp"
 <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:**
@@ -1411,7 +1586,11 @@ helium({
 
 ### JavaScript Expression Errors
 
-If a binding expression throws at runtime, Helium logs the error and continues without updating that binding. Standard and lite retain malformed expressions as literal text for compatibility; quote intentional string constants, for example `@text="'Ready'"`.
+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 -->
@@ -1434,8 +1613,10 @@ promises, so you can handle failures explicitly:
 
 ### Invalid Attribute Syntax
 
-Standard and Lite retain expressions that cannot be compiled as literal values.
-The CSP build logs the parser error and leaves the binding undefined.
+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
@@ -1445,43 +1626,106 @@ intentionally absent (or still on the roadmap). Current gaps:
 
 ### Not yet supported
 
-- **No DOM-removing `@if`** — only `@hidden`/`@visible`, which toggle visibility
-  but keep elements in the DOM.
 - **No `$watch`/`$nextTick`, and no cross-root shared store** — each mounted
   instance has its own isolated state namespace.
-
-### Roadmap
-
-Ordered by recommended implementation sequence:
-
-1. **Improve expression-compilation diagnostics** — emit a useful `console.warn`
-   containing the expression and build/engine context instead of silently
-   treating every compile failure as a literal value.
-2. **Add real-browser CI** covering CSP, Turbo, SSE, focus preservation, late
-   imports, generated Lite output, and package exports before adding more DOM
-   lifecycle behavior.
-3. **Document function and `this` context limitations** alongside the existing
-   magic-variable guidance, with correct patterns for passing `$data`, `$el`,
-   and other context explicitly.
-4. **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.
-5. **Add request cancellation and explicit success/error hooks** using
-   `AbortController`; define the request lifecycle before expanding loading and
-   error-state APIs.
-6. **Document a form-validation pattern first**, using native constraint
-   validation and Helium state; add helpers only if examples reveal recurring
-   boilerplate.
-7. **Create a complete error-state example** covering validation, HTTP failure,
-   retry, accessible messaging, and clearing stale errors.
-8. **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.
-9. **Add debounced two-way binding updates if needed** after reproducing a real
-    feedback/caret loop; event-handler debouncing already covers ordinary input
-    throttling.
-10. **Add a minimal watch/middleware system** together with a clear size budget;
-    avoid adopting Alpine-scale surface area without demonstrated use cases.
+- **No transition helper** — use CSS transitions/classes directly with
+  `@hidden`, `@visible`, or `@if`.
+
+### Stimulus-parity roadmap
+
+The goal is not to copy Stimulus's controller syntax. Simple behavior should
+remain local (`@click="open = !open"`, `@bind="name"`); the roadmap supplies the
+lifecycle and JavaScript escape hatches needed when behavior becomes complex.
+
+#### P0 — 1.0 release foundations
+
+- [x] **Define the expression and function-context contract.** Directive values
+  are expressions; multi-step work belongs in named functions with `$data`,
+  `$el`, refs, and other required context passed explicitly.
+- [x] **Reconcile directive attributes on retained elements.** Attribute add,
+  replace, and removal now install and tear down bindings, events, refs,
+  initializers, local data, and structural directives independently.
+- [x] **Run the production browser suite in Chromium, Firefox, and WebKit.** Keep
+  the same CSP, Turbo, SSE, keyed identity, dynamic-directive, late-import,
+  Lite, and entry-point checks in every engine.
+
+#### P1 — complex-behavior escape hatches
+
+1. **Formalize lifecycle modules over `@init`.** Document the existing
+   `@import` + `@init` setup-function convention: imported setup receives its
+   required element, state, refs, and dispatch context explicitly and returns
+   cleanup. Keep ordinary behavior inline and move only complex imperative work
+   into a lifecycle module.
+
+   ```js
+   export function connectFeature(element, data, refs) {
+     // setup
+     return () => {
+       // cleanup
+     }
+   }
+   ```
+
+2. **Formally support and test namespaced initializers.** Allow independent
+   behaviors such as `@init:editor` and `@init:tooltip` on one element, with
+   isolated replacement and cleanup when either attribute changes.
+
+   ```html
+   <div
+     @init:editor="connectEditor($el, $data, $refs)"
+     @init:tooltip="connectTooltip($el)"
+   ></div>
+   ```
+
+3. **Add unified lifecycle error handling.** Route initializer setup, async
+   rejection, cleanup, binding, event, import, and request failures through an
+   instance-level `handleError(error, context)` hook and optional debug mode.
+4. **Add an initializer-scoped `AbortSignal`.** Give each initializer a signal
+   that aborts when its attribute is replaced, removed, its element disconnects,
+   or its Helium root unmounts, so listeners and pending external work can use
+   native cancellation.
+5. **Support asynchronous setup and cleanup safely.** Recognize setup promises,
+   avoid registering stale results after disconnection or replacement, run a
+   cleanup returned asynchronously, and report rejected setup/cleanup through
+   the lifecycle error hook.
+6. **Add programmatic `watch()`.** Let imported setup functions observe reactive
+   state without exporting update functions or storing external instances in a
+   module-level `WeakMap`; include current/previous values and lifecycle-bound
+   cleanup. Keep middleware separate and lower priority.
+7. **Publish TypeScript declarations** for mounting, factories, expression
+   engines, CSP globals, SSE, lifecycle errors, initializer context, signals,
+   and watching.
+
+#### P2 — lifecycle depth and application maturity
+
+8. **Observe ref collections** so complex behaviors can react when matching
+   refs connect, disconnect, or reorder; this covers Stimulus target callbacks
+   without changing simple `$ref`/`$refs` usage.
+9. **Complete the HTTP lifecycle:** request cancellation with `AbortController`,
+   explicit success/error hooks, consistent `@loading` restoration, and opt-in
+   required-CSRF validation for state-changing same-origin requests.
+10. **Evaluate behavior lookup only after lifecycle modules are established.**
+    Prefer `$dispatch` for loose coordination; add outlet-like instance lookup
+    only if real applications require direct behavior-to-behavior calls.
+
+#### P3 — evidence-driven conveniences
+
+11. **Document complete validation and error-state patterns** covering native
+   constraint validation, HTTP failure, retry, accessible messages, and stale
+   error clearing before adding validation helpers.
+12. **Consider extensible event modifiers and structured action parameters.**
+   Expressions already cover most cases, so add APIs only for repeated needs.
+13. **Revisit `@use`, debounced binding, middleware, transitions, and a shared
+    store** only with concrete use cases and explicit size budgets. Event
+    debouncing, CSS transitions, custom events, and independent roots cover the
+    common forms today. Add `@use` only if lifecycle modules reveal a need for
+    behavior registration, private instances, or package interoperability
+    beyond namespaced `@init`.
+
+This ordering moves the former HTTP/form-heavy roadmap behind lifecycle,
+diagnostics, watching, and types. The HTTP, CSRF, loading, validation, and error
+example work remains planned, but it does not by itself close the most important
+Stimulus-parity gaps.
 
 ## Contributing
 
@@ -1491,9 +1735,12 @@ 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 test
-suite, creates the production bundles, and fails if any gzip size budget is
-exceeded. `npm run size` also reports raw, gzip, and Brotli sizes.
+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 cross-browser 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