Broiler.HtmlBridge.Scripting 0.1.0-preview.28

Broiler.HtmlBridge

An embeddable HTML control for .NET: a live DOM, a running JavaScript realm, and the host seam that lets an application drive both — the role WebView2 and mshtml.dll fill, built out of Broiler's own engines rather than someone else's browser process.

This component is the part of Broiler that turns parsed markup into a document that behaves like one. Broiler.DOM holds the tree, Broiler.CSS resolves style, Broiler.Layout does the box model and Broiler.HTML paints. HtmlBridge is what makes document.getElementById('x').style.color = 'red' reach all four and repaint — and what lets a host reach in from the other side.

It was extracted from Broiler.Browser in September 2026, with its history, because everything here is about hosting a document and nothing is about being a browser. The browser is now one embedder among the possible ones.

Status

Preview. The bridge is real and heavily exercised — 1390 passing tests and 22 skipped at Release, and 1445 passing with 22 skipped at Release-VM, which runs that suite plus the cases that only compile under it (both measured on 2026-09-24) — but the named control surface described in docs/html-control.md is not written yet. Today a host composes DomBridge, ScriptEngine and a layout view itself, which is what Broiler.Browser.Core does. That document is the plan for closing the gap, feature by feature, against what WebView2 and MSHTML actually offer.

The assemblies

External engine abstraction contracts and reference providers arrive via the Broiler.JSeal NuGet packages (Broiler.JSeal, Broiler.JSeal.BroilerJs, Broiler.JSeal.Vm).

The network arrives the same way: Broiler.HtmlBridge.Core references Broiler.Net, whose profile-owned IBrowserRequestTransport every bridge loader sends through when the host supplies one (DomBridgeSessionOptions.Network, and ScriptFetchContext for ScriptExtractionService.ExtractAll). The transport owns cookies, redirects and CORS; the bridge supplies each request's document context. Page script reaches the same transport only through gates: fetch(), XMLHttpRequest and sendBeacon carry their credentials and CORS modes, script cannot set Cookie or other forbidden headers, never reads Set-Cookie, and document.cookie is the profile's non-HTTP cookie API (DomBridgeSessionOptions.Cookies, or a store private to the bridge). Without a transport, the loaders fall back to process-wide clients that send and keep no cookies.

Every document shares one realm, so which document a script speaks for travels with it: a frame's microtasks, promise reactions, awaits, timers and module scripts run as the frame, and are dropped once the frame has navigated to another document. Origins are judged from the documents' request contexts, never from anything page script can assign: a frame of another origin (an opaque one — a sandboxed or file: frame — is same-origin with nothing but itself) is withheld from contentDocument, contentWindow and window.frames. One exception is kept from earlier releases: an unsandboxed data: frame's DOM is judged by its creator's origin (HTML makes it cross-origin), while its cookies, requests and messages keep its opaque origin. A message's source from a cross-origin frame can only be posted to, and its messages carry its real origin; a cross-origin linked sheet's cssRules throw SecurityError; document.cookie answers only a script of its document's origin; and a web document never has the bridge read a file: URL (scripts, modules, stylesheets, frames, workers).

The dependency rule that shapes all of it: a binding never names an engine. It names JSEAL, and a provider names the engine. eng/jseal-budget.json records how much engine coupling each project still has, scripts/check-engine-neutrality.sh recounts it on every push, and those numbers may fall and may never rise. See docs/jseal.md.

Building

git clone https://github.com/Broiler-Platform/Broiler.HtmlBridge.git
cd Broiler.HtmlBridge
dotnet build Broiler.HtmlBridge.slnx -c Release
dotnet test  Broiler.HtmlBridge.slnx -c Release

Four build types, and the -VM pair is not cosmetic — it changes the project graph:

Either engine can also be selected without changing configuration: dotnet build … -p:BroilerJavaScriptEngine=Vm.

External Broiler components, including both JavaScript engines, are pinned NuGet dependencies restored from nuget.org, the only package source NuGet.config lists. A fresh clone restores anonymously; no feed credentials are needed.

The solution builds all five shipping assemblies in every configuration. The -VM configurations additionally link the VM provider into the test suite and compile its engine-specific cases. This repository has no submodules: every Broiler component outside it arrives as a NuGet package, so no external component checkout is required.

Packaging

Every shipping project carries NuGet metadata and eng/pack.ps1 builds and validates every packable project in the solution — five today, the test project setting IsPackable=false — including symbols, metadata and internal dependency versions.

CI follows Broiler.JS and Broiler.VM: .NET 10 and Node.js 24, Release builds and tests on Linux and Windows, preview-version tests, and package artifacts from Windows. HtmlBridge also keeps its Linux Release-VM run, engine-neutrality guard and test-report artifacts. The coupling guard counts direct engine package references as well as project references.

Packages are published to nuget.org only. publish.yml resolves one preview version, calls CI with that version, then runs eng/verify-feed.ps1 against an isolated consumer cache before pushing the validated artifacts and their symbol packages. Every run pushes (there is no dry-run mode; CI packs and verifies a consumer restore without pushing); pushing a v* tag publishes that exact version. Every external dependency must already be on nuget.org, and publication requires the NUGET_TOKEN secret.

Preview numbers are cumulative. eng/resolve-preview-version.mjs picks one past the highest X.Y.Z-preview.N ever used, reading nuget.org and the retired GitHub Packages feed (read-only; 0.1.0-preview.1 to .5 were published there). With preview.3 on GitHub Packages and preview.2 on nuget.org, the next publish is preview.4, never a second preview.3.

Documentation

• Fingerprinting compatibility roadmap — completed Sannysoft/CreepJS compatibility scope, validation and deferred work, coordinated with Browser.
• docs/html-control.md — the control surface: what WebView2 and MSHTML offer, what this component already does, and what is missing.
• docs/jseal.md — engine neutrality, the contracts, the providers, the budget.
• docs/script-initiated-navigation.md — how a script's navigation reaches the host.

License

Apache-2.0. See LICENSE and THIRD_PARTY_NOTICES.md.