[route]

Redesigns the JavaScript evaluation API around named arguments. It lands in one go without breaking anyone's scripts: old-style calls keep their old behavior and warn, and FERRUM_JS_API=new runs the new behavior ahead of time.

Release	Old-style scripts
0.20 (this PR)	run as before and warn; FERRUM_JS_API=new runs them the new way
0.21	new way only: Runtime::Legacy, evaluate_async, evaluate_func and evaluate_on removed, no switch back

The old code lives unchanged, apart from warnings, in Frame::Runtime::Legacy, and the new pipeline is separate. So 0.21 deletes legacy.rb and utils/deprecate.rb. The switch is an environment variable rather than a browser option, so it's clearly temporary and removing it breaks no code.

The new API

page.evaluate("a + b", a: 1, b: 2)                              # named arguments become parameters
page.evaluate("function(a, b) { return a - b }", b: 1, a: 3)    # a declaration is used as-is, bound by name
page.evaluate("await fetch(url).then(r => r.status)", url: "/") # await works, timeout: bounds it
list = page.evaluate_handle("document.querySelectorAll('li')") # => Ferrum::RemoteObject
node.execute("this.value = text", text: "hi")                   # Node#execute, Node#evaluate_handle

• Positional arguments keep working in every release, arguments[0] and up, but can't be mixed with named ones in the new way.
• Promises are awaited. timeout: (seconds, the page timeout by default, 0 for no limit) is enforced in Ruby by waiting on the CDP response, so pages that replace Promise or mock timers can't break it. It raises Ferrum::ScriptTimeoutError, now a Ferrum::TimeoutError.
• Scripts are read by a small scanner, Frame::Script, that skips strings, template literals, regular expressions and comments.

Adapting your code

1. Upgrade to 0.20 and run your suite. Each warning names the line in your code (the first caller outside installed gems, so Capybara users see their execute_script call), the script, and a rewrite. Each warning prints once per call site.
2. Fix what it reports. The table below covers every case. Rewritten calls already take the new path in 0.20, so you can fix them one at a time.
3. Run your suite with FERRUM_JS_API=new. Warnings only cover the scripts and results your suite runs into, and 0.21 has no switch back, so this is the real check. FERRUM_DEPRECATION_WARNINGS=raise turns warnings into errors.
4. Upgrade to 0.21.

Most code needs nothing: plain expressions and positional arguments, page.evaluate("document.title") or page.evaluate("arguments[0] + 1", 1), behave the same in every release.

Your code	0.20	0.21	Rewrite
evaluate("arguments[0].foo", foo: 1), keywords read through arguments	one object in arguments[0]	foo is a parameter	evaluate("options.foo", options: { foo: 1 }), or evaluate("foo", foo: 1)
evaluate("a", 1, b: 2), positional mixed with keywords	keywords appended as an object	ArgumentError	evaluate("…", 1, { b: 2 }), or name every argument
evaluate("a(); b"), several statements	returns a(), skips the rest	SyntaxError	evaluate("function() { a(); return b }")
evaluate("\n window.x = 1\n"), a line break before the script	never runs, nil	runs	check it's safe to run, or remove it
evaluate("fetch(url)"), returns a promise	{}, not awaited	awaited, raises if rejected	prefix with void to not wait
returns an object with a then method	the object	awaited like a promise	wrap it, ({ value: object })
node.evaluate("this.parentNode"), a node, nodes or a Date	{}	Ferrum::Node, or the date's ISO 8601 string	check the code using the result
evaluate_async(expr, wait, *args)	warns	removed	evaluate("await …", timeout: wait)
evaluate_func(fn, *args, on: node)	warns	removed	evaluate(fn, a: 1), or node.evaluate(fn)
evaluate_on(node:, expression:)	warns	removed	node.evaluate(expression)

evaluate_async callbacks become await:

# before
page.evaluate_async(%(navigator.serviceWorker.register("/sw.js").then(arguments[0])), 5)
# after
page.evaluate(%(await navigator.serviceWorker.register("/sw.js")), timeout: 5)

Besides being simpler, a rejected promise now raises its real error right away, where evaluate_async timed out because nothing called the callback.

Libraries built on Ferrum should pass named arguments or a function declaration, which run the new way in both 0.20 and 0.21.

How old-style calls are detected

A call takes the new path, even in legacy mode, if it uses something only the new API has: named arguments, a function declaration, await, timeout:, or a new method. So Ferrum's own calls behave the same in both modes. Anything else runs the code from main unchanged, and is checked for what the new way does differently:

Detected	How
Keywords read through arguments, or mixed with positional arguments	the arguments given
Several statements	Runtime.compileScript, which parses without running, cached per script
A line break before the script	scanner
A promise or thenable	result subtype; for evaluate an own then function in the serialized result, otherwise Runtime.getProperties
Nodes and dates from Node#evaluate	result subtype, or Runtime.getProperties for arrays

The script runs once, and detection never runs code on its result, so getters and proxy traps don't fire. For evaluate the thenable check reads the serialized result, so it adds no CDP call.

Verified

Legacy mode runs main's code, deep serialization (#677) and thrown-value handling (#675) included, and main's runtime specs still pass against it. spec/frame/runtime/legacy_spec.rb pins those results and warnings, and spec/frame/runtime_spec.rb covers FERRUM_JS_API=new.

Replaces #617, #659, #660 and #661.