[guybedford]

TS number lowers to f64, but most numbers a platform API carries are integers with a known width (Response.status is a u16, a list limit a u32), and upstream declaration files cannot carry annotations.

• @rust <type> on a property or callable forces the member's own type; @rust <param>: <type> one named parameter. The scalar replaces the leaf through ? / | null, T[] and Promise<…>, wasm-bindgen converting at the boundary; a scalar slice parameter (ports: &[u16]) crosses as a JS array (slice = "array"), like the number[] it types. u64/i64 apply to a bigint leaf (lifted for number in Inline wrappers: @rust u64/i64 on a number, literal-keyed overloads; @throws {never} on constructors #68). A tag is chosen over a branded type u16 = number alias since upstream never uses one and an alias suggests a TS-level distinction that does not exist.
• --annotate <side.d.ts> layers @rust and @throws tags onto the input by declaration and member name; the side file is not emitted; a side name the input lacks, an invalid tag, or a tag the type cannot carry fails the run.
• A side declaration's type-parameter defaults replace the input's. An alias instantiated at its defaults takes the side's (RequestInfo → &Request<JsValue, Incoming> in the fixture); on an interface or class they take effect once the type declaration carries its defaults (Type-level generics usable by their bare names #63), so the bare Request can read cf() as IncomingRequestCfProperties instead of upstream's erased CfProperties<…> union.

Unit tests cover every --annotate error path. workers-types snapshot unchanged (annotations are supplied by the consumer).

[wasm-bindgen-bot]

This PR adds @rust <scalar> JSDoc tags, which narrow a number/bigint leaf to a Rust integer or float type, and a --annotate flag that layers @rust/@throws tags (and type-parameter defaults) from a side .d.ts onto the input by name. It looks aimed at better @cloudflare/workers-types bindings: u16 statuses, an incoming cf. It chooses a tag over a branded type u16 = number alias and a side file over editing the vendored input, and the error reporting for unmatched names is thorough. The main problem: a tagged leaf inside a generic handle (Promise<number> outside an async return, number[][], (number | null)[]) lowers to a bare u32 inside Promise<…>/Array<…>/JsNullable<…>, which needs a JsGeneric type, so the generated code won't compile. There are also two smaller gaps: an alias in the side file whose name the input lacks is skipped silently, and the snapshot doesn't show the documented effect of a side default on a bare Request.

Not merge-ready:

• @rust on a leaf inside a generic handle (Promise<number> getter or argument, number[][], (number | null)[]) emits a non-JsGeneric u32, so the output doesn't compile.
• An alias in the side file whose name the input lacks is silently skipped instead of failing the run.
• The documented side-default effect on a bare Request isn't reflected in the snapshot output.

[wasm-bindgen-bot]

Since my last review the PR was rebased onto #63, and new commits fix all three earlier concerns; their threads are already resolved. A tagged leaf inside a generic handle now stays Number/BigInt, and integration tests cover it. A side alias whose name is missing or ambiguous now fails the run. Only the ## Errors section of a side doc is carried over. One problem is new: since the rebase, the snapshot gives the emitted Request Rust defaults (Cf = Incoming) and fetch takes a bare &Request, but CONVENTIONS and the fixture comment still say the opposite.

Not merge-ready:

• CONVENTIONS.md (the type-parameter defaults paragraph) and the annotate.d.ts fixture comment say a bare Request is unchanged and fetch takes &Request<JsValue, Incoming>. Since the rebase, the snapshot shows Request<…, Cf = Incoming> with Rust defaults and fetch(input: &Request).