Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / src / web / html / traversable_navigable_5.lucb

#==============================================================================================
#
#   traversable_navigable_5 - HTML::TraversableNavigable: the apply-a-history-step entry points,
#   closing and destroying top-level traversables, same-document navigation, visibility, focus,
#   emulated geolocation and screenshots
#
#   DESCRIPTION:
#       Port of Libraries/LibWeb/HTML/TraversableNavigable.cpp lines 1564-1850
#       (update_for_navigable_creation_or_destruction, apply_the_reload_history_step,
#       apply_the_push_or_replace_history_step, apply_the_traverse_history_step,
#       close/definitely_close/destroy_top_level_traversable, finalize_a_same_document_navigation,
#       set_system_visibility_state, currently_focused_area, emulated_position_data,
#       set_emulated_position_data, process_screenshot_requests).
#
#       Copyright (c) 2022, Andreas Kling <andreas@ladybird.org>
#       Copyright (c) 2023-2025, Aliaksandr Kalenik <kalenik.aliaksandr@gmail.com>
#       SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================

# mark: Applying history steps ==================================================================

## Ported from TraversableNavigable.cpp:1566 Web::HTML::TraversableNavigable::update_for_navigable_creation_or_destruction.
# https://html.spec.whatwg.org/multipage/browsing-the-web.html#update-for-navigable-creation/destruction
pub func html_traversable_navigable_update_for_navigable_creation_or_destruction(this: HtmlTraversableNavigable*, on_complete: gc.Function1[HtmlHistoryStepResult, unit]*):
    # 1. Let step be traversable's current session history step.
    let step = html_traversable_navigable_current_session_history_step(this)

    # 2. Return the result of applying the history step to traversable given false, null, null, null, and null.
    html_traversable_navigable_apply_the_history_step(this, step, false, none, none, HtmlUserNavigationInvolvement.none_, none, HtmlTraversableNavigableSynchronousNavigation.no, none, on_complete)

## Ported from TraversableNavigable.cpp:1576 Web::HTML::TraversableNavigable::apply_the_reload_history_step.
# https://html.spec.whatwg.org/multipage/browsing-the-web.html#apply-the-reload-history-step
pub func html_traversable_navigable_apply_the_reload_history_step(this: HtmlTraversableNavigable*, user_involvement: HtmlUserNavigationInvolvement, on_complete: gc.Function1[HtmlHistoryStepResult, unit]*):
    # 1. Let step be traversable's current session history step.
    let step = html_traversable_navigable_current_session_history_step(this)

    # 2. Return the result of applying the history step step to traversable given true, null, null, null, and "reload".
    html_traversable_navigable_apply_the_history_step(this, step, true, none, none, user_involvement, BindNavigationType.reload, HtmlTraversableNavigableSynchronousNavigation.no, none, on_complete)

## Ported from TraversableNavigable.cpp:1586 Web::HTML::TraversableNavigable::apply_the_push_or_replace_history_step.
# https://html.spec.whatwg.org/multipage/browsing-the-web.html#apply-the-push/replace-history-step
pub func html_traversable_navigable_apply_the_push_or_replace_history_step(this: HtmlTraversableNavigable*, step: i32, history_handling: HtmlHistoryHandlingBehavior, user_involvement: HtmlUserNavigationInvolvement, synchronous_navigation: HtmlTraversableNavigableSynchronousNavigation, pending_document: DomDocument*?, on_complete: gc.Function1[HtmlHistoryStepResult, unit]*):
    # 1. Return the result of applying the history step step to traversable given false, null, null, userInvolvement, and historyHandling.
    var navigation_type = BindNavigationType.push
    if history_handling == HtmlHistoryHandlingBehavior.replace:
        navigation_type = BindNavigationType.replace
    html_traversable_navigable_apply_the_history_step(this, step, false, none, none, user_involvement, navigation_type, synchronous_navigation, pending_document, on_complete)

## Ported from TraversableNavigable.cpp:1593 Web::HTML::TraversableNavigable::apply_the_traverse_history_step.
pub func html_traversable_navigable_apply_the_traverse_history_step(this: HtmlTraversableNavigable*, step: i32, source_snapshot_params: HtmlSourceSnapshotParams*?, initiator_to_check: HtmlNavigable*?, user_involvement: HtmlUserNavigationInvolvement, on_complete: gc.Function1[HtmlHistoryStepResult, unit]*):
    # 1. Return the result of applying the history step step to traversable given true, sourceSnapshotParams, initiatorToCheck, userInvolvement, and "traverse".
    html_traversable_navigable_apply_the_history_step(this, step, true, source_snapshot_params, initiator_to_check, user_involvement, BindNavigationType.traverse, HtmlTraversableNavigableSynchronousNavigation.no, none, on_complete)

# mark: Closing top-level traversables ==========================================================

## Ported from TraversableNavigable.cpp:1600 Web::HTML::TraversableNavigable::close_top_level_traversable.
# https://html.spec.whatwg.org/multipage/document-sequences.html#close-a-top-level-traversable
pub func html_traversable_navigable_close_top_level_traversable(this: HtmlTraversableNavigable*):
    # 1. If traversable's is closing is true, then return.
    if html_navigable_is_closing(this.html_navigable()):
        return

    # AD-HOC: Set the is closing flag to prevent re-entrant calls from queuing duplicate session history steps.
    html_navigable_set_closing(this.html_navigable(), true)

    # 2. Definitely close traversable.
    html_traversable_navigable_definitely_close_top_level_traversable(this)

## definitely_close_top_level_traversable's afterAllUnloads: destroy traversable.
func html_traversable_navigable_after_all_unloads(context: void*?):
    html_traversable_navigable_destroy_top_level_traversable((HtmlTraversableNavigable*)(context else trap("no traversable")))

## definitely_close_top_level_traversable's session history traversal steps (step 3).
func html_traversable_navigable_definitely_close_steps(context: void*?, signal: CorePromise[ak.Empty, ak.AkError]*):
    let this = (HtmlTraversableNavigable*)(context else trap("no traversable"))

    # 1. Let afterAllUnloads be an algorithm step which destroys traversable.
    let after_all_unloads = gc.create_function0(gc.cell_heap(this.cell()), ak.Function0[unit](call = html_traversable_navigable_after_all_unloads, context = this))

    # 2. Unload a document and its descendants given traversable's active document, null, and afterAllUnloads.
    dom_document_unload_a_document_and_its_descendants(html_navigable_active_document(this.html_navigable()) else trap("no active document"), none, after_all_unloads)
    core_promise_resolve(signal, ak.Empty())

## definitely_close_top_level_traversable's check-if-unloading-is-canceled callback.
func html_traversable_navigable_definitely_close_checked(context: void*?, result: HtmlTraversableNavigableCheckIfUnloadingIsCanceledResult):
    let this = (HtmlTraversableNavigable*)(context else trap("no traversable"))
    if result != HtmlTraversableNavigableCheckIfUnloadingIsCanceledResult.continue_:
        return

    # 3. Append the following session history traversal steps to traversable:
    html_traversable_navigable_append_session_history_traversal_steps(this, gc.create_function1(gc.cell_heap(this.cell()), ak.Function1[CorePromise[ak.Empty, ak.AkError]*, unit](call = html_traversable_navigable_definitely_close_steps, context = this)))

## Ported from TraversableNavigable.cpp:1614 Web::HTML::TraversableNavigable::definitely_close_top_level_traversable.
# https://html.spec.whatwg.org/multipage/document-sequences.html#definitely-close-a-top-level-traversable
pub func html_traversable_navigable_definitely_close_top_level_traversable(this: HtmlTraversableNavigable*):
    assert(html_navigable_is_top_level_traversable(this.html_navigable()))

    # 1. Let toUnload be traversable's active document's inclusive descendant navigables.
    let to_unload = dom_document_inclusive_descendant_navigables(html_navigable_active_document(this.html_navigable()) else trap("no active document"))

    # 2. If the result of checking if unloading is canceled for toUnload is not "continue", then return.
    html_traversable_navigable_check_if_unloading_is_canceled_function1(this, to_unload, gc.create_function1(gc.cell_heap(this.cell()), ak.Function1[HtmlTraversableNavigableCheckIfUnloadingIsCanceledResult, unit](call = html_traversable_navigable_definitely_close_checked, context = this)))

## Ported from TraversableNavigable.cpp:1641 Web::HTML::TraversableNavigable::destroy_top_level_traversable.
# https://html.spec.whatwg.org/multipage/document-sequences.html#destroy-a-top-level-traversable
pub func html_traversable_navigable_destroy_top_level_traversable(this: HtmlTraversableNavigable*):
    assert(html_navigable_is_top_level_traversable(this.html_navigable()))

    # 1. Let browsingContext be traversable's active browsing context.
    let browsing_context = html_navigable_active_browsing_context(this.html_navigable())

    # 2. For each historyEntry in traversable's session history entries:
    # NOTE: Without bfcache, only the active document is alive, so we only need to destroy it.
    if let document = html_navigable_active_document(this.html_navigable()):
        dom_document_destroy_a_document_and_its_descendants(document)

    # 3. Remove browsingContext.
    if let context = browsing_context:
        html_browsing_context_remove(context)
    else:
        ak.dbgln("TraversableNavigable::destroy_top_level_traversable: No browsing context?")

    # 4. Remove traversable from the user interface (e.g., close or hide its tab in a tabbed browser).
    page_client_page_did_close_top_level_traversable(page_client(html_navigable_page(this.html_navigable())))

    # 5. Remove traversable from the user agent's top-level traversable set.
    with memory.heap:
        _ = ak.ordered_hash_table_remove_t(html_user_agent_top_level_traversable_set(), this)

    # FIXME: 6. Invoke WebDriver BiDi navigable destroyed with traversable.

    # FIXME: Figure out why we need to do this... we shouldn't be leaking Navigables for all time.
    #        However, without this, we can keep stale destroyed traversables around.
    html_navigable_set_has_been_destroyed(this.html_navigable())
    html_navigable_remove_from_all_navigables(this.html_navigable())

# mark: Same-document navigation ================================================================

## Ported from TraversableNavigable.cpp:1675 Web::HTML::finalize_a_same_document_navigation.
# https://html.spec.whatwg.org/multipage/browsing-the-web.html#finalize-a-same-document-navigation
pub func html_finalize_a_same_document_navigation(traversable: HtmlTraversableNavigable*, target_navigable: HtmlNavigable*, target_entry: HtmlSessionHistoryEntry*, entry_to_replace: HtmlSessionHistoryEntry*?, history_handling: HtmlHistoryHandlingBehavior, user_involvement: HtmlUserNavigationInvolvement, on_complete: gc.Function1[HtmlHistoryStepResult, unit]*):
    # NOTE: This is not in the spec but we should not navigate destroyed navigable.
    if html_navigable_has_been_destroyed(target_navigable):
        ak.function1_call(&on_complete.function, HtmlHistoryStepResult.applied)
        return

    # FIXME: 1. Assert: this is running on traversable's session history traversal queue.

    # 2. If targetNavigable's active session history entry is not targetEntry, then return.
    # FIXME: This is a workaround for a spec issue where the early return loses replace entries.
    #        Revisit when https://github.com/whatwg/html/issues/10232 is resolved.
    if html_navigable_active_session_history_entry(target_navigable) != target_entry:
        if let replaced = entry_to_replace:
            let target_entries = html_navigable_get_session_history_entries(target_navigable)
            if let index = ak.vector_find_first_index(target_entries, replaced):
                html_session_history_entry_set_step(target_entry, html_session_history_entry_step(replaced))
                *ak.vector_at(target_entries, index) = target_entry
        ak.function1_call(&on_complete.function, HtmlHistoryStepResult.applied)
        return

    # 3. Let targetStep be null.
    var target_step: i32 = 0

    # 4. Let targetEntries be the result of getting session history entries for targetNavigable.
    let target_entries = html_navigable_get_session_history_entries(target_navigable)

    # 5. If entryToReplace is null, then:
    # FIXME: Checking containment of entryToReplace should not be needed.
    #        For more details see https://github.com/whatwg/html/issues/10232#issuecomment-2037543137
    var replace_index: usize? = none
    if let replaced = entry_to_replace:
        replace_index = ak.vector_find_first_index(target_entries, replaced)
    if let index = replace_index:
        let replaced = entry_to_replace else trap("unreachable")

        # 1. Replace entryToReplace with targetEntry in targetEntries.
        *ak.vector_at(target_entries, index) = target_entry

        # 2. Set targetEntry's step to entryToReplace's step.
        html_session_history_entry_set_step(target_entry, html_session_history_entry_step(replaced))

        # 3. Set targetStep to traversable's current session history step.
        target_step = html_traversable_navigable_current_session_history_step(traversable)
    else:
        # 1. Clear the forward session history of traversable.
        html_traversable_navigable_clear_the_forward_session_history(traversable)

        # 2. Set targetStep to traversable's current session history step + 1.
        target_step = html_traversable_navigable_current_session_history_step(traversable) + 1

        # 3. Set targetEntry's step to targetStep.
        html_session_history_entry_set_step(target_entry, I32OrHtmlSessionHistoryEntryPending.i32_(target_step))

        # 4. Append targetEntry to targetEntries.
        ak.vector_append_t(target_entries, target_entry)

    # 6. Apply the push/replace history step targetStep to traversable given historyHandling and userInvolvement.
    html_traversable_navigable_apply_the_push_or_replace_history_step(traversable, target_step, history_handling, user_involvement, HtmlTraversableNavigableSynchronousNavigation.yes, none, on_complete)

# mark: System visibility and focus =============================================================

## The captures of set_system_visibility_state's task for one document.
struct HtmlTraversableNavigableUpdateVisibility:
    var visibility_state: HtmlVisibilityState
    var document: DomDocument*

## set_system_visibility_state's task: update the visibility state of the document.
func html_traversable_navigable_update_visibility_task(context: void*?):
    let captures = (HtmlTraversableNavigableUpdateVisibility*)(context else trap("no captures"))
    dom_document_update_the_visibility_state(captures.document, captures.visibility_state)

## Ported from TraversableNavigable.cpp:1737 Web::HTML::TraversableNavigable::set_system_visibility_state.
# https://html.spec.whatwg.org/multipage/interaction.html#system-visibility-state
pub func html_traversable_navigable_set_system_visibility_state(this: HtmlTraversableNavigable*, visibility_state: HtmlVisibilityState):
    if this.m_system_visibility_state == visibility_state:
        return
    this.m_system_visibility_state = visibility_state

    # When a user agent determines that the system visibility state for
    # traversable navigable traversable has changed to newState, it must run the following steps:

    # 1. Let navigables be the inclusive descendant navigables of traversable's active document.
    let navigables = dom_document_inclusive_descendant_navigables(html_navigable_active_document(this.html_navigable()) else trap("no active document"))

    # 2. For each navigable of navigables:
    for navigable in ak.vector_span_const(&navigables):
        # 1. Let document be navigable's active document.
        let document = html_navigable_active_document(navigable else trap("no navigable")) else trap("VERIFY: document")

        # 2. Queue a global task on the user interaction task source given document's relevant global object
        #    to update the visibility state of document with newState.
        let captures = new HtmlTraversableNavigableUpdateVisibility(visibility_state = visibility_state, document = document) else trap("out of memory")
        _ = html_queue_global_task(HtmlTaskSource.user_interaction, html_relevant_global_object((JsObject*)document), gc.create_function0(gc.cell_heap(this.cell()), ak.Function0[unit](call = html_traversable_navigable_update_visibility_task, context = captures)))

## Ported from TraversableNavigable.cpp:1764 Web::HTML::TraversableNavigable::currently_focused_area.
# https://html.spec.whatwg.org/multipage/interaction.html#currently-focused-area-of-a-top-level-traversable
pub func html_traversable_navigable_currently_focused_area(this: HtmlTraversableNavigable*) -> DomNode*?:
    # 1. If traversable does not have system focus, then return null.
    if not html_navigable_is_focused(this.html_navigable()):
        return none

    # 2. Let candidate be traversable's active document.
    var candidate = html_navigable_active_document(this.html_navigable()) else trap("no active document")

    # 3. While candidate's focused area is a navigable container with a non-null content navigable:
    #    set candidate to the active document of that navigable container's content navigable.
    while let focused_area = dom_document_focused_area(candidate):
        if not is_html_navigable_container(focused_area):
            break
        let content_navigable = html_navigable_container_content_navigable(as_html_navigable_container(focused_area)) else break
        candidate = html_navigable_active_document(content_navigable) else trap("no active document")

    # 4. If candidate's focused area is non-null, set candidate to candidate's focused area.
    if let focused_area = dom_document_focused_area(candidate):
        # NOTE: We return right away here instead of assigning to candidate,
        #       since that would require compromising type safety.
        return focused_area

    # 5. Return candidate.
    return candidate.dom_node()

# mark: Emulated position data ==================================================================

## Ported from TraversableNavigable.cpp:1793 Web::HTML::TraversableNavigable::emulated_position_data.
# https://w3c.github.io/geolocation/#dfn-emulated-position-data
pub func html_traversable_navigable_emulated_position_data(this: HtmlTraversableNavigable*) -> GeolocationEmulatedPositionData:
    assert(html_navigable_is_top_level_traversable(this.html_navigable()))
    return this.m_emulated_position_data

## Ported from TraversableNavigable.cpp:1800 Web::HTML::TraversableNavigable::set_emulated_position_data.
# https://w3c.github.io/geolocation/#dfn-emulated-position-data
pub func html_traversable_navigable_set_emulated_position_data(this: HtmlTraversableNavigable*, data: GeolocationEmulatedPositionData):
    assert(html_navigable_is_top_level_traversable(this.html_navigable()))
    this.m_emulated_position_data = data

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

## The captures of a screenshot's completion (`[bitmap, &client]`).
struct HtmlTraversableNavigableScreenshotDone:
    var bitmap: gfx.Bitmap*
    var client: PageClient*

## A rendered screenshot's completion: hand the bitmap to the page client.
func html_traversable_navigable_screenshot_done(context: void*?):
    let captures = (HtmlTraversableNavigableScreenshotDone*)(context else trap("no captures"))
    page_client_page_did_take_screenshot(captures.client, gfx.bitmap_to_shareable_bitmap(captures.bitmap))

## Renders `rect` of the page into a new bitmap and hands it to the client (the shared tail of
## both branches of process_screenshot_requests); false when the bitmap cannot be created.
func html_traversable_navigable_take_screenshot(this: HtmlTraversableNavigable*, client: PageClient*, rect: gfx.DevicePixelRect, paint_overlay: bool) -> bool:
    let bitmap = gfx.bitmap_create_int_size(gfx.BitmapFormat.bgra8888, gfx.device_pixel_rect_size(&rect)) else return false
    let painting_surface = gfx.painting_surface_wrap_bitmap(bitmap)
    let paint_config = HtmlPaintConfig(paint_overlay = paint_overlay, canvas_fill_rect = rect)
    let captures = new HtmlTraversableNavigableScreenshotDone(bitmap = bitmap, client = client) else trap("out of memory")
    html_navigable_render_screenshot(this.html_navigable(), painting_surface, paint_config, ak.Function0[unit](call = html_traversable_navigable_screenshot_done, context = captures))
    return true

## Ported from TraversableNavigable.cpp:1806 Web::HTML::TraversableNavigable::process_screenshot_requests.
pub func html_traversable_navigable_process_screenshot_requests(this: HtmlTraversableNavigable*):
    let page = html_navigable_page(this.html_navigable())
    let client = page_client(page)
    while not ak.queue_is_empty(&this.m_screenshot_tasks):
        let task = ak.queue_dequeue(&this.m_screenshot_tasks)
        if let node_id = task.node_id:
            let dom_node = dom_node_from_unique_id(node_id)
            if let node = dom_node:
                dom_document_update_layout(dom_node_document(node), DomUpdateLayoutReason.process_screenshot)
            if dom_node == none or dom_node_paintable_box(dom_node else trap("unreachable")) == none:
                page_client_page_did_take_screenshot(client, gfx.ShareableBitmap())
                continue
            let paintable_box = dom_node_paintable_box(dom_node else trap("unreachable")) else trap("unreachable")
            let rect = page_enclosing_device_rect(page, paint_paintable_box_absolute_border_box_rect(paintable_box))
            if not html_traversable_navigable_take_screenshot(this, client, rect, false):
                page_client_page_did_take_screenshot(client, gfx.ShareableBitmap())
                continue
        else:
            let document = html_navigable_active_document(this.html_navigable()) else trap("no active document")
            dom_document_update_layout(document, DomUpdateLayoutReason.process_screenshot)
            let viewport = dom_document_layout_node(document) else trap("no layout node")
            let scrollable_overflow_rect = paint_paintable_box_scrollable_overflow_rect(layout_box_paintable_box(viewport.layout_box()) else trap("no paintable box"))
            let rect = page_enclosing_device_rect(page, scrollable_overflow_rect else trap("Optional::value() on an empty optional"))
            if not html_traversable_navigable_take_screenshot(this, client, rect, true):
                page_client_page_did_take_screenshot(client, gfx.ShareableBitmap())
                continue