[Win32] Fix BrowserFunction missing on first page

[HeikoKlare]

Fixes #3370 — the sporadic failure of test_BrowserFunction_availableOnLoad_concurrentInstances_issue20 on the Edge/WebView2 backend.

Builds on top of #3478 (BrowserFunction dispose/redefine regression tests) and employs the regression tests added there — #3478 should be merged first.

Problem

A BrowserFunction created while an Edge browser is still initializing (with a navigation queued via setUrl/setText) could be missing on the first loaded page. AddScriptToExecuteOnDocumentCreated was issued only after the queued navigation and raced with document creation, so the function was sometimes not registered when the page's document was created — surfacing as SWTException: <function> is not defined.

Fix

Register the document-created scripts of all pending BrowserFunctions inside WebViewProvider.initializeWebView(), before completing the initialization future (which synchronously runs the queued navigation). This is the only point that is reliably "after init, before the first navigation", since the CompletableFuture navigation chain cannot be preempted retroactively.

Registration is now issued asynchronously: what makes a function land on a page is issuing the registration before the navigation is issued to WebView2, not waiting for its completion. This also removes the previous inCallback > 0 deferral (an async call cannot deadlock inside a WebView2 callback) and the separate synchronous registration method, leaving a single registration method and a single branch in createFunction. deregisterFunction stays correct for a registration whose script ID has not arrived yet (its async completion detects the removed function and removes the script itself).

Tests

Adds regression tests for function creation during concurrent initialization: creating a function from inside a callback, availability before the first page's inline scripts run, and multiple functions registered before initialization completes. These complement the dispose/redefine regression tests from #3478.

Reproducer

The underlying race is a sub-millisecond window and cannot be forced deterministically through the public API with a single browser. The following standalone reproducer makes it deterministic in practice by stressing concurrent initialization: before the fix it reports options is not defined within a few iterations; after the fix it completes all iterations cleanly.

Standalone reproducer (Windows/Edge)

/*******************************************************************************
 * Copyright (c) 2026 Contributors to the Eclipse Foundation.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *******************************************************************************/
package org.eclipse.swt.tests.junit;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.atomic.AtomicReference;

import org.eclipse.swt.SWT;
import org.eclipse.swt.SWTException;
import org.eclipse.swt.browser.Browser;
import org.eclipse.swt.browser.BrowserFunction;
import org.eclipse.swt.browser.ProgressAdapter;
import org.eclipse.swt.browser.ProgressEvent;
import org.eclipse.swt.layout.FillLayout;
import org.eclipse.swt.widgets.Display;
import org.eclipse.swt.widgets.Shell;

/**
 * Standalone reproducer for the Edge/WebView2 BrowserFunction registration race fixed by this change.
 *
 * <p>A {@link BrowserFunction} created while a {@link Browser} is still initializing (and while a
 * navigation queued via {@code setUrl}/{@code setText} is pending) must be available on the first
 * loaded page. Before the fix, {@code AddScriptToExecuteOnDocumentCreated} was issued <em>after</em>
 * the navigation, so it raced with document creation and the function was sometimes undefined,
 * producing {@code SWTException: options is not defined}.
 *
 * <p>The underlying race is a sub-millisecond timing window, so it cannot be forced deterministically
 * through the public SWT API with a single browser. This reproducer makes it <em>deterministic in
 * practice</em> by stressing the exact scenario: it creates several browsers that initialize
 * concurrently (their initialization pumps the shared event loop and perturbs each other's timing),
 * repeated over many iterations. Before the fix it reports failures within the first few iterations;
 * after the fix it completes all iterations with zero failures.
 *
 * <p>Run it standalone via {@link #main(String[])} on Windows (Edge backend), or call
 * {@link #reproduce(Display, int, int)} from a test.
 */
public final class BrowserFunctionConcurrentInitReproducer {

	private BrowserFunctionConcurrentInitReproducer() {
	}

	/** Number of browsers initialized concurrently in a single iteration. */
	private static final int DEFAULT_BROWSERS_PER_ITERATION = 8;
	/** Number of iterations to run when stressing the scenario. */
	private static final int DEFAULT_ITERATIONS = 50;
	/** Maximum time to wait for all browsers of one iteration to resolve. */
	private static final int ITERATION_TIMEOUT_MILLIS = 30_000;

	/** Result of a single browser within an iteration. */
	private enum Result {
		PENDING, AVAILABLE, MISSING
	}

	public static void main(String[] args) {
		Display display = new Display();
		try {
			Shell shell = new Shell(display);
			shell.setLayout(new FillLayout());
			Browser probe = new Browser(shell, SWT.NONE);
			boolean isEdge = "edge".equals(probe.getBrowserType());
			probe.dispose();
			if (!isEdge) {
				System.out.println("This reproducer targets the Edge/WebView2 backend; current backend is '"
						+ probe.getBrowserType() + "'. Nothing to reproduce.");
				return;
			}

			int failures = reproduce(display, DEFAULT_ITERATIONS, DEFAULT_BROWSERS_PER_ITERATION);
			if (failures > 0) {
				System.out.println("\nREPRODUCED: 'options' was missing in " + failures
						+ " case(s). This indicates the AddScriptToExecuteOnDocumentCreated race.");
				System.exit(1);
			} else {
				System.out.println("\nNo failures observed across " + DEFAULT_ITERATIONS + " iterations of "
						+ DEFAULT_BROWSERS_PER_ITERATION + " concurrent browsers. The race appears fixed.");
			}
		} finally {
			display.dispose();
		}
	}

	/**
	 * Runs the concurrent-initialization scenario and returns the number of browsers for which the
	 * BrowserFunction was <em>not</em> available on the loaded page (i.e. reproductions of the bug).
	 *
	 * @param display            the display to run on (must be the calling thread's display)
	 * @param iterations         number of iterations to run
	 * @param browsersPerIteration number of browsers initialized concurrently per iteration
	 * @return the total number of reproductions observed
	 */
	public static int reproduce(Display display, int iterations, int browsersPerIteration) {
		int totalFailures = 0;
		for (int iteration = 0; iteration < iterations; iteration++) {
			totalFailures += runSingleIteration(display, iteration, browsersPerIteration);
			if (totalFailures > 0) {
				// Fail fast: one reproduction is enough to demonstrate the defect.
				break;
			}
		}
		return totalFailures;
	}

	private static int runSingleIteration(Display display, int iteration, int browsersPerIteration) {
		Shell shell = new Shell(display);
		shell.setLayout(new FillLayout());
		List<Browser> browsers = new ArrayList<>();
		List<Result[]> results = new ArrayList<>();
		List<AtomicReference<SWTException>> exceptions = new ArrayList<>();

		try {
			for (int i = 0; i < browsersPerIteration; i++) {
				final Result[] result = { Result.PENDING };
				final AtomicReference<SWTException> exception = new AtomicReference<>();
				results.add(result);
				exceptions.add(exception);

				// Deliberately do NOT wait for initialization: keep all browsers initializing
				// concurrently, which is the timing that exposes the race (issue #20).
				final Browser browser = new Browser(shell, SWT.NONE);
				browser.setUrl("about:blank");
				new BrowserFunction(browser, "options") {
					@Override
					public Object function(Object[] arguments) {
						return null;
					}
				};
				browser.addProgressListener(new ProgressAdapter() {
					@Override
					public void completed(ProgressEvent event) {
						try {
							browser.evaluate("options();");
							result[0] = Result.AVAILABLE;
						} catch (SWTException ex) {
							result[0] = Result.MISSING;
							exception.set(ex);
						}
					}
				});
				browsers.add(browser);
			}

			shell.open();
			waitUntilResolved(display, results);

			int failures = 0;
			for (int i = 0; i < results.size(); i++) {
				Result r = results.get(i)[0];
				if (r != Result.AVAILABLE) {
					failures++;
					SWTException ex = exceptions.get(i).get();
					System.out.println("Iteration " + iteration + ", browser " + i + ": " + r
							+ (ex != null ? " (" + ex.getMessage() + ")" : " (timed out)"));
				}
			}
			if (failures == 0) {
				System.out.println("Iteration " + iteration + ": OK (" + browsersPerIteration + " browsers)");
			}
			return failures;
		} finally {
			for (Browser browser : browsers) {
				if (!browser.isDisposed()) {
					browser.dispose();
				}
			}
			shell.dispose();
			// Let Edge process pending disposal work between iterations.
			while (display.readAndDispatch()) {
				// drain
			}
		}
	}

	private static void waitUntilResolved(Display display, List<Result[]> results) {
		long deadline = System.currentTimeMillis() + ITERATION_TIMEOUT_MILLIS;
		// Periodically wake the display so the deadline is honored even if no browser event arrives.
		Runnable[] wake = new Runnable[1];
		wake[0] = () -> {
			if (!display.isDisposed()) {
				display.timerExec(100, wake[0]);
			}
		};
		display.timerExec(100, wake[0]);
		try {
			while (System.currentTimeMillis() < deadline && !allResolved(results)) {
				if (!display.readAndDispatch()) {
					display.sleep();
				}
			}
		} finally {
			display.timerExec(-1, wake[0]);
		}
	}

	private static boolean allResolved(List<Result[]> results) {
		for (Result[] result : results) {
			if (result[0] == Result.PENDING) {
				return false;
			}
		}
		return true;
	}
}

[github-actions]

Test Results

  212 files  ± 0    212 suites  ±0   27m 28s ⏱️ -18s
4 900 tests + 6  4 874 ✅ +4   26 💤 + 2  0 ❌ ±0 
7 083 runs  +18  6 903 ✅ +6  180 💤 +12  0 ❌ ±0 

Results for commit 3e6cd35. ± Comparison against base commit 4755f49.

♻️ This comment has been updated with latest results.

[HeikoKlare]

@sratz I may have finally found the last piece for reliable browser function registration with Edge/WebView2. This PR revises the according implementation to address all registration scenarios (during browser initialization, during page navigation or when page is already loaded) in a more simple way than just extending for the not-yet-addressed scenario. Could you please have a look at this fix proposal? I have iterated the fix with an AI agent for quite some time already but would be good to have someone else with experience in this piece of code have a thorough look as well. Thank you in advance!
I do not think this is something we should still merge for 2026-09 but rather early in 2026-12 development, so that we have sufficient time for testing.

[r-mennig]

The changes look good to me. I've only found a minor issue regarding a missing return value check on AddScriptToExecuteOnDocumentCreated

[r-mennig]

Not checking the return value of AddScriptToExecuteOnDocumentCreated can lead to browser functions silently failing to register. This is made worse by the fact that those functions can be contributed from other code parts (via createFunction), so I think any registration failure should be handled here by throwing an exception.

Suggested change

	webView.AddScriptToExecuteOnDocumentCreated(stringToWstr(functionString), completion.getAddress());
	int hr = webView.AddScriptToExecuteOnDocumentCreated(stringToWstr(functionString), completion.getAddress());
	if (hr != COM.S_OK) error(SWT.ERROR_NO_HANDLES, hr);

(Maybe something other that SWT.ERROR_NO_HANDLES would be better here)

[HeikoKlare]

That's a very correct concern. Unfortunately, there are problems with either of the callers of this method when throwing an error here:

1. The one caller is the immediate function registration when creating a BrowserFunction (via new BrowserFunction()). That constructor does not have any declared errors for the case that function registration fails. Introducing a new type of exception here can lead to consumers fail unexpectedly as they do not deal with that type of exception. Thus, this would be kind of API-breaking (though not in a very strict sense).
2. The other caller is the browser initialization finalization that registers a function that was created before initialization was finished. This initialization process must not fail because of a failing browser function registration as well, such that the error would have to be caught there again and the further error processing is unclear, as the initialization finalization may be triggered by any kind of consumer performing operations on the browser.

While just swallowing a failure is obviously not a good idea (even though we have done that so far as well), throwing an error does not seem feasible here.
I found these types of errors to potentially occur here:

• E_INVALIDARG if the script is null or the completion callback is invalid (both cannot happen)
• E_POINTER if a pointer argument is null (I do not see how it could happen with this call)
• The HRESULT for ERROR_INVALID_STATE if the web view was already closed (in which case failing function registration is not an issue at all).

So I am not sure if any relevant kind of error may occur here and since we have not seen reports about issues with function registration so far, it may be really seldom (if at all) that an error occurs here. For that, we may simply log the error for the sake of traceability and debuggability without throwing any error to avoid completely unexpected or unrecoverable application states. That's what I have implemented with my latest commit.