Iterable / iterator support and generic type parameter propagation

Adds first-class handling for the TS iterability protocol and bare
generic type parameters in method signatures, so APIs like
`SyncKvStorage.put<T>(key: string, value: T)` and
`SyncKvStorage.list<T>(): Iterable<[string, T]>` round-trip into
typed wasm-bindgen externs without erasing the generics.

## Iterators

`Iterator<T>` and `IterableIterator<T>` map directly to
`js_sys::Iterator<T>`; `AsyncIterator<T>` and
`AsyncIterableIterator<T>` map to `js_sys::AsyncIterator<T>`. These
are added as new IR variants (`TypeRef::Iterator` and
`TypeRef::AsyncIterator`) and emit through the existing generic
container machinery alongside `Promise<T>`.

## Iterable wrapper synthesis

`Iterable<T>` describes the protocol — an object exposing
`[Symbol.iterator](): Iterator<T>` — distinct from `Iterator<T>`
itself. To preserve that at the binding layer, top-level
`Iterable<T>` returns now synthesize a wrapper extern type with a
single `[Symbol.iterator]()` method:

```ts
interface SyncKvStorage {
  list<T>(): Iterable<[string, T]>;
}
```

becomes:

```rust
pub type SyncKvStorageList<T: ::wasm_bindgen::JsGeneric>;
#[wasm_bindgen(method, js_name = "Symbol.iterator")]
pub fn iterator<T: ::wasm_bindgen::JsGeneric>(
    this: &SyncKvStorageList<T>,
) -> Iterator<ArrayTuple<(JsString, T)>>;

#[wasm_bindgen(method)]
pub fn list<T: ::wasm_bindgen::JsGeneric>(this: &SyncKvStorage) -> SyncKvStorageList<T>;
```

The wrapper's name follows the existing `<Parent><Member>`
convention with dedup, mirroring anonymous-interface parameter
synthesis. `AsyncIterable<T>` synthesizes the analogous wrapper
keyed on `Symbol.asyncIterator`. Nested occurrences inside unions
or arrays are not synthesized — they erase to `JsValue`, matching
the existing parameter-synthesis limitation.

## Generic type parameter propagation

Bare TS generics on methods now survive codegen as
`<T: ::wasm_bindgen::JsGeneric>` declarations rather than being
erased to `JsValue`. Implementation:

* New `TypeRef::TypeParam(String)` IR variant for in-scope generic
  type parameter references.
* `convert_ts_type_scoped` returns `TypeParam(name)` instead of
  `Any` for names in the method's type-parameter scope.
* `convert_formal_params_with_synthesis` now threads scope through
  to parameter type conversion (previously called `convert_ts_type`,
  which ignored scope).
* Method codegen collects every `TypeParam` reachable from the
  signature and emits a generic decl bounded by
  `::wasm_bindgen::JsGeneric`. Synthesized iterable wrappers
  propagate any `TypeParam` from their item type onto the wrapper
  type itself, so `SyncKvStorageList` is `SyncKvStorageList<T>`.
* `pub type X<T, …>` declarations carry their generics so type
  aliases that mention generic parameters compile.

## External non-generic type protection

`GenericInstantiation` codegen now consults the codegen context's
recorded type-parameter arity per local type. References like
`ReadableStream<Uint8Array>` whose target accepts zero generics
(non-generic web-sys / external types) drop the args and emit the
bare base type, preventing `E0107`.

## Symbol-keyed methods

Symbol JS names like `Symbol.iterator` previously snake_cased to
`symboliterator`. `base_rust_name` now strips the `Symbol.`
prefix when computing the Rust name, so the synthesized iterator
methods read as `iterator` / `async_iterator` while `js_name`
keeps the full `Symbol.iterator` for wasm-bindgen.

## Header comment

Generated files now begin with `// Generated by ts-gen. Do not
edit.` (prepended after rustfmt — `quote!` doesn't preserve line
comments through token streams).

## Tests

* New `tests/fixtures/iterables.d.ts` exercises every iterability
  variant plus generic propagation through `put<T>` / `get<T>`.
* New `tests/snapshots/iterables.rs` blesses the expected output.
* Four unit tests in `parse::members::tests` cover happy path
  (sync), async, non-iterable rejection, and dedup.
* Existing snapshots updated: workers-types now produces typed
  `Iterator<...>`, `AsyncIterator<...>`, and per-method generics
  on `put` / `get` style methods that previously aliased `T` to
  `JsValue`.

## CONVENTIONS

Two new sections (slotted next to `Promise<T>` since all three
share the generic-container shape):

* `Iterator<T>` / `IterableIterator<T>` map to `js_sys::Iterator<T>`
* `Iterable<T>` returns synthesize a wrapper with `[Symbol.iterator]()`

`AGENTS.md` updated to clarify that CONVENTIONS sections are not
numbered and are ordered from simplest to most obscure.

Author: guybedford

AGENTS.md

@@ -58,7 +58,11 @@ complex (subtyping LUB across unions).
 
 **When to update `CONVENTIONS.md`:**
 
-* Adding a new TS construct → add a numbered section.
+* Adding a new TS construct → add a section. Sections are not
+  numbered; order them from simplest (primitives) to most obscure
+  (subtyping LUB across unions). Slot the new heading where it
+  naturally falls in that progression — usually next to a related
+  convention of similar complexity.
 * Changing an existing translation rule → update its section.
 * Bug fix that changes user-visible output → update if the fix changes
   the documented behaviour, otherwise just add a snapshot test.

CONVENTIONS.md

@@ -689,6 +689,76 @@ pub async fn fetch(url: &str) -> Result<Response, JsValue>;
 * `wasm-bindgen` rewraps the `T` as `Promise<T>` on the JS side.
 * Constructors and setters never become async.
 
+## `Iterator<T>` / `IterableIterator<T>` map to `js_sys::Iterator<T>`
+
+```ts
+interface FormData {
+  entries(): IterableIterator<[string, FormDataEntryValue]>;
+}
+```
+
+emits:
+
+```rust
+#[wasm_bindgen(method)]
+pub fn entries(this: &FormData) -> Iterator<ArrayTuple<(JsString, JsValue)>>;
+```
+
+`Iterator<T>` and `IterableIterator<T>` describe runtime objects that
+*are* iterators (have `.next()`), so they map directly to
+`js_sys::Iterator<T>` with the inner type erased the same way
+`Promise<T>` is — generic `T` parameters become `JsValue` unless they
+resolve to a concrete named type at generation time.
+
+`AsyncIterator<T>` and `AsyncIterableIterator<T>` map to
+`js_sys::AsyncIterator<T>` analogously; wasm-bindgen models the two
+iterator families separately.
+
+## `Iterable<T>` returns synthesize a wrapper with `[Symbol.iterator]()`
+
+```ts
+interface SyncKvStorage {
+  list<T = unknown>(): Iterable<[string, T]>;
+}
+```
+
+emits:
+
+```rust
+#[wasm_bindgen(extends = Object)]
+pub type SyncKvStorageList;
+#[wasm_bindgen(method, js_name = "Symbol.iterator")]
+pub fn iterator(this: &SyncKvStorageList) -> Iterator<ArrayTuple<(JsString, JsValue)>>;
+
+// And on the original interface:
+#[wasm_bindgen(method)]
+pub fn list(this: &SyncKvStorage) -> SyncKvStorageList;
+```
+
+`Iterable<T>` describes the *protocol* — an object that exposes
+`[Symbol.iterator](): Iterator<T>` — distinct from `Iterator<T>` (the
+iterator object itself). To preserve that distinction at the binding
+layer, ts-gen synthesizes a wrapper interface per top-level
+`Iterable<T>` return:
+
+* The wrapper's name is `<Parent><Method>` PascalCased, deduped
+  against existing names (same convention as anonymous-interface
+  parameter synthesis).
+* The wrapper has a single method `iterator()` keyed on `Symbol.iterator`
+  via `js_name = "Symbol.iterator"`, returning the inner `Iterator<T>`.
+* The original method's return type is rewritten to the wrapper's name.
+
+`AsyncIterable<T>` synthesizes the analogous wrapper using
+`Symbol.asyncIterator` and `AsyncIterator<T>` for the inner iterator.
+
+Nested occurrences (inside unions, arrays, etc.) are not synthesized —
+they erase to `JsValue` at codegen, matching the existing
+parameter-synthesis limitation. Hoist the type manually if a wrapper is
+needed in those positions.
+
+Symbol-keyed methods drop the `Symbol.` prefix when computing the Rust
+name: `Symbol.iterator` becomes `iterator`, not `symboliterator`.
+
 ## `@throws` JSDoc → typed error
 
 ```ts

src/codegen/classes.rs

@@ -55,6 +55,10 @@ struct ClassConfig<'a> {
     is_abstract: bool,
     /// Members to generate.
     members: Vec<Member>,
+    /// Type parameters declared on the type itself (rendered as
+    /// `<T: JsGeneric, …>` on the `pub type` decl and propagated to
+    /// every `this: &Type<T, …>` reference inside the extern block).
+    type_params: Vec<crate::ir::TypeParam>,
     /// Codegen context for type resolution.
     cgctx: Option<&'a CodegenContext<'a>>,
     /// Scope for type reference resolution.
@@ -85,6 +89,7 @@ impl<'a> ClassConfig<'a> {
             js_namespace: None,
             is_abstract: decl.is_abstract,
             members: decl.members.clone(),
+            type_params: decl.type_params.clone(),
             cgctx,
             scope,
         }
@@ -117,11 +122,41 @@ impl<'a> ClassConfig<'a> {
             js_namespace: None,
             is_abstract: false,
             members: decl.members.clone(),
+            type_params: decl.type_params.clone(),
             cgctx,
             scope,
         }
     }
 
+    /// Tokens for the type-level generic declaration (`<T: JsGeneric, …>`)
+    /// or empty when the type has no parameters.
+    fn type_generics_decl(&self) -> TokenStream {
+        if self.type_params.is_empty() {
+            return quote! {};
+        }
+        let idents = self
+            .type_params
+            .iter()
+            .map(|tp| super::typemap::make_ident(&tp.name))
+            .collect::<Vec<_>>();
+        quote! { <#(#idents: ::wasm_bindgen::JsGeneric),*> }
+    }
+
+    /// Tokens for the type's generic-argument list (`<T, …>`) used in
+    /// `this: &Type<T, …>` references inside the extern block. Empty
+    /// when there are no parameters.
+    fn type_generics_args(&self) -> TokenStream {
+        if self.type_params.is_empty() {
+            return quote! {};
+        }
+        let idents = self
+            .type_params
+            .iter()
+            .map(|tp| super::typemap::make_ident(&tp.name))
+            .collect::<Vec<_>>();
+        quote! { <#(#idents),*> }
+    }
+
     /// Rust name to use everywhere the class identifier appears in generated
     /// code (`pub type X`, `this: &X`, `static_method_of = X`, …).
     ///
@@ -976,10 +1011,12 @@ fn generate_type_decl(config: &ClassConfig) -> TokenStream {
         quote! { #[wasm_bindgen(#(#wb_parts),*)] }
     };
 
+    let generics_decl = config.type_generics_decl();
+
     quote! {
         #wb_attr
         #[derive(Debug, Clone, PartialEq, Eq)]
-        pub type #rust_ident;
+        pub type #rust_ident #generics_decl;
     }
 }
 
@@ -1069,13 +1106,47 @@ fn generate_expanded_method(config: &ClassConfig, sig: &FunctionSignature) -> To
         quote! {}
     };
 
+    // wasm-bindgen requires every type parameter mentioned in a method
+    // signature to be redeclared on the method, even when the same name
+    // is already on the parent type — see `js_sys::Array::for_each<T:
+    // JsGeneric>` for the canonical pattern.
+    let method_generics = generic_params_for_method(config, sig);
+    let this_generics = config.type_generics_args();
+
     quote! {
         #doc
         #[wasm_bindgen(#(#wb_parts),*)]
-        pub #async_kw fn #rust_ident(this: &#this_type, #params) #ret;
+        pub #async_kw fn #rust_ident #method_generics (this: &#this_type #this_generics, #params) #ret;
     }
 }
 
+/// Generic declaration for a method, covering both type-level parameters
+/// referenced in `this: &Foo<T, …>` and any method-only parameters
+/// mentioned in arguments or the return type. wasm-bindgen requires the
+/// redeclaration even for type-level params.
+fn generic_params_for_method(config: &ClassConfig, sig: &FunctionSignature) -> TokenStream {
+    // Type-level params come first, in declaration order, so that
+    // `<T: JsGeneric, U: JsGeneric>` aligns with the type's parameter
+    // list when `this: &Foo<T, U>` is referenced.
+    let mut names: Vec<String> = config
+        .type_params
+        .iter()
+        .map(|tp| tp.name.clone())
+        .collect();
+    for p in &sig.params {
+        super::signatures::collect_type_params(&p.type_ref, &mut names);
+    }
+    super::signatures::collect_type_params(&sig.return_type, &mut names);
+    if names.is_empty() {
+        return quote! {};
+    }
+    let idents = names
+        .iter()
+        .map(|n| super::typemap::make_ident(n))
+        .collect::<Vec<_>>();
+    quote! { <#(#idents: ::wasm_bindgen::JsGeneric),*> }
+}
+
 /// Generate a static method binding from an expanded signature.
 fn generate_expanded_static_method(config: &ClassConfig, sig: &FunctionSignature) -> TokenStream {
     let rust_ident = super::typemap::make_ident(&sig.rust_name);
@@ -1121,10 +1192,12 @@ fn generate_expanded_static_method(config: &ClassConfig, sig: &FunctionSignature
         quote! {}
     };
 
+    let generics = generic_params_for_method(config, sig);
+
     quote! {
         #doc
         #[wasm_bindgen(#(#wb_parts),*)]
-        pub #async_kw fn #rust_ident(#params) #ret;
+        pub #async_kw fn #rust_ident #generics (#params) #ret;
     }
 }
 

src/codegen/mod.rs

@@ -71,7 +71,12 @@ pub fn generate_with_options(
     syn::parse2::<syn::File>(tokens.clone()).map_err(|e| {
         anyhow::anyhow!("generated tokens are not valid syn:\n{e}\n\nTokens:\n{tokens}")
     })?;
-    rustfmt(&tokens.to_string())
+    let formatted = rustfmt(&tokens.to_string())?;
+    // Prepend a header comment. Line comments don't survive `quote!` token
+    // generation, so they have to be emitted as plain text after formatting.
+    Ok(format!(
+        "// Generated by ts-gen. Do not edit.\n\n{formatted}"
+    ))
 }
 
 /// Format Rust source via `rustfmt`.
@@ -120,8 +125,6 @@ fn generate_tokens(
     let cgctx = CodegenContext::from_module(module, gctx);
 
     let preamble = quote! {
-        // Auto-generated by ts-gen. Do not edit.
-
         #[allow(unused_imports)]
         use wasm_bindgen::prelude::*;
         #[allow(unused_imports)]
@@ -300,9 +303,25 @@ fn generate_type_alias(
         return quote! {};
     }
 
+    // Type-parameter declaration so aliases that mention generics survive
+    // codegen: `type EmailExportedHandler<Env, Props> = …;` rather than the
+    // bare `EmailExportedHandler =` that would leave `Props` undeclared.
+    let generics = if alias.type_params.is_empty() {
+        quote! {}
+    } else {
+        let idents = alias
+            .type_params
+            .iter()
+            .map(|tp| typemap::make_ident(&tp.name))
+            .collect::<Vec<_>>();
+        // Type aliases use plain `<T, U>` without trait bounds; aliases
+        // are erased during monomorphisation by their use sites.
+        quote! { <#(#idents),*> }
+    };
+
     quote! {
         #[allow(dead_code)]
-        pub type #name = #target;
+        pub type #name #generics = #target;
     }
 }