Document

This is the document section of niso_runtime.h, owned by niso-core and kept in crates/niso-core/include/document.h. The build composes it with the other sections in the order crates/niso-compose/sections.txt gives.

Functions: niso_dom_new, niso_dom_free, niso_dom_set_viewport, niso_dom_set_color_scheme, niso_dom_set_text_scale, niso_dom_set_font_weight_adjustment, niso_dom_set_system_font_weights, niso_dom_set_platform_style, niso_dom_document, niso_dom_window, niso_dom_now, niso_dom_advance_clock, niso_dom_wall_clock, niso_dom_last_error, niso_dom_set_tree_hook, niso_dom_set_task_hook, niso_dom_set_script_hook, niso_dom_set_microtask_hook, niso_dom_perform_microtask, niso_dom_begin_microtask_checkpoint, niso_dom_end_microtask_checkpoint, niso_dom_set_loader

The viewport is width x height device pixels at scale device pixels per CSS pixel.

Known limit: blitz walks a subtree that joins or leaves the document recursively, so on an 8 MiB stack, removing a connected subtree more than about 30k levels deep overflows it (repros/blitz-dom-subtree-walk-recursive). Run the DOM on a thread with a larger stack for documents that deep.

niso_dom* niso_dom_new(uint32_t width, uint32_t height, float scale);
void niso_dom_free(niso_dom* dom);
void niso_dom_set_viewport(niso_dom* dom, uint32_t width, uint32_t height, float scale);

The user’s color scheme: dark 1 or light 0, what prefers-color-scheme matches and the scheme system colors take where a page supports both. Hosts set it at start and whenever the user changes it. Light until set.

void niso_dom_set_color_scheme(niso_dom* dom, uint8_t dark);

The user’s text size (Dynamic Type, Android’s font scale), as the root font scale: the size text of each CSS font size is laid out and drawn at. points holds count (CSS px, px) pairs, the CSS px increasing and the px never decreasing, between which sizes are interpolated, and proportional to the nearest pair outside them, so a linear scale s is one pair (1, s) and a nonlinear one (Android 14’s FontScaleConverter, iOS’s text styles at the user’s size) is a few. No pairs, the default, draws text at its CSS size. Every computed font size scales; ems, rems and other lengths keep resolving against the CSS sizes, so nothing scales twice, and a line height given as a length scales with its element’s font. getComputedStyle reports the CSS sizes. Hosts set it at start and whenever the user changes it; the page is laid out again. Template text keeps its CSS size, which targets scale themselves (see niso_render_surfaces). Fails (Range) unless the pairs are positive, the CSS px increasing and the px never decreasing.

int32_t niso_dom_set_text_scale(niso_dom* dom, const float* points, size_t count);

The platform’s font weight adjustment, Android’s Configuration.fontWeightAdjustment (300 under Bold text): every font is matched and drawn at its CSS weight plus this, within 1 to 1000, as the platform’s own text views draw theirs. getComputedStyle reports the CSS weights. 0 until set. Hosts set it at start and whenever the user changes it; the page is laid out again. Fails (Range) outside -1000 to 1000.

int32_t niso_dom_set_font_weight_adjustment(niso_dom* dom, int32_t adjustment);

The weights the platform draws its system font (system-ui) at for CSS weights 100, 200, … 900, as it resolves that font itself: on Apple platforms the wght of UIFont.systemFont(ofSize:weight:) in the current trait collection, which Bold Text raises one named instance (Regular to Semibold, Bold to Black). Weights between are interpolated. count is 9, or 0 for the CSS weights, the default. Hosts set it at start and whenever the user changes it; the page is laid out again. Fails (Range) unless the weights are within 1 to 1000 and never decrease.

int32_t niso_dom_set_system_font_weights(niso_dom* dom, const float* weights, size_t count);

The host’s own user-agent style, UTF-8 CSS: the platform’s palette, type scale and shapes for the current color scheme, as custom properties on :root (–apple-system-* on Apple platforms, Material’s –md-sys-* on Android, and –niso-safe-area-inset-* on both for a page that covers the screen, see ROOT). It replaces the previous one; empty removes it. Hosts set it again whenever what it says changes. A page that wants to look native asks for niso’s platform sheet with , the first such meta in its head: ios, android or web name a platform, auto the one niso is built for (the web elsewhere), and off or anything else none, the default. The sheet is crates/niso-core/ua/niso.css’s tokens (–niso-color-, –niso-font- with –niso-tracking-, –niso-corner-, –niso-safe-*), the platform style’s properties under one set of names with web values where it has none, then that platform’s base sheet (ios.css, android.css, web.css: the page’s colors, type and margins, and overflow-wrap: break-word), all in the niso-platform cascade layer of the author origin. The meta holds it as a stylesheet link holds its sheet: the layer is declared where the meta is, any unlayered rule of the page wins over it, and the sheet follows the meta’s content and goes with the meta.

void niso_dom_set_platform_style(niso_dom* dom, const char* css, size_t len);
niso_handle niso_dom_document(niso_dom* dom);
niso_handle niso_dom_window(niso_dom* dom);

Milliseconds since the DOM was created: the time origin of event timestamps and animations. niso_dom_advance_clock skips it ahead, for virtual time.

double niso_dom_now(niso_dom* dom);
void niso_dom_advance_clock(niso_dom* dom, double ms);

Milliseconds since the Unix epoch on the same clock: the time origin (performance.timeOrigin) plus niso_dom_now, so it skips ahead with it. What a binding’s Date.now() and new Date() read, so they agree with timers.

double niso_dom_wall_clock(niso_dom* dom);
niso_str niso_dom_last_error(niso_dom* dom);
void niso_dom_set_tree_hook(niso_dom* dom, niso_tree_hook_fn hook, void* userdata);
void niso_dom_set_task_hook(niso_dom* dom, niso_task_hook_fn hook, void* userdata);
void niso_dom_set_script_hook(niso_dom* dom, niso_script_hook_fn hook, void* userdata);

Called when a call queues a microtask (to notify mutation observers or to process the backup custom element queue): the embedder queues a microtask that calls niso_dom_perform_microtask.

void niso_dom_set_microtask_hook(niso_dom* dom, niso_microtask_hook_fn hook, void* userdata);

Processes the backup custom element queue, then delivers the MutationObservers’ records to their callbacks.

int32_t niso_dom_perform_microtask(niso_dom* dom);

An embedder with microtasks brackets each microtask checkpoint it performs (HTML’s “perform a microtask checkpoint”: after each task, and after each callback the DOM calls when no script is running) with these.

void niso_dom_begin_microtask_checkpoint(niso_dom* dom);
void niso_dom_end_microtask_checkpoint(niso_dom* dom);

Where the document’s resources come from: stylesheets, fonts and other resources its CSS references, and the scripts a binding runs.

void niso_dom_set_loader(niso_dom* dom, niso_loader_fn loader, void* userdata);