dymokomi/luce-browser-engine
Source of release 0.6.0
0.6.0 / src / web / html / scripting / environments_1.lucb
#==============================================================================================
#
# environments_1 - HTML::Environment and HTML::EnvironmentSettingsObject; running script
#
# DESCRIPTION:
# Port of Libraries/LibWeb/HTML/Scripting/Environments.cpp (lines 37-285): the
# environment and the environment settings object (construction, finalize, initialize,
# visit_edges, discarding, the worker agents kept alive while starting, the realm
# execution context, realm, global object, universal global scope and responsible event
# loop), checking whether script can run, preparing to run and cleaning up after running
# script and callbacks, the topmost script-having execution context, and parsing URLs
# relative to an environment. The settings object registers with its responsible event
# loop so that microtask checkpoints notify its global object about rejected promises.
#
# Copyright (c) 2021-2025, Luke Wilde <luke@ladybird.org>
# Copyright (c) 2022, Linus Groh <linusg@serenityos.org>
# Copyright (c) 2022, networkException <networkexception@serenityos.org>
# Copyright (c) 2024-2026, Shannon Booth <shannon@serenityos.org>
# SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================
# mark: Environment =============================================================================
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:37 Web::HTML::Environment::visit_edges (override).
pub func html_environment_visit_edges_impl(base: gc.Cell*, visitor: gc.CellVisitor*):
let this = (HtmlEnvironment*)base
gc.cell_visit_edges_impl(base, visitor)
gc.cell_visitor_visit_t(visitor, this.target_browsing_context)
# mark: EnvironmentSettingsObject ===============================================================
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:43 Web::HTML::EnvironmentSettingsObject::EnvironmentSettingsObject.
## (The NonnullOwnPtr<JS::ExecutionContext> is managed memory the cell's words refer to.)
pub func html_environment_settings_object_construct(this: HtmlEnvironmentSettingsObject*, realm_execution_context: JsExecutionContext*):
this.m_realm_execution_context = realm_execution_context
# Register with the responsible event loop so we can perform step 4 of "perform a microtask checkpoint".
html_event_loop_register_environment_settings_object(html_environment_settings_object_responsible_event_loop(this), this)
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:50 Web::HTML::EnvironmentSettingsObject::finalize (override).
pub func html_environment_settings_object_finalize_impl(base: gc.Cell*):
let this = (HtmlEnvironmentSettingsObject*)base
html_event_loop_unregister_environment_settings_object(html_environment_settings_object_responsible_event_loop(this), this)
gc.cell_finalize_impl(base)
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:56 Web::HTML::EnvironmentSettingsObject::initialize (override).
pub func html_environment_settings_object_initialize_impl(base: JsCell*, realm: Realm*):
let this = (HtmlEnvironmentSettingsObject*)base
js_cell_initialize_impl(base, realm)
# realm.heap().allocate<ModuleMap>(): ModuleMap is opaque until module scripts come with
# scripting (phase 3); its storage is managed memory the settings object's words refer to.
this.m_module_map = new HtmlModuleMap else trap("out of memory")
this.m_universal_global_scope = as_if_universal_global_scope_mixin((gc.Cell*)html_environment_settings_object_global_object(this)) else trap("as<UniversalGlobalScopeMixin> failed")
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:63 Web::HTML::EnvironmentSettingsObject::visit_edges (override).
pub func html_environment_settings_object_visit_edges_impl(base: gc.Cell*, visitor: gc.CellVisitor*):
let this = (HtmlEnvironmentSettingsObject*)base
html_environment_visit_edges_impl(base, visitor)
gc.cell_visitor_visit_t(visitor, this.m_responsible_event_loop)
# visitor.visit(m_module_map): the opaque ModuleMap is managed memory, kept by the scan of the
# cell's words (DESIGN.md §3.1) until it becomes a cell in phase 3.
js_execution_context_visit_edges(this.m_realm_execution_context, visitor)
# visitor.visit(m_storage_manager), the service worker registration and service worker object
# maps and m_worker_agents_to_keep_alive_while_starting: their types are opaque until
# StorageAPI (P4), ServiceWorker (P4) and workers (P4), and they stay empty until then.
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:75 Web::HTML::EnvironmentSettingsObject::discard_environment (override).
pub func html_environment_settings_object_discard_environment_impl(base: HtmlEnvironment*):
let this = (HtmlEnvironmentSettingsObject*)base
# https://w3c.github.io/ServiceWorker/#ref-for-environment-discarding-steps
# Each service worker client has the following environment discarding steps:
# 1. Set client’s discarded flag.
html_environment_settings_object_set_discarded(this, true)
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:84 Web::HTML::EnvironmentSettingsObject::keep_worker_agent_alive_while_starting.
pub func html_environment_settings_object_keep_worker_agent_alive_while_starting(this: HtmlEnvironmentSettingsObject*, worker_agent: HtmlWorkerAgentParent*):
ak.vector_append_t(&this.m_worker_agents_to_keep_alive_while_starting, worker_agent)
## The predicate of release_worker_agent_from_startup_keep_alive (`agent.ptr() == &worker_agent`).
func html_environment_settings_object_is_worker_agent(context: void*?, agent: const (HtmlWorkerAgentParent*)*) -> bool:
return (void*?)*agent == context
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:89 Web::HTML::EnvironmentSettingsObject::release_worker_agent_from_startup_keep_alive.
pub func html_environment_settings_object_release_worker_agent_from_startup_keep_alive(this: HtmlEnvironmentSettingsObject*, worker_agent: HtmlWorkerAgentParent*):
_ = ak.vector_remove_first_matching(&this.m_worker_agents_to_keep_alive_while_starting, ak.Function1[const (HtmlWorkerAgentParent*)*, bool](call = html_environment_settings_object_is_worker_agent, context = worker_agent))
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:96 Web::HTML::EnvironmentSettingsObject::realm_execution_context.
pub func html_environment_settings_object_realm_execution_context(this: HtmlEnvironmentSettingsObject*) -> JsExecutionContext*:
# NOTE: All environment settings objects are created with a realm execution context, so it's stored and returned here in the base class.
return this.m_realm_execution_context
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:102 Web::HTML::EnvironmentSettingsObject::realm_execution_context (const).
pub func html_environment_settings_object_realm_execution_context_const(this: HtmlEnvironmentSettingsObject*) -> const JsExecutionContext*:
# NOTE: All environment settings objects are created with a realm execution context, so it's stored and returned here in the base class.
return this.m_realm_execution_context
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:108 Web::HTML::EnvironmentSettingsObject::module_map.
pub func html_environment_settings_object_module_map(this: HtmlEnvironmentSettingsObject*) -> HtmlModuleMap*:
return this.m_module_map else trap("the environment settings object has no module map")
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:114 Web::HTML::EnvironmentSettingsObject::realm.
## https://html.spec.whatwg.org/multipage/webappapis.html#environment-settings-object%27s-realm
pub func html_environment_settings_object_realm(this: HtmlEnvironmentSettingsObject*) -> Realm*:
# An environment settings object's realm execution context's Realm component is the environment settings object's Realm.
return html_environment_settings_object_realm_execution_context(this).realm else trap("the realm execution context has no realm")
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:121 Web::HTML::EnvironmentSettingsObject::global_object.
## https://html.spec.whatwg.org/multipage/webappapis.html#concept-settings-object-global
pub func html_environment_settings_object_global_object(this: HtmlEnvironmentSettingsObject*) -> JsObject*:
# An environment settings object's Realm then has a [[GlobalObject]] field, which contains the environment settings object's global object.
return realm_global_object(html_environment_settings_object_realm(this))
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:127 Web::HTML::EnvironmentSettingsObject::universal_global_scope.
pub func html_environment_settings_object_universal_global_scope(this: HtmlEnvironmentSettingsObject*) -> HtmlUniversalGlobalScopeMixin*:
return this.m_universal_global_scope else trap("the environment settings object has no universal global scope")
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:133 Web::HTML::EnvironmentSettingsObject::responsible_event_loop.
## https://html.spec.whatwg.org/multipage/webappapis.html#responsible-event-loop
pub func html_environment_settings_object_responsible_event_loop(this: HtmlEnvironmentSettingsObject*) -> HtmlEventLoop*:
# An environment settings object's responsible event loop is its global object's relevant agent's event loop.
# This is here in case the realm that is holding onto this ESO is destroyed before the ESO is. The responsible event loop pointer is needed in the ESO destructor to deregister from the event loop.
# FIXME: Figure out why the realm can be destroyed before the ESO, as the realm is holding onto this with an OwnPtr, but the heap block deallocator calls the ESO destructor directly instead of through the realm destructor.
if let responsible_event_loop = this.m_responsible_event_loop:
return responsible_event_loop
let event_loop = html_relevant_agent(html_environment_settings_object_global_object(this)).event_loop else trap("the relevant agent has no event loop")
this.m_responsible_event_loop = event_loop
return event_loop
# mark: Running script ==========================================================================
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:146 Web::HTML::can_run_script.
## https://html.spec.whatwg.org/multipage/webappapis.html#check-if-we-can-run-script
pub func html_can_run_script(settings: HtmlEnvironmentSettingsObject*) -> HtmlRunScriptDecision:
# 1. If the global object specified by settings is a Window object whose Document object is not fully active,
# then return "do not run".
if let window = as_if_html_window((gc.Cell*)html_environment_settings_object_global_object(settings)):
if not dom_document_is_fully_active(html_window_associated_document(window)):
return HtmlRunScriptDecision.do_not_run
# 2. If scripting is disabled for settings, then return "do not run".
if html_is_scripting_disabled(settings):
return HtmlRunScriptDecision.do_not_run
# 3. Return "run".
return HtmlRunScriptDecision.run
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:164 Web::HTML::prepare_to_run_script.
## https://html.spec.whatwg.org/multipage/webappapis.html#prepare-to-run-script
pub func html_prepare_to_run_script(settings: HtmlEnvironmentSettingsObject*):
# 1. Push settings's realm execution context onto the JavaScript execution context stack; it is now the running JavaScript execution context.
vm_push_execution_context(realm_vm(html_environment_settings_object_realm(settings)), html_environment_settings_object_realm_execution_context(settings))
# FIXME: 2. Add settings to the surrounding agent's event loop's currently running task's script evaluation environment settings object set.
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:173 Web::HTML::clean_up_after_running_script.
## https://html.spec.whatwg.org/multipage/webappapis.html#clean-up-after-running-script
pub func html_clean_up_after_running_script(settings: HtmlEnvironmentSettingsObject*):
let vm = js_cell_vm((JsCell*)html_environment_settings_object_global_object(settings))
# 1. Assert: settings's realm execution context is the running JavaScript execution context.
assert(html_environment_settings_object_realm_execution_context_const(settings) == vm_running_execution_context(vm))
# 2. Remove settings's realm execution context from the JavaScript execution context stack.
_ = vm_pop_execution_context(vm)
# 3. If the JavaScript execution context stack is now empty, perform a microtask checkpoint. (If this runs scripts, these algorithms will be invoked reentrantly.)
if not vm_has_running_execution_context(vm):
html_event_loop_perform_a_microtask_checkpoint(html_main_thread_event_loop())
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:188 Web::HTML::top_most_script_having_execution_context.
func html_top_most_script_having_execution_context(vm: Vm*) -> JsExecutionContext*?:
# Here, the topmost script-having execution context is the topmost entry of the JavaScript execution context stack that has a non-null ScriptOrModule component,
# or null if there is no such entry in the JavaScript execution context stack.
# (vm.last_execution_context_matching: the stack from the top down.)
let stack = vm_execution_context_stack(vm)
var index = stack.length
while index > 0:
index -= 1
let context = stack[index]
let has_script_or_module = match context.script_or_module:
.empty => false
if has_script_or_module:
return context
return none
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:203 Web::HTML::prepare_to_run_callback.
## https://html.spec.whatwg.org/multipage/webappapis.html#prepare-to-run-a-callback
pub func html_prepare_to_run_callback(settings: HtmlEnvironmentSettingsObject*):
let vm = js_cell_vm((JsCell*)html_environment_settings_object_global_object(settings))
# 1. Push settings onto the backup incumbent settings object stack.
# NOTE: The spec doesn't say which event loop's stack to put this on. However, all the examples of the incumbent settings object use iframes and cross browsing context communication to demonstrate the concept.
# This means that it must rely on some global state that can be accessed by all browsing contexts, which is the main thread event loop.
html_event_loop_push_onto_backup_incumbent_realm_stack(html_main_thread_event_loop(), settings)
# 2. Let context be the topmost script-having execution context.
# 3. If context is not null, increment context's skip-when-determining-incumbent counter.
if let context = html_top_most_script_having_execution_context(vm):
context.skip_when_determining_incumbent_counter += 1
# mark: Parsing URLs ============================================================================
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:222 Web::HTML::EnvironmentSettingsObject::parse_url.
## https://html.spec.whatwg.org/multipage/urls-and-fetching.html#parse-a-url
pub func html_environment_settings_object_parse_url(this: HtmlEnvironmentSettingsObject*, url: ak.StringView) -> web_url.Url?:
# 1. Let baseURL be environment's base URL, if environment is a Document object; otherwise environment's API base URL.
let base_url = html_environment_settings_object_api_base_url(this)
# 2. Return the result of applying the URL parser to url, with baseURL.
return domurl_parse(url, base_url)
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:232 Web::HTML::EnvironmentSettingsObject::encoding_parse_url.
## https://html.spec.whatwg.org/multipage/urls-and-fetching.html#encoding-parsing-a-url
pub func html_environment_settings_object_encoding_parse_url(this: HtmlEnvironmentSettingsObject*, url: ak.StringView) -> web_url.Url?:
# 1. Let encoding be UTF-8.
var encoding = ak.string_from_str("UTF-8")
# 2. If environment is a Document object, then set encoding to environment's character encoding.
# 3. Otherwise, if environment's relevant global object is a Window object, set encoding to environment's relevant
# global object's associated Document's character encoding.
if let window = as_if_html_window((gc.Cell*)html_environment_settings_object_global_object(this)):
encoding = dom_document_encoding_or_default(html_window_associated_document(window))
# 4. Let baseURL be environment's base URL, if environment is a Document object; otherwise environment's API base URL.
let base_url = html_environment_settings_object_api_base_url(this)
# 5. Return the result of applying the URL parser to url, with baseURL and encoding.
return domurl_parse(url, base_url, ak.string_bytes_as_string_view(&encoding))
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:252 Web::HTML::EnvironmentSettingsObject::encoding_parse_and_serialize_url.
## https://html.spec.whatwg.org/multipage/urls-and-fetching.html#encoding-parsing-and-serializing-a-url
pub func html_environment_settings_object_encoding_parse_and_serialize_url(this: HtmlEnvironmentSettingsObject*, url: ak.StringView) -> ak.String?:
# 1. Let url be the result of encoding-parsing a URL given url, relative to environment.
let parsed_url = html_environment_settings_object_encoding_parse_url(this, url)
# 2. If url is failure, then return failure.
let parsed = parsed_url else return none
# 3. Return the result of applying the URL serializer to url.
return web_url.url_serialize(&parsed)
## Ported from Libraries/LibWeb/HTML/Scripting/Environments.cpp:266 Web::HTML::clean_up_after_running_callback.
## https://html.spec.whatwg.org/multipage/webappapis.html#clean-up-after-running-a-callback
pub func html_clean_up_after_running_callback(settings: HtmlEnvironmentSettingsObject*):
let vm = js_cell_vm((JsCell*)html_environment_settings_object_global_object(settings))
# 1. Let context be the topmost script-having execution context.
# 2. If context is not null, decrement context's skip-when-determining-incumbent counter.
if let context = html_top_most_script_having_execution_context(vm):
context.skip_when_determining_incumbent_counter -= 1
# 3. Assert: the topmost entry of the backup incumbent realm stack is settings.
let event_loop = html_main_thread_event_loop()
assert(html_event_loop_top_of_backup_incumbent_realm_stack(event_loop) == settings)
# 4. Remove settings from the backup incumbent realm stack.
html_event_loop_pop_backup_incumbent_realm_stack(event_loop)