Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / docs / regions / r28.md

# Region r28: Page, navigables and Window — what other regions need to know

Region r28 ports the browsing layer: `Page` and `PageClient`, `EventHandler` and its helpers (auto scroll, middle
button scroll, drag and drop, element resize), `Navigable`, `TraversableNavigable`, `NavigableContainer`,
`BrowsingContext` and `BrowsingContextGroup`, `Window`, `WindowProxy`, `Navigator` and its mixins, `DocumentState`
and `SessionHistoryEntry`, `NavigationParams`, `PolicyContainers`, `SandboxingFlagSet`, `TokenizedFeatures`,
`SessionHistoryTraversalQueue`, `SourceSnapshotParams`, `RenderingThread` and `CrossOrigin/*`. All 855 functions of
`stubs/stub_r28_html_browsing.lucb` are ported and the stub fragment is gone. `Document::create_and_initialize` now
runs end to end for a P1 HTML document: a new top-level traversable with its browsing context, then a realm whose
global object is a new `Window` and whose global this value is the browsing context's `WindowProxy`.

## Fragments

| Fragment | Donor |
| --- | --- |
| `html/sandboxing_flag_set`, `policy_containers`, `document_state`, `navigation_params`, `source_snapshot_params` | `SandboxingFlagSet`, `PolicyContainers` + `EmbedderPolicy`, `DocumentState` + `SessionHistoryEntry`, `NavigationParams` + `NavigationType.h`, `SourceSnapshotParams` |
| `html/browsing_context` | `BrowsingContext.cpp/.h`, `BrowsingContextGroup.cpp/.h` |
| `html/cross_origin/abstract_operations` | `CrossOrigin/AbstractOperations.cpp`, `Reporting.cpp` (the JS property-key operations trap P3) |
| `html/navigable_1` … `_7` | `Navigable.cpp` 1-397, 397-889, 889-1283, 1285-1804, 1806-2287, 2288-2800, 2800-3262 |
| `html/traversable_navigable_1` … `_5` | `TraversableNavigable.cpp` 1-375, 375-829, 831-1165, 1166-1564, 1564-1850 |
| `html/session_history_traversal_queue`, `rendering_thread`, `tokenized_features` | one per `.cpp` + `.h` (RenderingThread for phase 1) |
| `html/navigable_container` | `NavigableContainer.cpp/.h` (r43's `navigable_container_taken_ahead` folded in) |
| `html/window_1` … `_4` | `Window.cpp` 86-553, 553-1106, 1108-1735, 1722-2038 |
| `html/window_proxy`, `navigator` | `WindowProxy.cpp/.h`; `Navigator.cpp` and its mixins (Beacon, ConcurrentHardware, DeviceMemory, ID; Language and OnLine inline) |
| `html/window_or_worker_global_scope` | `WindowOrWorkerGlobalScope.cpp` 71-104, 538-544, 1319-1329: what Window's lifetime needs (the rest is phase 2) |
| `page/page_1`, `page_2`, `page_client` | `Page.cpp` 68-450, 451-1074 with `Page.h`'s accessors; `PageClient`'s virtuals (Page.h 371-497) |
| `page/event_handler_1` … `_5` | `EventHandler.cpp` 60-566, 567-1003, 1005-1382, 1384-1799, 1800-2173 |
| `page/auto_scroll_handler`, `drag_and_drop_event_handler`, `element_resize_action` | `AutoScrollHandler` + `MiddleButtonScrollHandler`; `DragAndDropEventHandler`; `ElementResizeAction` + `InputEvent.cpp` 14-27 |
| `html/tests_html_browsing` | tests (below) |

Taken from outside the region because phase 1 reaches them:

| Fragment | Donor |
| --- | --- |
| `content_security_policy/policy_list`, `blocking_algorithms` | `PolicyList.cpp/.h`; `BlockingAlgorithms.cpp` 398-464 and 694-738 (the inline and `<base>` checks; they answer "Allowed" over an empty CSP list) |
| `html/custom_elements/custom_element_registry` | `CustomElementRegistry.cpp` 36-54, 463-475 (a real cell with an empty definition set) |
| `fetch/infrastructure/http/responses` | `Responses.cpp` 28-43, 109-116 with `Responses.h`'s accessors (`FetchResponse` is a cell) |
| `external/lib_http/header_list` | `LibHTTP/HeaderList.cpp` 16-91 (create, contains, get, append) |
| `painting/backing_store_manager` | `BackingStoreManager.cpp` 24-36, taken ahead of **r50** |

## What other regions must know

### Construction

- A document with a window: `traversable_navigable_create_a_new_top_level_traversable` on a `Page`, then
  `dom_document_create_and_initialize(type, content_type, navigation_params)`. `html/tests_html_browsing` has
  helpers that build the response, the navigation params and the page (`test_browsing_*`). The document is
  not activated: `create_and_initialize` does not set the WindowProxy's `[[Window]]` (that happens in
  `BrowsingContext::set_active_document`, as in C++).
- Test harnesses that give a document a settings realm with a non-Window global (layout, html_elements,
  html_structure) cannot reach the CSP checks: `PolicyList::from_object` needs a Window. Any `<details>` or
  `<style>` document in those harnesses still stops there (see "Still waiting" under Tests).

### Registries (DESIGN §3.3 rule 7)

These module globals live in the C heap and hold raw pointers. Each one is mutated `with memory.heap:`, and the
cell's finalize removes itself:

- `all_windows` (C++ `GC::WeakHashSet`): removed in `Window::finalize`.
- `all_navigables`: removed in `Navigable::finalize`.
- `NavigableContainer::all_instances`: removed in `NavigableContainer::finalize`.
- The user agent's browsing context group set.
- The top-level traversable set: removed in `TraversableNavigable::finalize`, a function the donor does not have.

The only other module globals are two integer id counters.

**Changed outside the region:** r29's `EventLoop::m_related_environment_settings_objects` is now
`ak.Vector[gc.Weak[HtmlEnvironmentSettingsObject]]`. In C++ it is a raw-pointer vector. Here it was a raw-pointer
vector in managed storage, so the conservative blob scan kept every settings object alive whenever it was
registered under the VM heap, and with it every realm, Window and Document. Entries still leave in the settings
object's finalize, as with `m_documents`.

### Signatures changed from the stubs

- `html_session_history_traversal_queue_first_synchronous_navigation_steps_with_target_navigable_not_contained_in`
  takes `const HashTable*`.
- `html_check_if_a_popup_window_is_requested` and `html_get_noopener_for_window_open` take
  `const OrderedHashMap*`; the latter also takes `const web_url.Url*?`.
- `html_parse_boolean_feature[T](value, yes: T, no: T)`: the C++ template uses `T::Yes` / `T::No`.
- `html_all_windows` returns the C-heap `HashTable[HtmlWindow*]` and is private.
- `page_for_each_media_element` / `page_for_each_canvas_element` take an `ak.Function1` instead of a template
  callback.
- `spin_event_loop_until_dialog_closed` becomes `page_spin_event_loop_until_dialog_closed(client, has_response,
  response)`. The C++ template over `Optional<T>` is replaced by a has-response predicate, and Page keeps
  `m_pending_prompt_response_set` for the outer `Optional`.
- `ui_events_input_event_create_from_platform_event` (closure stub) has a new `target_ranges` parameter with a
  default.
- `realm_global_this_value(realm)` is new: the phase-1 Realm keeps `m_global_this_value` for `Window::window`,
  `self` and `frames`.

### Types filled by hand

- `types_traversable_navigable` (with its finalize).
- `types_storage_shed`: adds a placeholder word so the cell is at least the size of a free-list entry.
- `types_window`: `OpenedWindow`, `NamedObjects`, and the infinity defaults.
- `types_page`: `FindInPageResult`, `MediaContextMenu`, `m_pending_prompt_response_set`.
- `types_event_handler`: `Target`, `MouseEventCoordinates`.
- The constants of auto scroll, middle button scroll and `ChromeMetrics`.
- `types_custom_element_registry`, `types_responses`, `types_header`, `types_policy_list`.
- `BrowsingContextAndDocument` and `BrowsingContextGroupAndDocument`.
- `types_rendering_thread`, `types_source_snapshot_params`, `types_navigation_observer`.

### Where paths stop (closure stubs, "unported (Pn)")

About 115 closure stubs went into `stub_closure`, mostly in the section "Declarations outside the phase-1 closure
that region r28 calls"; their rows are in `docs/namemap.tsv`. By phase:

- **P2:** Fetch (`fetch`, controllers, request accessors); Policy, Directive and Violation operations; the CSP
  navigation checks; the timers; `window_post_message_steps`; `send_beacon`.
- **P3:** WindowProxy's exotic internal methods and the CrossOrigin property-key operations; `set_opener`'s define;
  Navigation and History events; Selection and editing.
- **P4:** Storage; Gamepad; the drag data store, `DataTransfer` and `DragEvent`; `CloseWatcherManager`.

`sdl_poll_event` returns none.

## Deviations and notes

- **RenderingThread:** runs on the main thread in phase 1. There is no thread, and it uses `DisplayListPlayerCpu`.
- **Page transition events:** plain `Event`s until `PageTransitionEvent` is ported (phase 3).
- **Never defined in the donor:** `compute_mouse_event_client_offset` and `reset_cursor_blink_cycle` are declared but
  never defined, so they trap.
- **Pixel conversions:** CSS-to-device conversions in EventHandler truncate to int.
- **PageClient:** pure virtuals trap "pure virtual: ..."; functions with default bodies answer their defaults.
- **Compiler issues:** none found. There are no `LUCE-BUG` workarounds.

## Tests

- **`html/tests_html_browsing`**, all passing:
  - **`create_and_initialize`:** a P1 HTML document with its Window, WindowProxy, browsing context and realm. Covers
    the new traversable and the initial `about:blank` document and window, the global object and global
    this value (`window`/`self`/`frames`), the settings object (responsible document, API base URL, origin), the
    document's URL, content type, readiness, and its custom element registry. Navigating by fetching stops at the
    Fetch closure stub.
  - **Base URL:** the fallback is the document URL. Of several `<base>` elements, the first with an href wins.
    Covers relative, root-relative and scheme-relative resolution, the settings object's API base URL, and the
    initial `about:blank` document.
  - **Connected `<style>` in the cascade:** the sheet is in the document's style sheets, and type, id and style
    attribute rules cascade into computed `color` and `background-color`.
  - **Full collection:** the page keeps its traversable, browsing context, WindowProxy and initial window and
    document. Releasing the document's root frees the document, its window and its element. Releasing the page's
    root frees the rest, and `all_navigables` / `all_windows` return to their sizes.
- **`page/tests_page`:** `test_page_still_unported` also matches "unported (Pn)". Its stop asserts are gone because
  the paths now run.
- **Other regions' waiting oracle cases now on (25):**
  - `layout_tree`: `<canvas>` (tree, nodes).
  - `html_elements`: `<canvas>` documents, hints and `canvas` cases; `background=` hints on
    table/td/tr/tbody; `<a href>`/`<area href>` documents and roles; `<iframe>`, `<frame>`, `<object>` documents
    and hints.
  - `html_structure`: `<meta name=referrer>`.
- **Still waiting on a Window-backed harness (CSP list):**
  - `layout_geometry`: `details-closed`, `details-open`, `details-summary-default-ua-style`.
  - `html_elements`: `<details>` document and role.
  - `html_structure`: the `details` exclusivity cases.

  Their harnesses build documents in a settings realm whose global is not a Window. Giving them documents from
  `create_and_initialize` (as `tests_html_browsing` does) unblocks them. **The P1 polish did it for the layout
  harness** (`test_layout_tree_window_realm`: documents in the realm of a test page's top-level traversable's
  Window, as the oracle makes them), so the three `layout_geometry` cases run; `html_elements` and `html_structure`
  still wait.