dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / docs / regions / r13.md
# Region r13: top level (Dump, MimeSniff, Namespace, Platform, TreeNode, ...)
Ported from Ladybird 47c82b38d0: `Dump`, `GraphemeEdgeTracker`, `Infra/JSON`, `MimeSniff/MimeType`,
`MimeSniff/Resource`, `Namespace`, `Platform/{EventLoopPlugin,FontPlugin,ImageCodecPlugin,Timer}`
and `TreeNode.h`. `Forward.h`, `InvalidateDisplayList.h`, `TraversalDecision.h` and
`TraversalOrder.h` have no functions (their types were generated).
## Fragments
| Fragment | Donor |
| --- | --- |
| `dump_1.lucb`, `dump_2.lucb` | `Dump.cpp`, `Dump.h` |
| `grapheme_edge_tracker.lucb` | `GraphemeEdgeTracker.cpp/.h` |
| `infra/json.lucb` | `Infra/JSON.cpp` |
| `external/lib_http/http.lucb` | `LibHTTP/HTTP.cpp` `collect_an_http_quoted_string`, `HTTP_WHITESPACE` (needed by MIME parsing) |
| `fetch/infrastructure/url.lucb` | `Fetch/Infrastructure/URL.cpp` `is_http_or_https_scheme` only (needed by sniffing) |
| `mime_sniff/mime_type.lucb` | `MimeSniff/MimeType.cpp/.h` |
| `mime_sniff/resource_1..3.lucb` | `MimeSniff/Resource.cpp/.h` |
| `namespace.lucb`, `initialize_strings.lucb` | `Namespace.cpp/.h`; the new `web_initialize_strings` |
| `external/lib_core/event_loop.lucb` | the Core event loop seam (see below) |
| `external/lib_core/timer.lucb` | `LibCore/Timer.cpp/.h` and the timer half of `EventReceiver.cpp` |
| `platform/*.lucb` | `Platform/*.cpp` |
| `tree_node_1.lucb`, `tree_node_2.lucb` | `TreeNode.h` |
| `tests_dump`, `tests_grapheme_edge_tracker`, `tests_mime_sniff`, `tests_namespace`, `tests_platform`, `tests_tree_node` | `Tests/LibWeb/TestMimeSniff.cpp` (ported); the rest pinned to the reference build |
`./test.sh` now runs `luce-base test src/web` after the check.
## What other regions must know
### TreeNode (r15 DOM, r18 pseudo-elements, r43 layout, r50 paintables)
- Every `tree_node_*` function takes **the T itself** (`this: T*`, `const T*` for the C++
`const` members), constrained by `HasTreeNode[T]` (`func tree() -> TreeNode[T]*`), as DESIGN
§2.5 shows; the generated stubs took `TreeNode[T]*`, which cannot reach the T
(`static_cast<T*>(this)`). `TreeNode const&` parameters are `const T*`.
`DomNode`, `LayoutNode`, `PaintPaintable` and `DomPseudoElementTreeNode` now declare
`HasTreeNode[...]` (struct lines in their types files); `tree()` is added with `extend` in
`tree_node_1.lucb`. Call them on the base: `tree_node_parent(element.dom_node())`.
- `prepend_child` also needs `TreeNodePrependHooks[T]` (`inserted_into`, `children_changed`):
only `LayoutNode` has it, forwarding to `layout_node_inserted_into` / `layout_node_children_changed`.
- Class templates (`first_child_of_type<U>`, `for_each_in_subtree_of_type<U>`, ...) take
`info: const ak.ClassInfo*` (e.g. `&html_element_class`) and answer the matching `T*`; the
caller downcasts (DESIGN §2.4). They need `T: gc.IsCell`.
- C++ callbacks are `C*` with `C: TraversalCallback[T]` (`mutating func call(node: T*) ->
TraversalDecision`) or `C: IterationCallback[T]` (`-> ak.IterationDecision`); for plain loops
the generated iterators (`dom_node_children`, ...) remain the first choice (DESIGN §2.9).
- `tree_node_visit_edges(this, visitor)` takes the T too.
- Merging r15 (DOM Node) rewrote its TreeNode calls from `tree_node_x(&node.tree_node, ...)`
to `tree_node_x(node, ...)` (and `&other.tree_node` arguments to `other`); the class-template
queries keep r15's shape (`class_info: const ak.ClassInfo*`, answering `T*?`).
### Signature and type changes
- `mime_type_parameters` returns `const OrderedHashMap*` (C++ `const&`); `mime_minimise_a_supported_mime_type`
takes `const MimeType*`; new `mime_type_copy` (the defaulted copy constructor, cloning the map).
- `mime_resource_computed_mime_type` returns `const MimeType*`; `rules_for_identifying_an_unknown_mime_type`
takes `const MimeResource*`; `parse_a_vint` returns `Anonymous` (VintResult).
- `compute_cursor_position_on_{next,previous}_line` return `usize?` (were `u64?`).
- `dump_selector_*` take `const CssSelector*` (Selector is ref-counted); `dump_session_history_entry`
takes `HtmlSessionHistoryEntry*`; the anonymous-namespace functions are private.
- `platform_event_loop_plugin_spin_until`/`deferred_invoke` keep `gc.Function0[...]*?` and VERIFY it.
- Types filled or fixed: `CoreTimer` (LibCore Timer fields + `m_timer_id`), `HtmlDocumentStateNestedHistory`
(`id`, `entries`; r28 should visit `entries` in DocumentState::visit_edges), `InfraJsonBaseValue` /
`InfraJsonValue` (new; `InfraJsonTopLevel.json_value` had been mapped to AK's `JsonValue`),
`Anonymous2` (BytePatternTableRow: `const u8[]` patterns, `str` MIME type, so the tables are
constants), `mime_s_javascript_mime_type_essence_strings` (`let str[16]`), `no_ignored_bytes`
(`let`), `PlatformGenericFontKeyTraits` (hash and equality), `platform_timer_vtable` (adds
`finalize`).
- `module.lucb` imports `memory` and `os`.
### Startup and the embedder (r28 Page, r29 event loop, r57 runner)
- **`web_initialize_strings()`** (`initialize_strings.lucb`) interns the module's static
FlyStrings; it runs `namespace_initialize_strings()` now. Regions with FlyString globals
(tag/attribute/event names, ...) add their initializer there. The embedder calls it once.
- **Core event loop seam.** LibCore is not ported; `Platform::EventLoopPlugin` and
`Core::Timer` run over `CoreEventLoopImplementation` (pump, quit, was_exit_requested,
deferred_invoke, register_timer, unregister_timer), which the embedder implements and installs
with `core_event_loop_install`. A registered timer fires by `core_timer_timer_event(timer)`.
`Platform::Timer` is allocated by `heap_allocate_platform_timer` (Timer's own cell allocator);
its `finalize` unregisters its Core timer (the C++ destructor's effect). `tests_platform.lucb`
has a scripted loop to copy.
- **FontPlugin.** It keeps a managed `Font`, and `FontDatabase::the()` (a web_fonts global) is not
scanned: the embedder keeps the plugin and the database reachable (the HANDOFF item "Root
FontDatabase::the()" stays with the embedder that owns the heap roots, r14/r57). The
constructor loads the system font directories into a PathFontProvider, as the donor does.
## Deviations and what is not ported yet
- **GC_CELL class names.** The generated vtables leave `CellVTable.class_name` at GC::Cell's pure
virtual; Dump reads the name from the cell's `ClassInfo` (`dump_class_name`), which is what
GC_CELL's `class_name()` returns. The generator should set `class_name` in every vtable.
- **Blocked on other regions' types** (trap with "unported: ... (region rNN)"):
- `measure_text_width` (GraphemeEdgeTracker) needs `Layout::TextNode::ChunkIterator`, which the
skeleton does not declare (r43);
- `dump_selector` (for a selector with compound selectors) and `dump_qualified_name` need
`CSS::Selector::CompoundSelector`/`SimpleSelector`/`QualifiedName`, opaque until r38 fills them.
- **Infra/JSON** goes through JavaScript (`%JSON.parse%`, `%JSON.stringify%`, Array/Object
creation), which comes with luce-js in P3: those steps trap "unported (P3)"; UTF-8 decoding,
encoding and the walk over the Infra value are ported.
- **Dump's cascaded properties** call `css_computed_properties_for_each_property[TCallback]` with
a `DumpTreeComputedProperty*` whose `mutating func call(property_id, value: CssStyleValue*)` is
the lambda; r40 should constrain TCallback with an interface of that shape.
- `ImageCodecPlugin`'s virtuals stay pure (an embedder subclass provides them).
- `CSSRuleList` is iterated through its `m_rules` (its begin()/end()).
## Compiler issues
- `luce-browser-tools/compiler-issues/infer_generic_through_optional_pointer.lucb`: a `U*`
argument does not infer `T` for a `T*?` parameter; `traverse_preorder[T, C](...)` is called with
its type arguments written.