Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / tests / web_test / worker_load.lucb

#==============================================================================================
#
#   worker_load - a test's page, its document loaded from a file, and the waits of test-web
#
#   DESCRIPTION:
#       The page: WebContent's PageHost makes a PageClient (with its Page) and a fresh top-level
#       traversable on about:blank (TraversableNavigable::create_a_fresh_top_level_traversable);
#       HeadlessWebView then sets the 800x600 viewport. Phase 1 runs with scripting disabled
#       (DESIGN.md §1.3), as SVG-as-image documents do upstream.
#
#       The document (DESIGN.md §6.1 step 3): there is no navigation or body stream yet, so the
#       worker does what SVG/SVGDecodedImageData.cpp does for an image's bytes and what
#       DocumentLoading.cpp's load_document does for a navigation response: a file: response
#       whose URL list is the test's file URL (URL::create_with_file_scheme of its absolute
#       path, as test-web loads it) and whose Content-Type is the type LibCore guesses from the
#       file's name (as ResourceLoader answers file: URLs), navigation params for it in the
#       top-level traversable, the computed type of the response, Document::create_and_initialize,
#       and the new document made the traversable's active document (SVGDecodedImageData's
#       activation, completed by Document::make_active as Navigable's activation of a history
#       entry does). An HTML document (load_html_document) is parsed by
#       HTMLParser::create_with_uncertain_encoding over the bytes and HTMLParser::run(url); an XML
#       document (load_xml_document: .xht, .xhtml, .svg, .xml) is made ready to run scripts, as
#       the activation does, and given the bytes by load_xml_document's process_body steps, which
#       decode them and run the XML parser (XMLDocumentBuilder over luce-xml). The parser's "the
#       end" (HTML) or document_end (XML) completes the loading on the event loop
#       (DOMContentLoaded, the load event, "completely finish loading"), and the page tells its
#       client the document finished loading, which is when test-web injects its waiting
#       script.
#
#       The waits (test-web's afterFontsAndPaint, natively): document.fonts.ready, then two
#       animation frame callbacks (`requestAnimationFrame(() => requestAnimationFrame(...))`:
#       Window::request_animation_frame adds to the window's AnimationFrameCallbackDriver and
#       requests a frame from the client), which run in two rounds of "update the rendering".
#       The `test-wait` / `reftest-wait` classes need script to change, so they are not
#       watched in phase 1.
#
#       Copyright (c) 2023-2026, the Ladybird developers.
#       Copyright (c) 2026 the luce-browser authors.
#       SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================

# mark: Stages ==================================================================================

## Reports that the worker reached `stage` (the driver reads the last one a failed worker
## reported).
func worker_stage(stage: str):
    io.stderr().write(f"web_test: stage {stage}\n") catch failure: return

# mark: The page ================================================================================

## A test's page: the client, its page and the page's top-level traversable.
struct WorkerPage:
    var client: WorkerPageClient*
    var page: web.Page*
    var traversable: web.HtmlTraversableNavigable*

## The lambda of create_a_fresh_top_level_traversable that finishes the initial about:blank
## document.
func worker_initial_document_the_end(context: void*?):
    let traversable = (web.HtmlTraversableNavigable*)(context else trap("web_test: no traversable"))
    let document = web.html_navigable_active_document((web.HtmlNavigable*)traversable) else trap("web_test: no initial document")
    web.html_parser_the_end(document)

## TraversableNavigable::create_a_fresh_top_level_traversable(page, about:blank), which
## PageHost's constructor calls, without its AD-HOC emulated geolocation position (a
## Geolocation::GeolocationCoordinates, phase 4): a new top-level traversable set as the page's,
## its initial about:blank document marked as finished parsing on the event loop.
func worker_create_a_fresh_top_level_traversable(page: web.Page*) -> web.HtmlTraversableNavigable*:
    let traversable = web.html_traversable_navigable_create_a_new_top_level_traversable(page, none, ak.string_from_str(""))
    web.page_set_top_level_traversable(page, traversable)
    let heap = gc.cell_heap((gc.Cell*)traversable)
    web.platform_event_loop_plugin_deferred_invoke(web.platform_event_loop_plugin_the(),
                                                   gc.create_function0(heap, ak.Function0[unit](call = worker_initial_document_the_end, context = traversable)))
    return traversable

## The page of a test (PageHost::PageHost, HeadlessWebView::initialize_client): its client, a
## fresh top-level traversable on about:blank whose initial document has finished, the
## viewport, visible unless the page is not `rendering`, scripting disabled.
func worker_create_page(vm: web.Vm*, event_loop: WorkerEventLoop*, rendering: bool) -> WorkerPage:
    let client = worker_create_page_client(vm, rendering)
    let page = client.m_page else trap("web_test: no page")
    let traversable = worker_create_a_fresh_top_level_traversable(page)
    # ViewImplementation::initialize_client: the viewport (zoom 1, device pixel ratio 1, at most 60
    # frames a second, the client's defaults) and the system visibility state, visible for a
    # headless view. Without rendering the page stays hidden (the traversable's initial state),
    # and "update the rendering" leaves hidden documents alone.
    worker_page_client_set_viewport(client, 800, 600)
    if rendering:
        web.html_traversable_navigable_set_system_visibility_state(traversable, web.HtmlVisibilityState.visible)
    web.page_set_is_scripting_enabled(page, false)
    worker_drain(event_loop)
    return WorkerPage(client = client, page = page, traversable = traversable)

# mark: Loading a document ======================================================================

## The file: URL of the absolute path `path` (URL::create_with_file_scheme).
func worker_file_url(path: str) -> web_url.Url:
    return web_url.create_with_file_scheme(ak.byte_string_from_str(path), ak.byte_string_empty(), ak.byte_string_empty()) else trap("web_test: the test path is not a file URL")

## The registered types a test's file can be, in the order of LibCore's s_registered_mime_type
## (Libraries/LibCore/MimeData.cpp): each name with the extensions it is guessed from.
struct WorkerMimeTypeGuess:
    let name: str
    let extensions: str[3]

## The rows of s_registered_mime_type that name the extensions of test documents, in order ("" ends
## a row's extensions).
let worker_mime_type_guesses: WorkerMimeTypeGuess[5] = [
    WorkerMimeTypeGuess(name = "application/pdf", extensions = [".pdf", "", ""]),
    WorkerMimeTypeGuess(name = "application/xhtml+xml", extensions = [".xhtml", ".xht", ""]),
    WorkerMimeTypeGuess(name = "image/svg+xml", extensions = [".svg", "", ""]),
    WorkerMimeTypeGuess(name = "text/html", extensions = [".html", ".htm", "/"]),
    WorkerMimeTypeGuess(name = "text/xml", extensions = [".xml", "", ""]),
]

## Core::guess_mime_type_based_on_filename (Libraries/LibCore/MimeData.cpp:151), over the rows of
## worker_mime_type_guesses: the type of the first row with an extension `path` ends with.
func worker_guess_mime_type(path: str) -> str:
    for mime_type in worker_mime_type_guesses:
        for possible_extension in mime_type.extensions:
            if possible_extension.length > 0 and strings.ends_with(path, possible_extension):
                return mime_type.name
    return "application/octet-stream"

## A response of a navigation to the file `url` as a file: fetch delivers it
## (ResourceLoader's response_headers_for_file): its URL list « url » and a Content-Type header
## of the type guessed from the file's name.
func worker_file_response(vm: web.Vm*, url: web_url.Url) -> web.FetchResponse*:
    let response = web.fetch_infrastructure_response_create(vm)
    ak.vector_append_t(web.fetch_response_url_list(response), url)
    let path_string = web_url.url_file_path(&url)
    let mime_type = worker_guess_mime_type(ak.string_view_text(ak.byte_string_view(&path_string)))
    web.http_header_list_append(web.fetch_response_header_list(response), web.http_header_create(ak.sv("Content-Type"), ak.sv(mime_type)))
    return response

## load_document, step 1: the computed type of the response (the supplied type of its
## Content-Type header, sniffed in a browsing context over the file's first bytes).
func worker_computed_type(response: web.FetchResponse*, bytes: const u8[]) -> web.MimeType:
    var configuration = web.MimeSniffingConfiguration()
    web.mime_sniffing_configuration_init_fields(&configuration)
    configuration.sniffing_context = web.MimeSniffingContext.browsing
    configuration.supplied_type = web.fetch_extract_mime_type(web.fetch_response_header_list(response))
    let sniffed = bytes[..<bytes.length] if bytes.length <= 1445 else bytes[..<1445]
    return web.mime_resource_sniff(sniffed, configuration)

## The new document replaces the navigable's (see the header): SVGDecodedImageData::create's
## replacement, then the activation of its history entry.
func worker_activate_document(page: const WorkerPage*, document: web.DomDocument*):
    let navigable = (web.HtmlNavigable*)page.traversable
    let previous_document = web.html_navigable_active_document(navigable)
    # SVGDecodedImageData::create: the new document replaces the navigable's (FIXME there: use
    # Navigable::navigate, which is phase 2), then the activation of its history entry.
    web.html_navigable_set_ongoing_navigation(navigable, web.EmptyOrHtmlNavigableTraversalOrString.empty)
    web.html_navigable_set_active_document(navigable, document)
    web.dom_document_make_active(document)
    # Navigable::activate_history_entry, step 6: set the initial visibility state of the document to the navigable's
    # traversable navigable's system visibility state (a hidden document is not rendered).
    web.dom_document_set_initial_visibility_state(document, web.html_traversable_navigable_system_visibility_state(page.traversable))
    # Then the replaced document is unloaded, as the history step that activates the new one
    # unloads the old (unload_a_document_and_its_descendants). A navigation does not intend to
    # keep it in a back/forward cache, so unloading destroys it (Document::unload, steps 9 and
    # 19), and with it its queued tasks: test-web loads a reftest's reference by navigating,
    # and a rendering task the test document left queued must not hold back the reference's.
    if let previous = previous_document:
        web.dom_document_unload(previous, document)

## Loads the `bytes` of the file `url` into the page's top-level traversable as its active
## document and starts parsing them, as load_document does for the computed type (see the
## header): an HTML document (load_html_document) or an XML document (load_xml_document).
## Answers the document.
func worker_load_document(page: const WorkerPage*, vm: web.Vm*, url: web_url.Url, bytes: const u8[]) -> web.DomDocument*:
    let heap = web.vm_heap(vm)
    let navigable = (web.HtmlNavigable*)page.traversable

    # The navigation params of a response (Navigable::populate_session_history_entry for a fetched
    # response): its origin, a new policy container, no sandboxing.
    let response = worker_file_response(vm, url)
    let origin = web_url.url_origin(&url)
    let coop = web.HtmlOpenerPolicy()
    let coop_enforcement_result = web.HtmlOpenerPolicyEnforcementResult(url = url, origin = origin, opener_policy = coop)
    let policy_container = web.heap_allocate_html_policy_container(heap)
    let navigation_params = web.heap_allocate_html_navigation_params(heap, none, navigable, none, response, none, none, coop_enforcement_result, none,
                                                                     origin, policy_container, (web.HtmlSandboxingFlagSet)0, coop, none,
                                                                     web.HtmlUserNavigationInvolvement.browser_ui)

    let type_ = worker_computed_type(response, bytes)
    let input = ak.byte_buffer_copy_span_u8(bytes) else trap("out of memory")

    # -> an HTML MIME type
    if web.mime_type_is_html(&type_):
        # load_html_document, step 1: create and initialize a Document of "html" and "text/html".
        let document = web.dom_document_create_and_initialize(web.DocumentDomDocumentType.html, ak.string_from_str("text/html"), navigation_params) else trap("web_test: Document::create_and_initialize threw")
        worker_activate_document(page, document)
        worker_stage("created")

        # load_html_document, step 3: an HTML parser over the response's body.
        let parser = web.html_parser_create_with_uncertain_encoding(document, input)
        web.html_parser_run_url(parser, url)
        worker_stage("parsed")
        return document

    # -> an XML MIME type that is not an explicitly supported XML MIME type
    if web.mime_type_is_xml(&type_):
        # load_xml_document: create and initialize a Document of "xml" and the type's essence.
        let document = web.dom_document_create_and_initialize(web.DocumentDomDocumentType.xml, web.mime_type_essence(&type_), navigation_params) else trap("web_test: Document::create_and_initialize threw")
        worker_activate_document(page, document)
        # Document::update_for_history_step_application, step 8.4: at this point scripts may run for
        # the newly-created document (which starts a parser load_xml_document deferred).
        web.dom_document_set_ready_to_run_scripts(document)
        worker_stage("created")

        # load_xml_document's process_body with the body's bytes, which Body::fully_read reads from
        # the body's stream (phase 4): the charset of the type, decoding, then the XML parser.
        var content_encoding: ak.String? = none
        if let maybe_encoding = ak.ordered_hash_map_get_k_const(web.mime_type_parameters(&type_), ak.string_from_str("charset")):
            content_encoding = *maybe_encoding
        let process_body = new web.DocumentLoadingProcessXmlBody(document = document, url = url, content_encoding = content_encoding, mime = type_) else trap("out of memory")
        web.DocumentLoadingProcessXmlBody.call(process_body, input)
        worker_stage("parsed")
        return document

    let essence = web.mime_type_essence(&type_)
    trap(f"web_test: unported: loading a document of type {ak.string_view_text(ak.string_bytes_as_string_view(&essence))}")

## Whether the client was told that `url` finished loading.
func worker_finished_loading(client: WorkerPageClient*, url: const web_url.Url*) -> bool:
    for index in 0..<ak.vector_size(&client.m_finished_loading):
        let loaded = *ak.vector_at_const(&client.m_finished_loading, index)
        if web_url.url_equals(url, loaded, web_url.ExcludeFragment.yes):
            return true
    return false

## Runs the event loop until the page tells its client that `url` finished loading (test-web's
## on_load_finish for the test's URL).
func worker_wait_for_load(page: const WorkerPage*, event_loop: WorkerEventLoop*, url: const web_url.Url*):
    while not worker_finished_loading(page.client, url):
        _ = event_loop.pump(web.CoreEventLoopPumpMode.wait_for_events)
    worker_stage("loaded")

# mark: afterFontsAndPaint ======================================================================

## The two nested animation frame callbacks of afterFontsAndPaint.
struct WorkerAnimationFrames:
    var window: web.HtmlWindow*
    var client: WorkerPageClient*
    var remaining: i32

## One animation frame callback: the next one is requested until none remain.
func worker_animation_frame(context: void*?, now: f64):
    let frames = (WorkerAnimationFrames*)(context else trap("web_test: animation frame without its state"))
    frames.remaining -= 1
    if frames.remaining > 0:
        worker_request_animation_frame(frames)

## Window::request_animation_frame with a native callback.
func worker_request_animation_frame(frames: WorkerAnimationFrames*):
    let heap = gc.cell_heap((gc.Cell*)frames.window)
    let callback = gc.create_function1(heap, ak.Function1[f64, unit](call = worker_animation_frame, context = frames))
    _ = web.html_animation_frame_callback_driver_add(web.html_window_animation_frame_callback_driver(frames.window), callback)
    web.page_client_request_frame(&frames.client.page_client)

## test-web's afterFontsAndPaint: document.fonts.ready, then two animation frames.
func worker_after_fonts_and_paint(page: const WorkerPage*, event_loop: WorkerEventLoop*, document: web.DomDocument*):
    let ready = web.css_font_face_set_ready(web.dom_document_fonts(document))
    while not web.idl_is_promise_fulfilled(ready):
        _ = event_loop.pump(web.CoreEventLoopPumpMode.wait_for_events)
    worker_stage("fonts-ready")

    let window = web.dom_document_window(document) else trap("web_test: the document has no window")
    let frames = new WorkerAnimationFrames(window = window, client = page.client, remaining = 2) else trap("out of memory")
    worker_request_animation_frame(frames)
    while frames.remaining > 0:
        _ = event_loop.pump(web.CoreEventLoopPumpMode.wait_for_events)
    worker_stage("painted")

# mark: Screenshots =============================================================================

## A screenshot of the page (test-web's TestWebView::take_screenshot: the traversable's screenshot
## task, whose bitmap reaches the client).
func worker_take_screenshot(page: const WorkerPage*, event_loop: WorkerEventLoop*) -> gfx.Bitmap*?:
    let count = ak.vector_size(&page.client.m_screenshots)
    web.html_traversable_navigable_queue_screenshot_task(page.traversable, none)
    while ak.vector_size(&page.client.m_screenshots) == count:
        _ = event_loop.pump(web.CoreEventLoopPumpMode.wait_for_events)
    worker_stage("screenshot")
    return ak.vector_at_const(&page.client.m_screenshots, count).m_bitmap