dymokomi/luce-browser-engine
Source of release 0.6.0
0.6.0 / 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.