fix: hydrate strict event arguments in repeat scopes (#322)

Author: mohamedmansour

DESIGN.md

@@ -1235,10 +1235,10 @@ Each component's compiled template is registered in `window.__webui.templates[ta
 | `cl`  | `SlotPath[]`                      | Conditional anchor slots aligned to `c[]`          |
 | `r`   | `[collection, itemVar, blockIndex][]` | Repeat blocks                                  |
 | `rl`  | `SlotPath[]`                      | Repeat anchor slots aligned to `r[]`               |
-| `e`   | `[event, handler, argSpecs, targetPath][]` | Body events                              |
+| `e`   | `[event, handler, argSpecs, targetPath][]` | Body events                              |
 | `b`   | `TemplateBlockMeta[]`             | Nested compiled block table referenced by `c` / `r` |
 | `sa`  | `string`                          | Optional module-mode adopted stylesheet specifier copied from `shadowrootadoptedstylesheets` |
-| `re`  | `[event, handler, argSpecs][]`    | Root events, attached to the host element          |
+| `re`  | `[event, handler, argSpecs][]`    | Root events, attached to the host element          |
 
 All arrays are optional — omitted from the output when empty to minimize payload.
 
@@ -1270,15 +1270,15 @@ Logical operators also match the protocol enum values:
 - `[name, 2, ConditionExpr]` — boolean attribute binding, e.g. `?disabled="{{expr}}"`
 - `[name, 3, parts]` — mixed/template attribute binding, e.g. `class="item {{state}}"`
 
-`argSpecs` for event handlers are resolved at dispatch time against the captured scope chain for the rendered template block:
-
-- `["e"]` passes the DOM event object
-- `["p", path]` resolves a component or active `<for>` scope path, e.g. `item.id`
-- `["s", value]`, `["n", value]`, `["b", 0|1]`, and `["z"]` pass string, number, boolean, and `null` literals
-
-For example, `@click="{selectItem(item.id)}"` calls `selectItem` with the current repeat item id, while `@click="{selectItem(item.id, e)}"` passes the item id followed by the event object. `@click="{selectItem(e)}"` keeps the existing event-passing behavior, and `@click="{selectItem()}"` calls the handler with no arguments.
-
-### Compilation rules
+`argSpecs` for event handlers are resolved at dispatch time against the captured scope chain for the rendered template block:
+
+- `["e"]` passes the DOM event object
+- `["p", path]` resolves a component or active `<for>` scope path, e.g. `item.id`
+- `["s", value]`, `["n", value]`, `["b", 0|1]`, and `["z"]` pass string, number, boolean, and `null` literals
+
+For example, `@click="{selectItem(item.id)}"` calls `selectItem` with the current repeat item id, while `@click="{selectItem(item.id, e)}"` passes the item id followed by the event object. `@click="{selectItem(e)}"` keeps the existing event-passing behavior, and `@click="{selectItem()}"` calls the handler with no arguments.
+
+### Compilation rules
 
 The Rust compiler (`generate_compiled_template` in `webui-parser/src/plugin/webui.rs`) transforms the HTML template in a single forward pass, then finalizes it into marker-free client HTML plus locator metadata:
 
@@ -1291,7 +1291,7 @@ The Rust compiler (`generate_compiled_template` in `webui-parser/src/plugin/webu
 | `:config="{{settings}}"`, `:value="{{searchQuery}}"` | `a[]` + `ag[]` | element kept marker-free |
 | `<if condition="expr">body</if>`     | `c[]` + `cl[]` + `b[]` | block removed; anchor slot stored |
 | `<for each="v in coll">body</for>`   | `r[]` + `rl[]` + `b[]` | block removed; anchor slot stored |
-| `@event="{handler(item.id, e)}"`     | `e[]`                  | element kept marker-free          |
+| `@event="{handler(item.id, e)}"`     | `e[]`                  | element kept marker-free          |
 | `@event` on `<template>` wrapper     | `re[N]`                | *(stripped)*                      |
 | `w-ref="name"`                       | *(stays)*              | *(unchanged)*                     |
 | `<outlet />`                         | *(stays)*              | `<outlet></outlet>`               |
@@ -1333,13 +1333,15 @@ WebUI SSR marker formats are:
 
 The WebUI handler plugin emits only these five comment markers. Text bindings, attribute bindings, and event handlers are resolved from compiled metadata path indices at hydration time - no DOM attribute markers are needed. The handler only emits markers in active child scopes; the root page scope remains marker-free. During hydration the framework keeps `<!--wr-->` and `<!--wc-->` as runtime anchors and removes `<!--/wr-->`, `<!--/wc-->`, and `<!--wi-->` markers.
 
+WebUI Framework hydration assumes the SSR DOM, hydration markers, and compiled metadata were generated by the same trusted WebUI compiler/handler version. Hand-authored or partially modified marker streams are unsupported; missing structural closing markers are invalid input, not a recoverable runtime condition.
+
 ### Runtime contract
 
 `@microsoft/webui-framework` consumes the metadata object above plus the SSR markers emitted by `WebUIHydrationPlugin`. This follows an Islands Architecture approach: the server delivers fully-rendered HTML, and only interactive Web Components hydrate on the client — leaving static content untouched.
 
 - SSR hydration uses one DOM walk to discover `<!--wr-->`, `<!--wi-->`, and `<!--wc-->` comment markers, wire the relevant bindings using compiled metadata path indices, then remove SSR-only markers.
-- Client-created DOM never reparses template syntax; it clones marker-free `h` and resolves `tx`, `ag`, `cl`, `rl`, and `el` locators directly.
-- Events are resolved from compiled `e[]` metadata entries using path indices. The runtime installs listeners on target elements and resolves handler arguments against the scope captured when that block was rendered. Root events from `re[]` attach directly to the host element.
+- Client-created DOM never reparses template syntax; it clones marker-free `h` and resolves `tx`, `ag`, `cl`, `rl`, and event target paths directly.
+- Events are resolved from compiled `e[]` metadata entries using path indices. The runtime installs listeners on target elements and resolves handler arguments against the scope captured when that block was rendered. Root events from `re[]` attach directly to the host element.
 - The full package entrypoint supports repeat metadata (`r[]` / `rl[]`). The additive `@microsoft/webui-framework/element-no-repeat` entrypoint preserves the same public `WebUIElement` API but must reject compiled templates that contain repeat metadata.
 
 Detailed component examples, decorators, and package entrypoint guidance live in [packages/webui-framework/README.md](packages/webui-framework/README.md) rather than being duplicated in this design spec.

crates/webui-parser/src/plugin/webui.rs

@@ -10,7 +10,7 @@
 //! a single `<script>` tag; during SPA navigation the router evaluates
 //! them directly. Each metadata object contains
 //! **marker-free static HTML** plus locator arrays for client-created DOM
-//! (`tx`, `ag`, `cl`, `rl`, `el`) and semantic arrays (`a`, `c`, `r`, `e`,
+//! (`tx`, `ag`, `cl`, `rl`) and semantic arrays (`a`, `c`, `r`, `e`,
 //! `re`, `b`). The client runtime resolves those locators once and then
 //! patches direct node references — **no template string parsing, no regex,
 //! no DOM scanning** on the client-created path.
@@ -25,11 +25,10 @@
 //!   ag: [[[0], 0, 1]],
 //!   c: [[[1, "state", 3, "'done'"], 0]],
 //!   cl: [[[0], 1]],
-//!   e: [["click", "onClick", 0]],
-//!   el: [[0]],
+//!   e: [["click", "onClick", [], [0]]],
 //!   b: [{ h: "<span class=\"check\">✓</span>" }],
 //!   sa: "my-component",
-//!   re: [["submit", "onSubmit", 1]],
+//!   re: [["submit", "onSubmit", [["e"]]]],
 //! };
 //! ```
 //!
@@ -337,7 +336,7 @@ enum CompiledAttrPart {
 /// | `<for each="v in coll">body</for>`    | `r[]` + `rl[]` + `b[]`     | block removed; anchor slot stored |
 /// | `<link>` / `<style>` child nodes      | `h`                        | preserved in static HTML          |
 /// | module adopted stylesheet specifier   | `sa`                       | stored from `<template>` wrapper  |
-/// | `@event="{handler(e)}"`               | `e[]` + `el[]`             | element kept marker-free          |
+/// | `@event="{handler(e)}"`               | `e[]`                      | element kept marker-free          |
 /// | `w-ref="name"` / `w-ref={name}`       | *(stays in HTML)*          | *(unchanged)*                     |
 /// | `<outlet />` / `<outlet>`             | *(stays in HTML)*          | `<outlet></outlet>`               |
 pub fn generate_compiled_template(tag_name: &str, html_content: &str) -> String {
@@ -2016,41 +2015,54 @@ fn parse_event_handler(raw_value: &str) -> EventHandler {
                 Some(close) if close > paren => close,
                 _ => return EventHandler::Invalid(inner.to_string()),
             };
+            if !inner[close + 1..].trim().is_empty() {
+                return EventHandler::Invalid(inner.to_string());
+            }
             let handler_name = inner[..paren].trim();
-            if handler_name.is_empty() {
+            if !is_valid_identifier(handler_name) {
                 return EventHandler::Invalid(inner.to_string());
             }
-            EventHandler::Valid(
-                handler_name.to_string(),
-                parse_event_args(&inner[paren + 1..close]),
-            )
+            let Some(args) = parse_event_args(&inner[paren + 1..close]) else {
+                return EventHandler::Invalid(inner.to_string());
+            };
+            EventHandler::Valid(handler_name.to_string(), args)
         }
         None => EventHandler::Invalid(inner.to_string()),
     }
 }
 
-fn parse_event_args(raw_args: &str) -> Vec<EventArg> {
-    split_event_args(raw_args)
-        .into_iter()
-        .filter_map(|arg| parse_event_arg(arg.trim()))
-        .collect()
+fn parse_event_args(raw_args: &str) -> Option<Vec<EventArg>> {
+    if raw_args.trim().is_empty() {
+        return Some(Vec::new());
+    }
+
+    let raw_parts = split_event_args(raw_args)?;
+    let mut args = Vec::with_capacity(raw_parts.len());
+    for arg in raw_parts {
+        let trimmed = arg.trim();
+        if trimmed.is_empty() {
+            return None;
+        }
+        args.push(parse_event_arg(trimmed)?);
+    }
+    Some(args)
 }
 
-fn split_event_args(raw_args: &str) -> Vec<&str> {
+fn split_event_args(raw_args: &str) -> Option<Vec<&str>> {
     let mut args = Vec::new();
     let mut start = 0usize;
     let mut quote: Option<u8> = None;
     let mut escaped = false;
     for (idx, byte) in raw_args.bytes().enumerate() {
-        if escaped {
-            escaped = false;
-            continue;
-        }
-        if byte == b'\\' {
-            escaped = true;
-            continue;
-        }
         if let Some(q) = quote {
+            if escaped {
+                escaped = false;
+                continue;
+            }
+            if byte == b'\\' {
+                escaped = true;
+                continue;
+            }
             if byte == q {
                 quote = None;
             }
@@ -2065,8 +2077,11 @@ fn split_event_args(raw_args: &str) -> Vec<&str> {
             start = idx + 1;
         }
     }
+    if quote.is_some() || escaped {
+        return None;
+    }
     args.push(&raw_args[start..]);
-    args
+    Some(args)
 }
 
 fn parse_event_arg(arg: &str) -> Option<EventArg> {
@@ -2088,10 +2103,13 @@ fn parse_event_arg(arg: &str) -> Option<EventArg> {
     if let Some(value) = parse_quoted_event_string(arg) {
         return Some(EventArg::String(value));
     }
+    if is_quoted_event_arg_start(arg) {
+        return None;
+    }
     if is_number_literal(arg) {
         return Some(EventArg::Number(arg.to_string()));
     }
-    Some(EventArg::Path(arg.to_string()))
+    is_valid_event_path(arg).then(|| EventArg::Path(arg.to_string()))
 }
 
 fn parse_quoted_event_string(arg: &str) -> Option<String> {
@@ -2118,6 +2136,49 @@ fn is_number_literal(arg: &str) -> bool {
             .all(|b| b.is_ascii_digit() || matches!(b, b'.' | b'-' | b'+' | b'e' | b'E'))
 }
 
+fn is_quoted_event_arg_start(arg: &str) -> bool {
+    matches!(arg.as_bytes().first(), Some(b'"' | b'\''))
+}
+
+fn is_valid_event_path(path: &str) -> bool {
+    let mut parts = path.split('.');
+    let Some(first) = parts.next() else {
+        return false;
+    };
+    if !is_valid_identifier(first) {
+        return false;
+    }
+    for part in parts {
+        if part.is_empty() || (!is_valid_identifier(part) && !is_ascii_digits(part)) {
+            return false;
+        }
+    }
+    true
+}
+
+fn is_valid_identifier(value: &str) -> bool {
+    let mut bytes = value.bytes();
+    let Some(first) = bytes.next() else {
+        return false;
+    };
+    if !is_identifier_start(first) {
+        return false;
+    }
+    bytes.all(is_identifier_continue)
+}
+
+fn is_identifier_start(byte: u8) -> bool {
+    byte.is_ascii_alphabetic() || byte == b'_' || byte == b'$'
+}
+
+fn is_identifier_continue(byte: u8) -> bool {
+    is_identifier_start(byte) || byte.is_ascii_digit()
+}
+
+fn is_ascii_digits(value: &str) -> bool {
+    !value.is_empty() && value.bytes().all(|byte| byte.is_ascii_digit())
+}
+
 fn extract_single_handlebars(value: &str) -> Option<String> {
     let trimmed = value.trim();
     if let Some(inner) = trimmed
@@ -2483,7 +2544,7 @@ mod tests {
         );
         assert_no_client_markers(&result);
         assert!(result.contains(r#"h:"<p>hi</p>""#));
-        assert!(result.contains(r#",re:[["click","onClick",0]]"#));
+        assert!(result.contains(r#",re:[["click","onClick",[]]]"#));
     }
 
     #[test]
@@ -2612,7 +2673,9 @@ mod tests {
             .unwrap();
         let templates = plugin.take_component_templates();
         assert_eq!(templates.len(), 1);
-        assert!(templates[0].1.contains(r#",re:[["click","onClick",1]]"#));
+        assert!(templates[0]
+            .1
+            .contains(r#",re:[["click","onClick",[["e"]]]]"#));
     }
 
     #[test]
@@ -3079,6 +3142,58 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn test_parse_event_handler_rejects_trailing_tokens() {
+        assert!(matches!(
+            parse_event_handler("{onClick(e)} trailing"),
+            EventHandler::Invalid(ref raw) if raw == "{onClick(e)} trailing"
+        ));
+        assert!(matches!(
+            parse_event_handler("{onClick(e) trailing}"),
+            EventHandler::Invalid(ref raw) if raw == "onClick(e) trailing"
+        ));
+    }
+
+    #[test]
+    fn test_parse_event_handler_rejects_empty_args() {
+        assert!(matches!(
+            parse_event_handler("{onClick(, e)}"),
+            EventHandler::Invalid(ref raw) if raw == "onClick(, e)"
+        ));
+        assert!(matches!(
+            parse_event_handler("{onClick(e,)}"),
+            EventHandler::Invalid(ref raw) if raw == "onClick(e,)"
+        ));
+    }
+
+    #[test]
+    fn test_parse_event_handler_rejects_malformed_args() {
+        assert!(matches!(
+            parse_event_handler("{onClick('unterminated)}"),
+            EventHandler::Invalid(ref raw) if raw == "onClick('unterminated)"
+        ));
+        assert!(matches!(
+            parse_event_handler("{onClick(other())}"),
+            EventHandler::Invalid(ref raw) if raw == "onClick(other())"
+        ));
+        assert!(matches!(
+            parse_event_handler("{onClick(count + 1)}"),
+            EventHandler::Invalid(ref raw) if raw == "onClick(count + 1)"
+        ));
+    }
+
+    #[test]
+    fn test_parse_event_handler_rejects_invalid_handler_name() {
+        assert!(matches!(
+            parse_event_handler("{handler.name()}"),
+            EventHandler::Invalid(ref raw) if raw == "handler.name()"
+        ));
+        assert!(matches!(
+            parse_event_handler("{1handler()}"),
+            EventHandler::Invalid(ref raw) if raw == "1handler()"
+        ));
+    }
+
     #[test]
     fn test_parse_event_handler_empty_value() {
         assert!(matches!(parse_event_handler("{}"), EventHandler::Empty));

docs/ai.md

@@ -187,9 +187,14 @@ Supported operators: `==`, `!=`, `>`, `<`, `>=`, `<=`, `&&`, `||`, `!`
 ```html
 <button @click="{handleClick()}">Click me</button>
 <input @keydown="{onKeydown(e)}" />
+<button @click="{selectItem(item.id, 'details', e)}">Select</button>
 <div @mouseenter="{onHover()}" @mouseleave="{onLeave()}">Hover</div>
 ```
 
+Event handler arguments can be `e`, dotted component or repeat-scope paths,
+string/number/boolean/null literals, or a mix of those. Nested JavaScript
+expressions are not parsed in templates.
+
 ### DOM references
 
 ```html
@@ -766,17 +771,9 @@ togglePanel(): void { this.isPanelOpen = !this.isPanelOpen; }
 </for>
 ```
 
-Note: `remove(item.id)` does not work as written because template event
-handlers cannot pass arguments from loop scope. Instead, use a child
-component that emits a custom event:
-
-```html
-<for each="item in items">
-  <list-item id="{{item.id}}" text="{{item.text}}"
-    @remove-item="{onRemove(e)}">
-  </list-item>
-</for>
-```
+`remove(item.id)` receives the current loop item's id. The framework captures
+the active repeat scope during hydration and resolves the path when the click
+event fires.
 
 ### Boolean attribute styling
 

docs/guide/concepts/how-it-works.md

@@ -81,7 +81,7 @@ After the browser renders the server HTML, JavaScript loads and Web Components *
 1. **Custom elements upgrade** - the browser calls `connectedCallback` for each registered Web Component
 2. **Shadow root detection** - the framework finds the existing Declarative Shadow DOM root (it does **not** recreate the DOM)
 3. **Bindings wired** - template expressions (`{{count}}`, `?disabled`) are connected to class properties
-4. **Events connected** - `@click`, `@keydown`, and other event handlers are attached
+4. **Events connected** - `@click`, `@keydown`, and other handlers are attached with their compiled argument scopes
 5. **Reactive state activated** - `@observable` properties become live; changes trigger targeted DOM updates
 
 ### Islands Architecture