blitz_script/lib.rs
1//! JavaScript execution on top of Blitz
2//!
3//! This crate implements a [`ScriptDocument`]: a wrapper around a [`BaseDocument`](blitz_dom::BaseDocument)
4//! which can execute the JavaScript contained in (or referenced by) the document's `<script>` tags
5//! using the [Boa](https://boajs.dev) JavaScript engine, and which exposes JavaScript DOM APIs
6//! (`document`, elements, events, timers, etc) backed by `blitz-dom` to the scripts it runs.
7//!
8//! It is capable of running real-world JavaScript frameworks such as [Preact](https://preactjs.com/).
9//!
10//! ### Modules
11//!
12//! `<script type="module">` is parsed in module goal and its imports are
13//! resolved and fetched through the same [`ScriptFetcher`] as classic
14//! `<script src>`, so a module graph blocks the document thread the same way a
15//! classic script already does. `<script type="importmap">`, `import.meta.url`,
16//! dynamic `import()` and JSON modules (`with { type: "json" }`) are supported;
17//! import-map `integrity` and module workers are not.
18//!
19//! ### Example
20//!
21//! ```rust
22//! use blitz_script::ScriptDocument;
23//! use blitz_dom::DocumentConfig;
24//!
25//! let mut doc = ScriptDocument::from_html(
26//! r#"
27//! <div id="root"></div>
28//! <script>
29//! const el = document.createElement("h1");
30//! el.textContent = "Hello from JS";
31//! document.getElementById("root").appendChild(el);
32//! </script>
33//! "#,
34//! DocumentConfig::default(),
35//! );
36//! doc.execute_scripts();
37//! ```
38
39#![allow(clippy::collapsible_if)]
40
41mod application_document;
42#[cfg(feature = "debug-control")]
43mod debug_control;
44mod document;
45mod docwrite;
46mod dom;
47pub mod dom_exception;
48mod domc;
49pub mod engine;
50mod event_handler;
51mod fetch;
52mod fonts;
53mod job_budget;
54pub mod media;
55mod module;
56mod raster;
57mod runtime;
58pub mod script_stats;
59mod state;
60mod timers;
61
62// Embedders extending the native script surface must use the same Boa types
63// and registry dependencies as this engine.
64pub use boa_engine;
65pub use boa_runtime;
66
67/// Drop-context collection on its current owner thread.
68pub fn collect_retired_realms() {
69 boa_gc::force_collect();
70}
71
72pub use application_document::{ApplicationDocument, ScriptBackend, ScriptDocumentBackend};
73#[cfg(feature = "debug-control")]
74pub use debug_control::DebugController;
75pub use document::ScriptDocument;
76pub use fetch::{DefaultScriptFetcher, FetchError, ScriptFetcher};
77pub use raster::raster_image_for_attribute;
78pub use runtime::{DiagnosticBatch, DiagnosticEntry, DiagnosticStreamBatch};