BrowsingContextOptions Class

Options of a BrowsingContext, shared by its nested browsing contexts.

public sealed class BrowsingContextOptions

Constructors

NameDescription
BrowsingContextOptions()

BrowsingContextOptions()

BrowsingContextOptions.cs
public BrowsingContextOptions()

No documentation is available.

Properties

NameDescription
AcceptCHCacheGets or sets the Accept-CH cache of the browsing contexts (https://wicg.github.io/client-hints-infrastructure/#accept-ch-cache): the client hints that the origins opted into with the Accept-CH header of the responses of the top-level navigations. The default is null: each browsing context created by the application has its own cache, shared by its auxiliary browsing contexts. A cache can be shared by several browsing contexts, and outlive them.
BackForwardCacheSizeGets or sets the maximum number of documents that a top-level browsing context keeps in its back/forward cache (https://html.spec.whatwg.org/multipage/browsing-the-web.html#note-bfcache). A document that the browsing context navigates away from is kept alive in its session history entry when it is eligible: the pagehide event is fired with persisted set to true instead of the unload event, its tasks and timers are suspended, and a traversal to the entry (e.g. history.back()) makes it the active document again, firing pageshow with persisted set to true, instead of loading it again. As in the browsers, a document is not eligible when it has unload event listeners, an open WebSocket, held web locks, or when its response is not a successful HTTP(S) response to a GET request whose Cache-Control header does not contain no-store, or when its browsing context group has other top-level browsing contexts (e.g. a popup opened without noopener). When the cache is full, the document cached first is evicted. The default is 6 (as in Chromium); 0 disables the cache.
BadgingGets or sets the host hooks of the Badging API (https://w3c.github.io/badging/, navigator.setAppBadge() and navigator.clearAppBadge()): BadgingOptions.SetBadge shows the badge of the application. The default is null: the badge is not shown anywhere, and the promises are resolved.
BatteryStatusGets or sets the host hooks of the Battery Status API (https://w3c.github.io/battery/, navigator.getBattery()): BatteryStatusOptions.Provider is the source of the battery status. The default is null: the BatteryManager reports a fully charged battery that is plugged in (as a user agent that cannot report the battery status).
BrowsingContextCreatedGets or sets the callback invoked when the library creates a browsing context that uses these options: a nested browsing context (the content navigable of an iframe, frame, object or embed element, see BrowsingContext.Parent) or an auxiliary browsing context (window.open(), a _blank target, see BrowsingContext.IsAuxiliary). It is invoked once the browsing context is attached to its parent or to its opener, with its initial about:blank document. It is not invoked for the browsing contexts created by the application. The callback is invoked on the thread of the event loop. The first argument is the context of the new browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.
BrowsingContextDestroyedGets or sets the callback invoked when a browsing context that uses these options is destroyed: a nested browsing context whose container is removed, a top-level browsing context closed by window.close() or disposed by the application (BrowsingContext.Dispose). Its documents are unloaded. The callback is invoked on the thread of the event loop. The first argument is the context of the browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.
CacheStorageGets or sets the storage of the caches of the Cache API of the browsing contexts and of their workers (caches), e.g. a database or a InMemoryCacheStorageBackend shared by several browsing contexts. The default is null: each browsing context created by the application has its own in-memory caches, shared by its auxiliary browsing contexts and their workers.
ClientHintsGets or sets the values of the client hints of the browsing contexts (https://wicg.github.io/client-hints-infrastructure/, https://wicg.github.io/ua-client-hints/): the identity of the user agent exposed by navigator.userAgentData and sent in the Sec-CH-UA-* request headers, the memory of the device and the network information. The default is null: ClientHintsOptions.Default, with ClientHintsOptions.Mobile set when the viewport is the one of a mobile device (ViewportOptions.IsMobile).
ClipboardGets or sets the system clipboard of the browsing contexts: the data copied by the copy and cut actions and by navigator.clipboard, read by the paste action and by navigator.clipboard (https://w3c.github.io/clipboard-apis/). The default is null: the browsing contexts share an in-memory clipboard, created with the first browsing context. Set it to observe or simulate what the user copies, or to use the clipboard of the operating system (see SystemClipboard).
ClipboardPermissionGets or sets the callback that decides whether a document may read or write the system clipboard (https://w3c.github.io/clipboard-apis/#permissions): navigator.clipboard and the copy, cut and paste commands of document.execCommand(). It plays the role of the permission prompt of a browser; there is no user activation, so the access never requires a user gesture. The default is null: all the documents are allowed. Deny the access to untrusted documents when BrowsingContextOptions.Clipboard is the clipboard of the operating system. The first argument is the context of the window (see CallbackContext): its CallbackContext.Window is never null, and CallbackContext.Document is the document that accesses the clipboard.
CloseNotificationGets or sets the callback that removes a notification shown by BrowsingContextOptions.ShowNotification: the script called close(), or a new notification with the same tag replaces it. It is not called when the host closes the notification itself (Notification.Dismiss). The callback is invoked on the thread of the event loop. The default is null. The first argument is the context of the global object that created the notification (see CallbackContext): its CallbackContext.Global is the window or the worker, and its CallbackContext.BrowsingContext is null for a worker.
ComputePressureGets or sets the host hooks of the Compute Pressure API (https://w3c.github.io/compute-pressure/, PressureObserver): ComputePressureOptions.Provider is the source of the pressure states of the device. The default is null: the cpu source is supported, but it reports no state (the observers are never called).
ConsoleMessageGets or sets the callback invoked when a script of a global object (a window or a worker) prints a message with the console namespace (console.log(), console.count()... https://console.spec.whatwg.org/). It plays the role of the developer console of a browser. The default is null: the messages are not formatted. The callback is invoked on the thread of the event loop of the global object: the workers run on their own threads. The first argument is the context of the global object that raised it (see CallbackContext): its CallbackContext.Global is the window, the worker or the worklet, and its CallbackContext.BrowsingContext is null for a worker or a worklet.
ContentSecurityPolicyViolationGets or sets the callback invoked when a content security policy is violated (the policies of the Content-Security-Policy and Content-Security-Policy-Report-Only headers and of the meta elements, including the Trusted Types directives), whatever the disposition of the policy: see ContentSecurityPolicyViolationReport.Disposition. It is invoked with the securitypolicyviolation event, in the task that fires it, so it plays the role of the developer console of a browser. The callback is invoked on the thread of the event loop of the global object: the workers run on their own threads. It is not invoked for a document without browsing context. The first argument is the context of the global object that raised it (see CallbackContext): its CallbackContext.Global is the window, the worker or the worklet, and its CallbackContext.BrowsingContext is null for a worker or a worklet.
CookieJarGets or sets the cookie store of the browsing contexts: the cookies of Document.Cookie and of the Cookie Store API (window.cookieStore), given to BrowsingContextOptions.DocumentLoader with each request (see DocumentRequest.GetCookieHeader and DocumentRequest.StoreCookies). The default is null: the documents have no cookies. The jar can be shared by several browsing contexts; create it with the BrowsingContextOptions.TimeProvider of the browsing contexts to measure the expiry times with their clock.
DeclarativeRefreshEnabledGets or sets whether the documents navigate when their declarative refresh comes due: the Refresh header of their response or a <meta http-equiv="refresh"> element, e.g. 5; url=next.html (https://html.spec.whatwg.org/multipage/semantics.html#shared-declarative-refresh-steps). The refresh comes due the given number of seconds after the document is completely loaded (measured by the clock of the DomEventLoop), and the navigation replaces the document. The default is true when BrowsingContextOptions.DocumentLoader is set, false otherwise (the navigation would result in an error document).
DevicePostureGets or sets the host hooks of the Device Posture API (https://w3c.github.io/device-posture/, navigator.devicePosture and the device-posture media feature): DevicePostureOptions.Provider is the source of the posture of the device. The default is null: the posture is DevicePostureType.Continuous.
DocumentActivatedGets or sets the callback invoked when a document becomes the active document of a browsing context that uses these options: the end of a navigation (a document is created, including the error document of a navigation whose response is a network error, see Document.IsNetworkErrorDocument), or a traversal of the session history that loads a document. It is not invoked for the initial about:blank document of a new browsing context. The callback is invoked on the thread of the event loop, before the document is parsed. The first argument is the context of the browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.
DocumentLoaderGets or sets the loader of the documents of the navigations (e.g. the src of an iframe, or location.href = url). Nothing is fetched by the library: when this is null, the navigations to URLs other than about:blank and about:srcdoc result in error documents.
DownloadStartedGets or sets the callback invoked when a browsing context that uses these options downloads a resource (https://html.spec.whatwg.org/multipage/links.html#downloading-resources): the response of a navigation whose Content-Disposition is attachment or whose computed MIME type is application/octet-stream (the active document stays), or the resource of a hyperlink with a download attribute, fetched by BrowsingContextOptions.DocumentLoader. The downloads of the documents sandboxed without allow-downloads are blocked. When null, the downloads are ignored: the hyperlinks with a download attribute fetch nothing, and the rest of the body of an attachment response is not read. The callback is invoked on the thread of the event loop. The first argument is the context of the browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.
EncodingDetectorGets or sets the detector of the encoding of the HTML documents of the navigations that do not declare their encoding: no byte order mark, no charset in the Content-Type header, no meta element, and no same-origin container document (https://html.spec.whatwg.org/multipage/parsing.html#determining-the-character-encoding). The default is EncodingDetector.Default, which guesses the legacy encodings from the content, and UTF-8 for the file: URLs only (as the browsers). Null disables the detection: these documents are decoded as windows-1252, as the ones whose encoding is not detected. The detector is only used for the HTML documents of the navigations: the other resources (XML documents, text files, style sheets, scripts, the responses of XMLHttpRequest and fetch(), TextDecoder) have the fallback encoding of their specification.
EnterFullscreenGets or sets the callback called when the documents of a top-level browsing context are about to be displayed fullscreen (https://fullscreen.spec.whatwg.org/#dom-element-requestfullscreen, "resize the viewport"), with the options of Element.RequestFullscreen. The host of a window makes it fullscreen and returns the size of the viewport while fullscreen (the dimensions of the screen), or null to keep the size of the viewport. The default is null: the viewport keeps its size (BrowsingContextOptions.Viewport), and the fullscreen element fills it (the :fullscreen rules of the user agent style sheet). The first argument is the context of the top-level browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.
ExitFullscreenGets or sets the callback called when the documents of a top-level browsing context are no longer displayed fullscreen (https://fullscreen.spec.whatwg.org/#exit-fullscreen): the viewport gets the size of BrowsingContextOptions.Viewport back. The default is null. The first argument is the context of the top-level browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.
ExitPointerLockGets or sets the callback called when the pointer lock of a top-level browsing context is exited (https://w3c.github.io/pointerlock/#dfn-exit-pointer-lock): the host displays its cursor again, at the position of the mouse (UserInput.Mouse). The default is null. The first argument is the context of the top-level browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.
FeaturesGets or sets the optional features of the web platform exposed to the scripts of the windows and of the workers, e.g. new WebPlatformFeatures { WebSocketEnabled = false }: the scripts see the disabled features as unsupported features, as in a browser that does not implement them. Use it to reduce what the scripts of untrusted documents can do, or to test the fallbacks of a page. The default is null: WebPlatformFeatures.Default (all the features are enabled).
FileSystemGets or sets the storage of the origin private file systems of the browsing contexts and of their workers (navigator.storage.getDirectory()), e.g. a directory, a database or a InMemoryFileSystemBackend shared by several browsing contexts. The default is null: each browsing context created by the application has its own in-memory file systems, shared by its auxiliary browsing contexts and their workers.
GeolocationGets or sets the source of the positions of the device (https://w3c.github.io/geolocation/, navigator.geolocation), e.g. a GeolocationProvider whose GeolocationProvider.Position is set by the application, or a subclass that reads the location of the operating system. The library checks the geolocation permission (see BrowsingContextOptions.Permissions and BrowsingContextOptions.RequestPermission) and the permissions policy, and handles the timeouts, the cached positions and the watches. A provider can be shared by several browsing contexts. The default is null: the position is unavailable (POSITION_UNAVAILABLE).
GlobalPrivacyControlGets or sets the preference of the user expressed by Global Privacy Control (https://w3c.github.io/gpc/): navigator.globalPrivacyControl, and the Sec-GPC: 1 header of the requests when it is enabled. The default is null: the preference is not set (navigator.globalPrivacyControl is false, and no header is sent).
IdleDetectionGets or sets the host hooks of the Idle Detection API (https://wicg.github.io/idle-detection/, IdleDetector): IdleDetectionOptions.Provider is the source of the idle state of the user and of the screen. The idle-detection permission is checked with BrowsingContextOptions.Permissions and BrowsingContextOptions.RequestPermission. The default is null: the user is active and the screen is unlocked.
IndexedDBGets or sets the storage of the IndexedDB databases of the browsing contexts and of their workers (indexedDB), e.g. a database or a InMemoryIndexedDBBackend shared by several browsing contexts. The default is null: each browsing context created by the application has its own in-memory databases, shared by its auxiliary browsing contexts and their workers.
KeyboardLockGets or sets the host hooks of the Keyboard Lock API (https://wicg.github.io/keyboard-lock/, navigator.keyboard.lock()): KeyboardLockOptions.Lock and KeyboardLockOptions.Unlock capture the keys that the system or the browser handle. The default is null: no key is captured, but the promises are resolved.
KeyboardMapGets or sets the host hooks of the Keyboard Map API (https://wicg.github.io/keyboard-map/, navigator.keyboard.getLayoutMap()): KeyboardMapOptions.Provider is the source of the keyboard layout. The default is null: the layout is US QWERTY, and it never changes.
LanguagesGets or sets the preferred languages of the user, as BCP 47 language tags, in order of preference: navigator.language and navigator.languages of the windows and of the workers, and the Accept-Language header of the requests that do not set one. The default is null: en-US and en, and the requests have no Accept-Language header (the BrowsingContextOptions.DocumentLoader may add one).
LocalStorageGets or sets the local storage areas of the browsing contexts (window.localStorage), keyed by origin. The default is null: each browsing context created by the application has its own storage shed, shared by its auxiliary browsing contexts. A shed can be shared by several browsing contexts: the storage events are fired at the windows of all of them. A shed created with a WebStoragePersistence persists the items.
MediaAutoplayPolicyGets or sets whether the media elements are allowed to play without a user gesture (https://html.spec.whatwg.org/multipage/media.html#allowed-to-play): play() and the autoplay attribute. The default is MediaAutoplayPolicy.Allowed.
MediaBackendGets or sets the media pipeline of the audio and video elements of the browsing contexts (see MediaBackend): it tells which media types can be played, reads the metadata of the media resources the elements fetch and plays them. The library implements the processing model of the media elements (the resource selection, the ready states, the events, play(), seeking...) but never decodes audio or video by itself. The default is null: the media elements have no media resource (nothing is fetched, no media event is fired, canPlayType() returns the empty string and play() is rejected with a NotSupportedError).
MediaSessionGets or sets the host hooks of the Media Session API (https://w3c.github.io/mediasession/, navigator.mediaSession): MediaSessionOptions.SessionChanged receives the metadata, the playback state, the position state and the action handlers of the pages, to show them in media controls. The default is null: the media session is shown nowhere.
NetworkInformationGets or sets the host hooks of the Network Information API (https://wicg.github.io/netinfo/, navigator.connection): NetworkInformationOptions.Provider is the source of the information about the network connection. The default is null: an unknown connection with the performance of a 4G network (or the network values of BrowsingContextOptions.ClientHints), which never changes.
PendingInputGets or sets the host hooks of navigator.scheduling.isInputPending() (https://wicg.github.io/is-input-pending/): PendingInputOptions.IsInputPending tells whether input events are waiting to be dispatched to a window. The default is null: no input is pending (the input that the host gives to the library is dispatched at once).
PermissionsGets or sets the permissions that the user gave to the origins, read by navigator.permissions.query() (see PermissionStore). The default is null: the browsing contexts that use these options share a store in which every permission is PermissionState.Prompt until it is set.
RenderingBackendGets or sets the rasterizer of the documents of the browsing contexts (see RenderingBackend, e.g. the ImagingRenderingBackend of the Meziantou.Framework.WebPlatform.Imaging package): it turns the display lists the library paints into pixels, decodes the images and draws the canvases. The default is null: nothing is rasterized (the layout and the geometry are computed as usual), and the APIs that need pixels behave as in a user agent that does not support them (e.g. canvas.getContext('2d') returns null).
RequestPermissionGets or sets the callback that asks the user for a permission (https://w3c.github.io/permissions/#dfn-request-permission-to-use), with the name of the powerful feature (e.g. geolocation, notifications): it plays the role of the permission prompt of a browser. It is only called when the state of the permission in BrowsingContextOptions.Permissions is PermissionState.Prompt; the answer (PermissionState.Granted or PermissionState.Denied) is stored in the permission store for the top-level origin, so the user is asked once. The callback blocks the event loop until the user answers. The default is null: the requests are denied, and nothing is stored (as when the user dismisses the prompt). The first argument is the context of the global object that requests the permission (see CallbackContext).
RequestPointerLockGets or sets the callback called when an element of a document of a top-level browsing context requests the pointer lock (https://w3c.github.io/pointerlock/#dom-element-requestpointerlock, "process the lock request"), with the options of Element.RequestPointerLock: the host hides its cursor and reads the movements of its mouse (PointerInput.MoveBy), without the adjustments of the platform when PointerLockOptions.UnadjustedMovement is set, and returns true; it returns false when it cannot or does not want to lock the pointer (the request fails with a NotSupportedError). The default is null: the pointer is locked (a host without cursor has nothing to do, and the movements it injects are not adjusted). The first argument is the context of the top-level browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.
SameDocumentNavigatedGets or sets the callback invoked when the URL of the active document of a browsing context that uses these options changes without a new document (https://html.spec.whatwg.org/multipage/browsing-the-web.html#navigate-to-a-fragment): a navigation to a fragment, history.pushState() or history.replaceState(), a traversal of the session history within the document. The callback is invoked on the thread of the event loop. The first argument is the context of the browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.
ScreenOrientationGets or sets the host hooks of the Screen Orientation API (https://w3c.github.io/screen-orientation/, screen.orientation): ScreenOrientationOptions.Provider is the screen of the device, its orientation and its locks. The default is null: a desktop screen, whose orientation cannot be locked.
ScriptEngineGets or sets the JavaScript engine that runs the scripts of the documents of the browsing contexts (see ScriptEngine). The default is null: the library never executes scripts.
ScriptingEnabledGets or sets whether scripting is enabled for the documents loaded in the browsing contexts (https://html.spec.whatwg.org/multipage/webappapis.html#concept-bc-noscript). The default is true when BrowsingContextOptions.ScriptEngine is set, false otherwise. Without a script engine, it only changes how <noscript> is parsed: the scripts never run.
SensorsGets or sets the host hooks of the sensor APIs (https://w3c.github.io/sensors/, Accelerometer, Gyroscope, Magnetometer, AmbientLightSensor, the orientation sensors, etc.) and of the device orientation and motion events (https://w3c.github.io/deviceorientation/): DeviceSensorsOptions.Provider holds the sensors of the device, whose readings are pushed by the application. The permissions of the sensors are checked with BrowsingContextOptions.Permissions and BrowsingContextOptions.RequestPermission. The default is null: the device has no sensor, so the sensor objects fail to start with a NotReadableError, and the events are fired once with null values.
ServiceWorkersGets or sets the storage of the service worker registrations of the browsing contexts (navigator.serviceWorker), e.g. a database or a InMemoryServiceWorkerBackend shared by several browsing contexts: the registrations, and the scripts of their service workers, outlive the browsing contexts. The default is null: each browsing context created by the application has its own in-memory registrations, shared by its auxiliary browsing contexts and their workers.
ShareGets or sets the callback that shares data with a target chosen by the user (https://w3c.github.io/web-share/, navigator.share()), e.g. the share sheet of the operating system. It returns true when the data is shared, and false when the user cancels (the promise is rejected with an AbortError). The library checks the document (a secure context, fully active, allowed by the web-share permissions policy, with a transient activation) and validates the data before calling it. The callback is invoked on the thread of the event loop; the share completes when the returned task completes. The default is null: there is no share target, so navigator.share() is rejected with an AbortError (navigator.canShare() still validates the data). The first argument is the context of the window (see CallbackContext): its CallbackContext.Window is never null.
ShowFilePickerGets or sets the callback invoked when the file picker of an input element of type file is shown (the activation of the element, or showPicker()). The host lets the user choose files, and sets them with HtmlInputElement.Files (then fires the input and change events). The callback is invoked on the thread of the event loop. The default is null: the file picker closes at once, without file. The first argument is the context of the window of the element (see CallbackContext): its CallbackContext.Window is never null.
ShowNotificationGets or sets the callback that shows a notification to the user (https://notifications.spec.whatwg.org/, new Notification()), once the notifications permission is granted (see BrowsingContextOptions.Permissions and BrowsingContextOptions.RequestPermission): its properties are the title, the body, the icon... The host calls Notification.Click when the user activates it and Notification.Dismiss when the user closes it. The callback is invoked on the thread of the event loop, before the show event is fired. The default is null: the notifications are not displayed, but they behave as if they were (the show event is fired). The first argument is the context of the global object that created the notification (see CallbackContext): its CallbackContext.Global is the window or the worker, and its CallbackContext.BrowsingContext is null for a worker.
SpeculativeLoadingGets or sets the preferences of the user for the speculative loads requested by the speculation rules of the documents (https://html.spec.whatwg.org/multipage/speculative-loading.html): the navigational prefetches and the prerendering. By default, the documents are prefetched and prerendered when a BrowsingContextOptions.DocumentLoader is configured.
SpeculativeParsingGets or sets whether the HTML parser speculatively fetches the resources of the rest of a document while it waits for a parsing-blocking script (https://html.spec.whatwg.org/multipage/parsing.html#speculative-html-parsing): the scripts, the images and the other resources the elements would fetch are requested from the BrowsingContextOptions.DocumentLoader earlier (DocumentRequest.IsSpeculative is true), as a browser does. Each URL is requested speculatively once per document, and the response is not used: the parser requests the resource again when it reaches the element, so the loader should cache the responses to benefit from it. The documents whose response has the Document-Policy: expect-no-linked-resources header are not parsed speculatively. The default is false.
StorageGets or sets the options of the storage of the origins (navigator.storage): the quota that estimate() reports and that the origin private file system enforces, and the answer to persist(). The default is null: the quota is StorageOptions.DefaultQuota, and the storage is never persistent.
TimeProviderGets or sets the clock of the timers of the windows (setTimeout(), requestAnimationFrame()...) and of performance.now(): it is set as the DomEventLoop.TimeProvider of the event loop of the thread when the browsing context is created. Use a fake clock (e.g. FakeTimeProvider) to run the timers without waiting. The default is null: the clock of the event loop (TimeProvider.System by default).
UnhandledScriptErrorGets or sets the callback invoked when an exception reported to a global object (a window or a worker) is not handled: an exception thrown by a script or a callback, whose error event was not canceled, or a promise rejected without handler, whose unhandledrejection event was not canceled (https://html.spec.whatwg.org/multipage/webappapis.html#report-an-exception). It plays the role of the developer console of a browser. The callback is invoked on the thread of the event loop of the global object: the workers run on their own threads. The first argument is the context of the global object that raised it (see CallbackContext): its CallbackContext.Global is the window, the worker or the worklet, and its CallbackContext.BrowsingContext is null for a worker or a worklet.
UseSystemFontsGets or sets whether the fonts installed on the machine can be used: a font-family and a local() source of @font-face can name them, as in a browser. The default is false: the documents only use the fonts bundled with the library (Tinos, Arimo, Cousine, STIX Two Math and Ahem) and their web fonts, so that the layout is the same on every machine.
UserAgentGets or sets the user agent string of the browsing contexts, as the userAgent option of Playwright: navigator.userAgent (and appVersion) of the windows and of the workers, the user agent of the reports, and the User-Agent header of the requests that do not set one. The default is null: Navigator.DefaultUserAgent, and the requests have no User-Agent header (the BrowsingContextOptions.DocumentLoader may add one).
UserPromptHandlerGets or sets the callback that shows the simple dialogs of the windows (https://html.spec.whatwg.org/multipage/timers-and-user-prompts.html#simple-dialogs): alert(), confirm(), prompt(), and the prompt of a beforeunload event that is canceled by a document that has sticky activation (the user is asked to confirm that the document is unloaded). The script waits for the result: the callback blocks the event loop until the user answers. The default is null: no dialog is shown, confirm() returns false, prompt() returns null and the documents are unloaded. The first argument is the context of the window (see CallbackContext): its CallbackContext.Window is never null.
VibrateGets or sets the callback that vibrates the device (https://w3c.github.io/vibration/, navigator.vibrate()), with the normalized pattern: the durations alternate between the vibrations and the pauses, starting with a vibration. An empty pattern cancels the current vibration; it is also used when the document becomes hidden. The callback is invoked on the thread of the event loop, and must not block it. The default is null: nothing vibrates, and navigator.vibrate() returns true (as a device without vibration hardware). The first argument is the context of the window (see CallbackContext): its CallbackContext.Window is never null.
ViewportGets or sets the virtual viewport and the preferences of the user the media queries and the viewport-relative lengths of the computed styles (Window.GetComputedStyle) are evaluated against. The default is ViewportOptions.Default (800x600 CSS pixels).
ViewportSegmentsGets or sets the host hooks of the viewport segments (https://drafts.csswg.org/css-viewport/#viewport-segments, window.viewport.segments, the horizontal-viewport-segments and vertical-viewport-segments media features and the viewport-segment-* environment variables): ViewportSegmentsOptions.Provider reports the display features (folds and hinges) that split the viewport. The default is null: the viewport has a single segment.
VirtualKeyboardGets or sets the host hooks of the VirtualKeyboard API (https://w3c.github.io/virtual-keyboard/, navigator.virtualKeyboard): VirtualKeyboardOptions.Show and VirtualKeyboardOptions.Hide show and hide the on-screen keyboard, whose geometry is reported by VirtualKeyboardOptions.Provider. The default is null: there is no virtual keyboard.
VisitedLinksGets or sets the history of the visited links of the browsing contexts, which the :visited pseudo-class matches against (https://drafts.csswg.org/selectors-4/#link). The default is null: no link is visited (every link matches :link), nothing is recorded, and the rendering of a document does not depend on the documents loaded before it. With a store (e.g. an InMemoryVisitedLinkStore, which can be shared by several browsing contexts), the navigations of the browsing contexts are recorded in it (see VisitedLinkStore.Add), and the visited links are painted with the colors of the :visited rules; the scripts cannot observe which links are visited (getComputedStyle(), matches() and the other APIs answer as if every link was unvisited).
WakeLockGets or sets the host hooks of the Screen Wake Lock API (https://w3c.github.io/screen-wake-lock/, navigator.wakeLock): WakeLockOptions.Acquire and WakeLockOptions.Release keep the screen on. The screen-wake-lock permission is checked with BrowsingContextOptions.Permissions and BrowsingContextOptions.RequestPermission. The default is null: nothing is kept on, but the documents get their locks.
WebAssemblyRuntimeGets or sets the runtime that compiles and runs the WebAssembly modules of the scripts: it defines the WebAssembly namespace in the realms (https://webassembly.github.io/spec/js-api/). The default is null: the namespace is not defined, unless the BrowsingContextOptions.ScriptEngine provides its own (e.g. V8). The Meziantou.Framework.WebPlatform.Wasmtime package provides a runtime.

Gets or sets the Accept-CH cache of the browsing contexts (https://wicg.github.io/client-hints-infrastructure/#accept-ch-cache): the client hints that the origins opted into with the Accept-CH header of the responses of the top-level navigations. The default is null: each browsing context created by the application has its own cache, shared by its auxiliary browsing contexts. A cache can be shared by several browsing contexts, and outlive them.

public AcceptCHCache? AcceptCHCache { get; init; }

Property value

AcceptCHCache?

BackForwardCacheSize

BrowsingContextOptions.cs

Gets or sets the maximum number of documents that a top-level browsing context keeps in its back/forward cache (https://html.spec.whatwg.org/multipage/browsing-the-web.html#note-bfcache). A document that the browsing context navigates away from is kept alive in its session history entry when it is eligible: the pagehide event is fired with persisted set to true instead of the unload event, its tasks and timers are suspended, and a traversal to the entry (e.g. history.back()) makes it the active document again, firing pageshow with persisted set to true, instead of loading it again. As in the browsers, a document is not eligible when it has unload event listeners, an open WebSocket, held web locks, or when its response is not a successful HTTP(S) response to a GET request whose Cache-Control header does not contain no-store, or when its browsing context group has other top-level browsing contexts (e.g. a popup opened without noopener). When the cache is full, the document cached first is evicted. The default is 6 (as in Chromium); 0 disables the cache.

public int BackForwardCacheSize { get; init; }

Property value

int

Gets or sets the host hooks of the Badging API (https://w3c.github.io/badging/, navigator.setAppBadge() and navigator.clearAppBadge()): BadgingOptions.SetBadge shows the badge of the application. The default is null: the badge is not shown anywhere, and the promises are resolved.

public BadgingOptions? Badging { get; init; }

Property value

BadgingOptions?

Gets or sets the host hooks of the Battery Status API (https://w3c.github.io/battery/, navigator.getBattery()): BatteryStatusOptions.Provider is the source of the battery status. The default is null: the BatteryManager reports a fully charged battery that is plugged in (as a user agent that cannot report the battery status).

public BatteryStatusOptions? BatteryStatus { get; init; }

Property value

BatteryStatusOptions?

BrowsingContextCreated

BrowsingContextOptions.cs

Gets or sets the callback invoked when the library creates a browsing context that uses these options: a nested browsing context (the content navigable of an iframe, frame, object or embed element, see BrowsingContext.Parent) or an auxiliary browsing context (window.open(), a _blank target, see BrowsingContext.IsAuxiliary). It is invoked once the browsing context is attached to its parent or to its opener, with its initial about:blank document. It is not invoked for the browsing contexts created by the application. The callback is invoked on the thread of the event loop. The first argument is the context of the new browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.

public Action<CallbackContext>? BrowsingContextCreated { get; init; }

BrowsingContextDestroyed

BrowsingContextOptions.cs

Gets or sets the callback invoked when a browsing context that uses these options is destroyed: a nested browsing context whose container is removed, a top-level browsing context closed by window.close() or disposed by the application (BrowsingContext.Dispose). Its documents are unloaded. The callback is invoked on the thread of the event loop. The first argument is the context of the browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.

public Action<CallbackContext>? BrowsingContextDestroyed { get; init; }

Gets or sets the storage of the caches of the Cache API of the browsing contexts and of their workers (caches), e.g. a database or a InMemoryCacheStorageBackend shared by several browsing contexts. The default is null: each browsing context created by the application has its own in-memory caches, shared by its auxiliary browsing contexts and their workers.

public CacheStorageBackend? CacheStorage { get; init; }

Property value

CacheStorageBackend?

Gets or sets the values of the client hints of the browsing contexts (https://wicg.github.io/client-hints-infrastructure/, https://wicg.github.io/ua-client-hints/): the identity of the user agent exposed by navigator.userAgentData and sent in the Sec-CH-UA-* request headers, the memory of the device and the network information. The default is null: ClientHintsOptions.Default, with ClientHintsOptions.Mobile set when the viewport is the one of a mobile device (ViewportOptions.IsMobile).

public ClientHintsOptions? ClientHints { get; init; }

Property value

ClientHintsOptions?

Remarks

The low-entropy hints (Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform, and Save-Data when ClientHintsOptions.SaveData is set) are sent with every request to a secure origin. The other hints are only sent to the origins that opted into them with the Accept-CH header (see BrowsingContextOptions.AcceptCHCache), and to the origins they delegate them to. Set WebPlatformFeatures.ClientHintsEnabled to false to send no client hint.

Gets or sets the system clipboard of the browsing contexts: the data copied by the copy and cut actions and by navigator.clipboard, read by the paste action and by navigator.clipboard (https://w3c.github.io/clipboard-apis/). The default is null: the browsing contexts share an in-memory clipboard, created with the first browsing context. Set it to observe or simulate what the user copies, or to use the clipboard of the operating system (see SystemClipboard).

public SystemClipboard? Clipboard { get; init; }

Property value

SystemClipboard?

ClipboardPermission

BrowsingContextOptions.cs

Gets or sets the callback that decides whether a document may read or write the system clipboard (https://w3c.github.io/clipboard-apis/#permissions): navigator.clipboard and the copy, cut and paste commands of document.execCommand(). It plays the role of the permission prompt of a browser; there is no user activation, so the access never requires a user gesture. The default is null: all the documents are allowed. Deny the access to untrusted documents when BrowsingContextOptions.Clipboard is the clipboard of the operating system. The first argument is the context of the window (see CallbackContext): its CallbackContext.Window is never null, and CallbackContext.Document is the document that accesses the clipboard.

public Func<CallbackContext, ClipboardAccess, bool>? ClipboardPermission { get; init; }

Property value

Func<CallbackContext, ClipboardAccess, bool>?

Remarks

The asynchronous clipboard API is only available to the documents of a secure context that have the focus, and the copy, cut and paste actions triggered by the user are always allowed.

CloseNotification

BrowsingContextOptions.cs

Gets or sets the callback that removes a notification shown by BrowsingContextOptions.ShowNotification: the script called close(), or a new notification with the same tag replaces it. It is not called when the host closes the notification itself (Notification.Dismiss). The callback is invoked on the thread of the event loop. The default is null. The first argument is the context of the global object that created the notification (see CallbackContext): its CallbackContext.Global is the window or the worker, and its CallbackContext.BrowsingContext is null for a worker.

public Action<CallbackContext, Notification>? CloseNotification { get; init; }

Gets or sets the host hooks of the Compute Pressure API (https://w3c.github.io/compute-pressure/, PressureObserver): ComputePressureOptions.Provider is the source of the pressure states of the device. The default is null: the cpu source is supported, but it reports no state (the observers are never called).

public ComputePressureOptions? ComputePressure { get; init; }

Gets or sets the callback invoked when a script of a global object (a window or a worker) prints a message with the console namespace (console.log(), console.count()... https://console.spec.whatwg.org/). It plays the role of the developer console of a browser. The default is null: the messages are not formatted. The callback is invoked on the thread of the event loop of the global object: the workers run on their own threads. The first argument is the context of the global object that raised it (see CallbackContext): its CallbackContext.Global is the window, the worker or the worklet, and its CallbackContext.BrowsingContext is null for a worker or a worklet.

public Action<CallbackContext, ConsoleMessage>? ConsoleMessage { get; init; }

ContentSecurityPolicyViolation

BrowsingContextOptions.cs

Gets or sets the callback invoked when a content security policy is violated (the policies of the Content-Security-Policy and Content-Security-Policy-Report-Only headers and of the meta elements, including the Trusted Types directives), whatever the disposition of the policy: see ContentSecurityPolicyViolationReport.Disposition. It is invoked with the securitypolicyviolation event, in the task that fires it, so it plays the role of the developer console of a browser. The callback is invoked on the thread of the event loop of the global object: the workers run on their own threads. It is not invoked for a document without browsing context. The first argument is the context of the global object that raised it (see CallbackContext): its CallbackContext.Global is the window, the worker or the worklet, and its CallbackContext.BrowsingContext is null for a worker or a worklet.

public Action<CallbackContext, ContentSecurityPolicyViolationReport>? ContentSecurityPolicyViolation { get; init; }

Gets or sets the cookie store of the browsing contexts: the cookies of Document.Cookie and of the Cookie Store API (window.cookieStore), given to BrowsingContextOptions.DocumentLoader with each request (see DocumentRequest.GetCookieHeader and DocumentRequest.StoreCookies). The default is null: the documents have no cookies. The jar can be shared by several browsing contexts; create it with the BrowsingContextOptions.TimeProvider of the browsing contexts to measure the expiry times with their clock.

public CookieJar? CookieJar { get; init; }

Property value

CookieJar?

DeclarativeRefreshEnabled

BrowsingContextOptions.cs

Gets or sets whether the documents navigate when their declarative refresh comes due: the Refresh header of their response or a <meta http-equiv="refresh"> element, e.g. 5; url=next.html (https://html.spec.whatwg.org/multipage/semantics.html#shared-declarative-refresh-steps). The refresh comes due the given number of seconds after the document is completely loaded (measured by the clock of the DomEventLoop), and the navigation replaces the document. The default is true when BrowsingContextOptions.DocumentLoader is set, false otherwise (the navigation would result in an error document).

public bool DeclarativeRefreshEnabled { get; init; }

Property value

bool

Gets or sets the host hooks of the Device Posture API (https://w3c.github.io/device-posture/, navigator.devicePosture and the device-posture media feature): DevicePostureOptions.Provider is the source of the posture of the device. The default is null: the posture is DevicePostureType.Continuous.

public DevicePostureOptions? DevicePosture { get; init; }

Property value

DevicePostureOptions?

DocumentActivated

BrowsingContextOptions.cs

Gets or sets the callback invoked when a document becomes the active document of a browsing context that uses these options: the end of a navigation (a document is created, including the error document of a navigation whose response is a network error, see Document.IsNetworkErrorDocument), or a traversal of the session history that loads a document. It is not invoked for the initial about:blank document of a new browsing context. The callback is invoked on the thread of the event loop, before the document is parsed. The first argument is the context of the browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.

public Action<CallbackContext, Document>? DocumentActivated { get; init; }

Gets or sets the loader of the documents of the navigations (e.g. the src of an iframe, or location.href = url). Nothing is fetched by the library: when this is null, the navigations to URLs other than about:blank and about:srcdoc result in error documents.

public DocumentLoader? DocumentLoader { get; init; }

Property value

DocumentLoader?

Gets or sets the callback invoked when a browsing context that uses these options downloads a resource (https://html.spec.whatwg.org/multipage/links.html#downloading-resources): the response of a navigation whose Content-Disposition is attachment or whose computed MIME type is application/octet-stream (the active document stays), or the resource of a hyperlink with a download attribute, fetched by BrowsingContextOptions.DocumentLoader. The downloads of the documents sandboxed without allow-downloads are blocked. When null, the downloads are ignored: the hyperlinks with a download attribute fetch nothing, and the rest of the body of an attachment response is not read. The callback is invoked on the thread of the event loop. The first argument is the context of the browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.

public Action<CallbackContext, Download>? DownloadStarted { get; init; }

Gets or sets the detector of the encoding of the HTML documents of the navigations that do not declare their encoding: no byte order mark, no charset in the Content-Type header, no meta element, and no same-origin container document (https://html.spec.whatwg.org/multipage/parsing.html#determining-the-character-encoding). The default is EncodingDetector.Default, which guesses the legacy encodings from the content, and UTF-8 for the file: URLs only (as the browsers). Null disables the detection: these documents are decoded as windows-1252, as the ones whose encoding is not detected. The detector is only used for the HTML documents of the navigations: the other resources (XML documents, text files, style sheets, scripts, the responses of XMLHttpRequest and fetch(), TextDecoder) have the fallback encoding of their specification.

public EncodingDetector? EncodingDetector { get; init; }

Property value

EncodingDetector?

Gets or sets the callback called when the documents of a top-level browsing context are about to be displayed fullscreen (https://fullscreen.spec.whatwg.org/#dom-element-requestfullscreen, "resize the viewport"), with the options of Element.RequestFullscreen. The host of a window makes it fullscreen and returns the size of the viewport while fullscreen (the dimensions of the screen), or null to keep the size of the viewport. The default is null: the viewport keeps its size (BrowsingContextOptions.Viewport), and the fullscreen element fills it (the :fullscreen rules of the user agent style sheet). The first argument is the context of the top-level browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.

public Func<CallbackContext, FullscreenOptions, FullscreenViewportSize?>? EnterFullscreen { get; init; }

Gets or sets the callback called when the documents of a top-level browsing context are no longer displayed fullscreen (https://fullscreen.spec.whatwg.org/#exit-fullscreen): the viewport gets the size of BrowsingContextOptions.Viewport back. The default is null. The first argument is the context of the top-level browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.

public Action<CallbackContext>? ExitFullscreen { get; init; }

Gets or sets the callback called when the pointer lock of a top-level browsing context is exited (https://w3c.github.io/pointerlock/#dfn-exit-pointer-lock): the host displays its cursor again, at the position of the mouse (UserInput.Mouse). The default is null. The first argument is the context of the top-level browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.

public Action<CallbackContext>? ExitPointerLock { get; init; }

Gets or sets the optional features of the web platform exposed to the scripts of the windows and of the workers, e.g. new WebPlatformFeatures { WebSocketEnabled = false }: the scripts see the disabled features as unsupported features, as in a browser that does not implement them. Use it to reduce what the scripts of untrusted documents can do, or to test the fallbacks of a page. The default is null: WebPlatformFeatures.Default (all the features are enabled).

public WebPlatformFeatures? Features { get; init; }

Property value

WebPlatformFeatures?

Gets or sets the storage of the origin private file systems of the browsing contexts and of their workers (navigator.storage.getDirectory()), e.g. a directory, a database or a InMemoryFileSystemBackend shared by several browsing contexts. The default is null: each browsing context created by the application has its own in-memory file systems, shared by its auxiliary browsing contexts and their workers.

public FileSystemBackend? FileSystem { get; init; }

Property value

FileSystemBackend?

Gets or sets the source of the positions of the device (https://w3c.github.io/geolocation/, navigator.geolocation), e.g. a GeolocationProvider whose GeolocationProvider.Position is set by the application, or a subclass that reads the location of the operating system. The library checks the geolocation permission (see BrowsingContextOptions.Permissions and BrowsingContextOptions.RequestPermission) and the permissions policy, and handles the timeouts, the cached positions and the watches. A provider can be shared by several browsing contexts. The default is null: the position is unavailable (POSITION_UNAVAILABLE).

public GeolocationProvider? Geolocation { get; init; }

Property value

GeolocationProvider?

Gets or sets the preference of the user expressed by Global Privacy Control (https://w3c.github.io/gpc/): navigator.globalPrivacyControl, and the Sec-GPC: 1 header of the requests when it is enabled. The default is null: the preference is not set (navigator.globalPrivacyControl is false, and no header is sent).

public GlobalPrivacyControlOptions? GlobalPrivacyControl { get; init; }

Gets or sets the host hooks of the Idle Detection API (https://wicg.github.io/idle-detection/, IdleDetector): IdleDetectionOptions.Provider is the source of the idle state of the user and of the screen. The idle-detection permission is checked with BrowsingContextOptions.Permissions and BrowsingContextOptions.RequestPermission. The default is null: the user is active and the screen is unlocked.

public IdleDetectionOptions? IdleDetection { get; init; }

Property value

IdleDetectionOptions?

Gets or sets the storage of the IndexedDB databases of the browsing contexts and of their workers (indexedDB), e.g. a database or a InMemoryIndexedDBBackend shared by several browsing contexts. The default is null: each browsing context created by the application has its own in-memory databases, shared by its auxiliary browsing contexts and their workers.

public IndexedDBBackend? IndexedDB { get; init; }

Property value

IndexedDBBackend?

Gets or sets the host hooks of the Keyboard Lock API (https://wicg.github.io/keyboard-lock/, navigator.keyboard.lock()): KeyboardLockOptions.Lock and KeyboardLockOptions.Unlock capture the keys that the system or the browser handle. The default is null: no key is captured, but the promises are resolved.

public KeyboardLockOptions? KeyboardLock { get; init; }

Property value

KeyboardLockOptions?

Gets or sets the host hooks of the Keyboard Map API (https://wicg.github.io/keyboard-map/, navigator.keyboard.getLayoutMap()): KeyboardMapOptions.Provider is the source of the keyboard layout. The default is null: the layout is US QWERTY, and it never changes.

public KeyboardMapOptions? KeyboardMap { get; init; }

Property value

KeyboardMapOptions?

Gets or sets the preferred languages of the user, as BCP 47 language tags, in order of preference: navigator.language and navigator.languages of the windows and of the workers, and the Accept-Language header of the requests that do not set one. The default is null: en-US and en, and the requests have no Accept-Language header (the BrowsingContextOptions.DocumentLoader may add one).

public IReadOnlyList<string>? Languages { get; init; }

Gets or sets the local storage areas of the browsing contexts (window.localStorage), keyed by origin. The default is null: each browsing context created by the application has its own storage shed, shared by its auxiliary browsing contexts. A shed can be shared by several browsing contexts: the storage events are fired at the windows of all of them. A shed created with a WebStoragePersistence persists the items.

public StorageShed? LocalStorage { get; init; }

Property value

StorageShed?

MediaAutoplayPolicy

BrowsingContextOptions.cs

Gets or sets whether the media elements are allowed to play without a user gesture (https://html.spec.whatwg.org/multipage/media.html#allowed-to-play): play() and the autoplay attribute. The default is MediaAutoplayPolicy.Allowed.

public MediaAutoplayPolicy MediaAutoplayPolicy { get; init; }

Property value

MediaAutoplayPolicy

Gets or sets the media pipeline of the audio and video elements of the browsing contexts (see MediaBackend): it tells which media types can be played, reads the metadata of the media resources the elements fetch and plays them. The library implements the processing model of the media elements (the resource selection, the ready states, the events, play(), seeking...) but never decodes audio or video by itself. The default is null: the media elements have no media resource (nothing is fetched, no media event is fired, canPlayType() returns the empty string and play() is rejected with a NotSupportedError).

public MediaBackend? MediaBackend { get; init; }

Property value

MediaBackend?

Gets or sets the host hooks of the Media Session API (https://w3c.github.io/mediasession/, navigator.mediaSession): MediaSessionOptions.SessionChanged receives the metadata, the playback state, the position state and the action handlers of the pages, to show them in media controls. The default is null: the media session is shown nowhere.

public MediaSessionOptions? MediaSession { get; init; }

Property value

MediaSessionOptions?

Gets or sets the host hooks of the Network Information API (https://wicg.github.io/netinfo/, navigator.connection): NetworkInformationOptions.Provider is the source of the information about the network connection. The default is null: an unknown connection with the performance of a 4G network (or the network values of BrowsingContextOptions.ClientHints), which never changes.

public NetworkInformationOptions? NetworkInformation { get; init; }

Gets or sets the host hooks of navigator.scheduling.isInputPending() (https://wicg.github.io/is-input-pending/): PendingInputOptions.IsInputPending tells whether input events are waiting to be dispatched to a window. The default is null: no input is pending (the input that the host gives to the library is dispatched at once).

public PendingInputOptions? PendingInput { get; init; }

Property value

PendingInputOptions?

Gets or sets the permissions that the user gave to the origins, read by navigator.permissions.query() (see PermissionStore). The default is null: the browsing contexts that use these options share a store in which every permission is PermissionState.Prompt until it is set.

public PermissionStore? Permissions { get; init; }

Property value

PermissionStore?

Gets or sets the rasterizer of the documents of the browsing contexts (see RenderingBackend, e.g. the ImagingRenderingBackend of the Meziantou.Framework.WebPlatform.Imaging package): it turns the display lists the library paints into pixels, decodes the images and draws the canvases. The default is null: nothing is rasterized (the layout and the geometry are computed as usual), and the APIs that need pixels behave as in a user agent that does not support them (e.g. canvas.getContext('2d') returns null).

public RenderingBackend? RenderingBackend { get; init; }

Property value

RenderingBackend?

Remarks

With a backend, the encoded bytes of the images are kept in memory so that the backend can decode them when they are painted. Nothing is painted until something asks for pixels (e.g. a screenshot): the documents are painted lazily, and painted again only when their layout, their styles or their scroll positions changed.

RequestPermission

BrowsingContextOptions.cs

Gets or sets the callback that asks the user for a permission (https://w3c.github.io/permissions/#dfn-request-permission-to-use), with the name of the powerful feature (e.g. geolocation, notifications): it plays the role of the permission prompt of a browser. It is only called when the state of the permission in BrowsingContextOptions.Permissions is PermissionState.Prompt; the answer (PermissionState.Granted or PermissionState.Denied) is stored in the permission store for the top-level origin, so the user is asked once. The callback blocks the event loop until the user answers. The default is null: the requests are denied, and nothing is stored (as when the user dismisses the prompt). The first argument is the context of the global object that requests the permission (see CallbackContext).

public Func<CallbackContext, string, PermissionState>? RequestPermission { get; init; }

RequestPointerLock

BrowsingContextOptions.cs

Gets or sets the callback called when an element of a document of a top-level browsing context requests the pointer lock (https://w3c.github.io/pointerlock/#dom-element-requestpointerlock, "process the lock request"), with the options of Element.RequestPointerLock: the host hides its cursor and reads the movements of its mouse (PointerInput.MoveBy), without the adjustments of the platform when PointerLockOptions.UnadjustedMovement is set, and returns true; it returns false when it cannot or does not want to lock the pointer (the request fails with a NotSupportedError). The default is null: the pointer is locked (a host without cursor has nothing to do, and the movements it injects are not adjusted). The first argument is the context of the top-level browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.

public Func<CallbackContext, PointerLockOptions, bool>? RequestPointerLock { get; init; }

SameDocumentNavigated

BrowsingContextOptions.cs

Gets or sets the callback invoked when the URL of the active document of a browsing context that uses these options changes without a new document (https://html.spec.whatwg.org/multipage/browsing-the-web.html#navigate-to-a-fragment): a navigation to a fragment, history.pushState() or history.replaceState(), a traversal of the session history within the document. The callback is invoked on the thread of the event loop. The first argument is the context of the browsing context (see CallbackContext): its CallbackContext.BrowsingContext is never null.

public Action<CallbackContext>? SameDocumentNavigated { get; init; }

ScreenOrientation

BrowsingContextOptions.cs

Gets or sets the host hooks of the Screen Orientation API (https://w3c.github.io/screen-orientation/, screen.orientation): ScreenOrientationOptions.Provider is the screen of the device, its orientation and its locks. The default is null: a desktop screen, whose orientation cannot be locked.

public ScreenOrientationOptions? ScreenOrientation { get; init; }

Gets or sets the JavaScript engine that runs the scripts of the documents of the browsing contexts (see ScriptEngine). The default is null: the library never executes scripts.

public ScriptEngine? ScriptEngine { get; init; }

Property value

ScriptEngine?

Remarks

When an engine is set, the scripts of the documents run: the script elements, the event handler content attributes (e.g. onclick), the javascript: URLs and the timers. Do not use an engine with untrusted documents unless it limits the resources the scripts can use, and the BrowsingContextOptions.DocumentLoader limits the resources they can request.

Gets or sets whether scripting is enabled for the documents loaded in the browsing contexts (https://html.spec.whatwg.org/multipage/webappapis.html#concept-bc-noscript). The default is true when BrowsingContextOptions.ScriptEngine is set, false otherwise. Without a script engine, it only changes how <noscript> is parsed: the scripts never run.

public bool ScriptingEnabled { get; init; }

Property value

bool

Gets or sets the host hooks of the sensor APIs (https://w3c.github.io/sensors/, Accelerometer, Gyroscope, Magnetometer, AmbientLightSensor, the orientation sensors, etc.) and of the device orientation and motion events (https://w3c.github.io/deviceorientation/): DeviceSensorsOptions.Provider holds the sensors of the device, whose readings are pushed by the application. The permissions of the sensors are checked with BrowsingContextOptions.Permissions and BrowsingContextOptions.RequestPermission. The default is null: the device has no sensor, so the sensor objects fail to start with a NotReadableError, and the events are fired once with null values.

public DeviceSensorsOptions? Sensors { get; init; }

Property value

DeviceSensorsOptions?

Gets or sets the storage of the service worker registrations of the browsing contexts (navigator.serviceWorker), e.g. a database or a InMemoryServiceWorkerBackend shared by several browsing contexts: the registrations, and the scripts of their service workers, outlive the browsing contexts. The default is null: each browsing context created by the application has its own in-memory registrations, shared by its auxiliary browsing contexts and their workers.

public ServiceWorkerBackend? ServiceWorkers { get; init; }

Property value

ServiceWorkerBackend?

Gets or sets the callback that shares data with a target chosen by the user (https://w3c.github.io/web-share/, navigator.share()), e.g. the share sheet of the operating system. It returns true when the data is shared, and false when the user cancels (the promise is rejected with an AbortError). The library checks the document (a secure context, fully active, allowed by the web-share permissions policy, with a transient activation) and validates the data before calling it. The callback is invoked on the thread of the event loop; the share completes when the returned task completes. The default is null: there is no share target, so navigator.share() is rejected with an AbortError (navigator.canShare() still validates the data). The first argument is the context of the window (see CallbackContext): its CallbackContext.Window is never null.

public Func<CallbackContext, ShareRequest, ValueTask<bool>>? Share { get; init; }

Gets or sets the callback invoked when the file picker of an input element of type file is shown (the activation of the element, or showPicker()). The host lets the user choose files, and sets them with HtmlInputElement.Files (then fires the input and change events). The callback is invoked on the thread of the event loop. The default is null: the file picker closes at once, without file. The first argument is the context of the window of the element (see CallbackContext): its CallbackContext.Window is never null.

public Action<CallbackContext, HtmlInputElement>? ShowFilePicker { get; init; }

Gets or sets the callback that shows a notification to the user (https://notifications.spec.whatwg.org/, new Notification()), once the notifications permission is granted (see BrowsingContextOptions.Permissions and BrowsingContextOptions.RequestPermission): its properties are the title, the body, the icon... The host calls Notification.Click when the user activates it and Notification.Dismiss when the user closes it. The callback is invoked on the thread of the event loop, before the show event is fired. The default is null: the notifications are not displayed, but they behave as if they were (the show event is fired). The first argument is the context of the global object that created the notification (see CallbackContext): its CallbackContext.Global is the window or the worker, and its CallbackContext.BrowsingContext is null for a worker.

public Action<CallbackContext, Notification>? ShowNotification { get; init; }

SpeculativeLoading

BrowsingContextOptions.cs

Gets or sets the preferences of the user for the speculative loads requested by the speculation rules of the documents (https://html.spec.whatwg.org/multipage/speculative-loading.html): the navigational prefetches and the prerendering. By default, the documents are prefetched and prerendered when a BrowsingContextOptions.DocumentLoader is configured.

public SpeculativeLoadingOptions SpeculativeLoading { get; init; }

SpeculativeParsing

BrowsingContextOptions.cs

Gets or sets whether the HTML parser speculatively fetches the resources of the rest of a document while it waits for a parsing-blocking script (https://html.spec.whatwg.org/multipage/parsing.html#speculative-html-parsing): the scripts, the images and the other resources the elements would fetch are requested from the BrowsingContextOptions.DocumentLoader earlier (DocumentRequest.IsSpeculative is true), as a browser does. Each URL is requested speculatively once per document, and the response is not used: the parser requests the resource again when it reaches the element, so the loader should cache the responses to benefit from it. The documents whose response has the Document-Policy: expect-no-linked-resources header are not parsed speculatively. The default is false.

public bool SpeculativeParsing { get; init; }

Property value

bool

Gets or sets the options of the storage of the origins (navigator.storage): the quota that estimate() reports and that the origin private file system enforces, and the answer to persist(). The default is null: the quota is StorageOptions.DefaultQuota, and the storage is never persistent.

public StorageOptions? Storage { get; init; }

Property value

StorageOptions?

Gets or sets the clock of the timers of the windows (setTimeout(), requestAnimationFrame()...) and of performance.now(): it is set as the DomEventLoop.TimeProvider of the event loop of the thread when the browsing context is created. Use a fake clock (e.g. FakeTimeProvider) to run the timers without waiting. The default is null: the clock of the event loop (TimeProvider.System by default).

public TimeProvider? TimeProvider { get; init; }

Property value

TimeProvider?

UnhandledScriptError

BrowsingContextOptions.cs

Gets or sets the callback invoked when an exception reported to a global object (a window or a worker) is not handled: an exception thrown by a script or a callback, whose error event was not canceled, or a promise rejected without handler, whose unhandledrejection event was not canceled (https://html.spec.whatwg.org/multipage/webappapis.html#report-an-exception). It plays the role of the developer console of a browser. The callback is invoked on the thread of the event loop of the global object: the workers run on their own threads. The first argument is the context of the global object that raised it (see CallbackContext): its CallbackContext.Global is the window, the worker or the worklet, and its CallbackContext.BrowsingContext is null for a worker or a worklet.

public Action<CallbackContext, ScriptError>? UnhandledScriptError { get; init; }

Gets or sets whether the fonts installed on the machine can be used: a font-family and a local() source of @font-face can name them, as in a browser. The default is false: the documents only use the fonts bundled with the library (Tinos, Arimo, Cousine, STIX Two Math and Ahem) and their web fonts, so that the layout is the same on every machine.

public bool UseSystemFonts { get; init; }

Property value

bool

Remarks

The installed fonts are found in the font directories of the operating system (Windows, macOS, and the configuration of fontconfig on Linux), once per process: a font installed later is not seen. Only the names and the styles of the fonts are read to match them, and a font file is read when one of its faces is used.

The bundled fonts keep their names: Arimo and Tinos are always the bundled fonts, and the generic families (serif, sans-serif, monospace, math) still use them, with the metrics of the default fonts of the browsers.

Gets or sets the user agent string of the browsing contexts, as the userAgent option of Playwright: navigator.userAgent (and appVersion) of the windows and of the workers, the user agent of the reports, and the User-Agent header of the requests that do not set one. The default is null: Navigator.DefaultUserAgent, and the requests have no User-Agent header (the BrowsingContextOptions.DocumentLoader may add one).

public string? UserAgent { get; init; }

Property value

string?

UserPromptHandler

BrowsingContextOptions.cs

Gets or sets the callback that shows the simple dialogs of the windows (https://html.spec.whatwg.org/multipage/timers-and-user-prompts.html#simple-dialogs): alert(), confirm(), prompt(), and the prompt of a beforeunload event that is canceled by a document that has sticky activation (the user is asked to confirm that the document is unloaded). The script waits for the result: the callback blocks the event loop until the user answers. The default is null: no dialog is shown, confirm() returns false, prompt() returns null and the documents are unloaded. The first argument is the context of the window (see CallbackContext): its CallbackContext.Window is never null.

public Func<CallbackContext, UserPrompt, UserPromptResult>? UserPromptHandler { get; init; }

Gets or sets the callback that vibrates the device (https://w3c.github.io/vibration/, navigator.vibrate()), with the normalized pattern: the durations alternate between the vibrations and the pauses, starting with a vibration. An empty pattern cancels the current vibration; it is also used when the document becomes hidden. The callback is invoked on the thread of the event loop, and must not block it. The default is null: nothing vibrates, and navigator.vibrate() returns true (as a device without vibration hardware). The first argument is the context of the window (see CallbackContext): its CallbackContext.Window is never null.

public Action<CallbackContext, IReadOnlyList<TimeSpan>>? Vibrate { get; init; }

Gets or sets the virtual viewport and the preferences of the user the media queries and the viewport-relative lengths of the computed styles (Window.GetComputedStyle) are evaluated against. The default is ViewportOptions.Default (800x600 CSS pixels).

public ViewportOptions? Viewport { get; init; }

Property value

ViewportOptions?

Gets or sets the host hooks of the viewport segments (https://drafts.csswg.org/css-viewport/#viewport-segments, window.viewport.segments, the horizontal-viewport-segments and vertical-viewport-segments media features and the viewport-segment-* environment variables): ViewportSegmentsOptions.Provider reports the display features (folds and hinges) that split the viewport. The default is null: the viewport has a single segment.

public ViewportSegmentsOptions? ViewportSegments { get; init; }

Gets or sets the host hooks of the VirtualKeyboard API (https://w3c.github.io/virtual-keyboard/, navigator.virtualKeyboard): VirtualKeyboardOptions.Show and VirtualKeyboardOptions.Hide show and hide the on-screen keyboard, whose geometry is reported by VirtualKeyboardOptions.Provider. The default is null: there is no virtual keyboard.

public VirtualKeyboardOptions? VirtualKeyboard { get; init; }

Gets or sets the host hooks of the Screen Wake Lock API (https://w3c.github.io/screen-wake-lock/, navigator.wakeLock): WakeLockOptions.Acquire and WakeLockOptions.Release keep the screen on. The screen-wake-lock permission is checked with BrowsingContextOptions.Permissions and BrowsingContextOptions.RequestPermission. The default is null: nothing is kept on, but the documents get their locks.

public WakeLockOptions? WakeLock { get; init; }

Property value

WakeLockOptions?

WebAssemblyRuntime

BrowsingContextOptions.cs

Gets or sets the runtime that compiles and runs the WebAssembly modules of the scripts: it defines the WebAssembly namespace in the realms (https://webassembly.github.io/spec/js-api/). The default is null: the namespace is not defined, unless the BrowsingContextOptions.ScriptEngine provides its own (e.g. V8). The Meziantou.Framework.WebPlatform.Wasmtime package provides a runtime.

public WebAssemblyRuntime? WebAssemblyRuntime { get; init; }

Property value

WebAssemblyRuntime?

Remarks

The WebAssembly code runs with the resources of the process: the limits of the script engine (e.g. its timeout) interrupt it, but its memories are only limited by the runtime.