Skip to main content

blitz_script/native/
runtime.rs

1//! Native guest trait implementations for the bounded Rust AST runtime.
2//!
3//! The document is borrowed for each entry into script or host work. No
4//! document pointer is retained between calls.
5
6use std::task::Context;
7
8use blitz_dom::{BaseDocument, NodeId};
9use blitz_traits::events::{BlitzPointerEvent, DomEvent, UiEvent};
10
11use crate::diagnostics::{DiagnosticBatch, DiagnosticEntry, DiagnosticStreamBatch};
12use crate::document_scripts::ScriptKind;
13use crate::native_document::{NativeDocumentRuntime, TypedNativeGuest};
14use crate::native_host::{NativeGuest, NativeHost, RealmScope, RetainedCallback};
15
16use super::*;
17
18const DIAGNOSTIC_CAPACITY: usize = 1024;
19const POLL_JOB_LIMIT: usize = 4096;
20
21/// Explicit typed-storage contract for embedders that own persistent storage.
22/// The document runtime never guesses at storage through a stringly bridge call.
23pub trait NativeStorageBridge: RuntimeBridge {
24    fn storage_get(&mut self, key: &str) -> Result<Option<Value>>;
25    fn storage_set(&mut self, key: &str, value: Value) -> Result<()>;
26    fn storage_remove(&mut self, key: &str) -> Result<()>;
27    fn storage_clear(&mut self) -> Result<()>;
28}
29
30fn stream_batch(entries: &[DiagnosticEntry], after: u64, limit: usize) -> DiagnosticStreamBatch {
31    let first = entries
32        .first()
33        .map_or(after.saturating_add(1), |entry| entry.sequence);
34    let lost = first.saturating_sub(after.saturating_add(1));
35    let selected = entries
36        .iter()
37        .filter(|entry| entry.sequence > after)
38        .take(limit)
39        .cloned()
40        .collect::<Vec<_>>();
41    let next_sequence = selected.last().map_or(after, |entry| entry.sequence);
42    DiagnosticStreamBatch {
43        entries: selected,
44        lost,
45        next_sequence,
46    }
47}
48
49impl<B: RuntimeBridge> Guest<B> {
50    /// Invoke a retained function while the owning document is borrowed.
51    pub fn invoke_retained_callback_with_document(
52        &mut self,
53        document: &mut BaseDocument,
54        callback: &RetainedCallback<u64, u64>,
55        arguments: &[Value],
56    ) -> Result<Value> {
57        if !callback.is_current_in(&self.scope()) {
58            return Err(Error::new("InvalidStateError", "stale retained callback"));
59        }
60        let value = self
61            .callbacks
62            .get(callback.callback())
63            .cloned()
64            .ok_or_else(|| Error::new("InvalidStateError", "unknown retained callback"))?;
65        let function = value
66            .as_object()
67            .and_then(|object| object.borrow().function.clone())
68            .ok_or_else(|| Error::type_error("retained value is no longer callable"))?;
69        self.begin_execution();
70        self.call_function(
71            document,
72            function,
73            Value::Undefined,
74            arguments.to_vec(),
75            false,
76        )
77    }
78
79    fn bridge_poll(
80        &mut self,
81        document: &mut BaseDocument,
82        context: Option<&Context<'_>>,
83        run_timers: bool,
84    ) -> Result<bool> {
85        if self.disposed || self.frozen {
86            return Ok(false);
87        }
88        let _scope = value::HeapScope::enter(&self.heap);
89        self.begin_execution();
90        document.handle_messages();
91        self.web_poll(document)?;
92        let resource_work = self.dispatch_resource_events(document)?;
93        let outcomes = document.take_image_load_outcomes();
94        let queued_resources = !outcomes.is_empty();
95        for (node, _generation, loaded) in outcomes {
96            let Some(element) = document.get_node(node).and_then(|node| node.element_data()) else {
97                continue;
98            };
99            let source = element
100                .attr(blitz_dom::local_name!("src"))
101                .unwrap_or("")
102                .to_owned();
103            self.queue_resource_event(
104                document,
105                node,
106                &source,
107                if loaded { "load" } else { "error" },
108            );
109        }
110        let jobs =
111            self.bridge
112                .poll(document, context.map(|current| current.waker()), run_timers)?;
113        let did_work = !jobs.is_empty() || !self.jobs.is_empty();
114        self.jobs.extend(jobs);
115        let drained = self.drain_jobs(document, POLL_JOB_LIMIT)?;
116        self.web_poll(document)?;
117        Ok(resource_work || queued_resources || did_work || drained)
118    }
119
120    fn dispatch_lifecycle_event(&mut self, document: &mut BaseDocument, name: &str) -> Result<()> {
121        let event = Value::object("Event");
122        event.put("type", Value::string(name));
123        event.put("bubbles", Value::Bool(false));
124        event.put("cancelable", Value::Bool(false));
125        let document_value = self.global.get("document");
126        let _ = self.dispatch_event(document, document_value, event.clone())?;
127        let _ = self.dispatch_event(document, self.global.clone(), event)?;
128        Ok(())
129    }
130
131    fn sync_document_state(&mut self) {
132        let document = self.global.get("document");
133        if document.kind() != "Undefined" {
134            document.put("readyState", Value::string(&self.ready_state));
135            document.put(
136                "visibilityState",
137                Value::string(if self.visible { "visible" } else { "hidden" }),
138            );
139        }
140    }
141}
142
143impl<B: RuntimeBridge> NativeGuest for Guest<B> {
144    type Value = Value;
145    type RealmId = u64;
146    type CallbackId = u64;
147    type Error = Error;
148
149    fn scope(&self) -> RealmScope<Self::RealmId> {
150        RealmScope::new(self.scope_id, self.generation)
151    }
152
153    fn retain_callback(
154        &mut self,
155        callback: &Self::Value,
156    ) -> Result<RetainedCallback<Self::RealmId, Self::CallbackId>, Self::Error> {
157        if self.disposed
158            || callback
159                .as_object()
160                .and_then(|object| object.borrow().realm)
161                .is_some_and(|realm| realm != self.scope_id)
162        {
163            return Err(Error::new(
164                "InvalidStateError",
165                "callback does not belong to the active realm",
166            ));
167        }
168        let callable = callback.kind() == "Function"
169            || callback
170                .as_object()
171                .is_some_and(|object| object.borrow().function.is_some());
172        if !callable {
173            return Err(Error::type_error("retained callback must be callable"));
174        }
175        let id = self.next_callback;
176        self.next_callback = id.checked_add(1).ok_or_else(|| {
177            Error::new("QuotaExceededError", "callback identifier space exhausted")
178        })?;
179        self.callbacks.insert(id, callback.clone());
180        Ok(RetainedCallback::new(self.scope_id, self.generation, id))
181    }
182
183    fn release_callback(
184        &mut self,
185        callback: &RetainedCallback<Self::RealmId, Self::CallbackId>,
186    ) -> Result<(), Self::Error> {
187        if !callback.is_current_in(&self.scope()) {
188            return Err(Error::new("InvalidStateError", "stale retained callback"));
189        }
190        self.callbacks
191            .remove(callback.callback())
192            .map(|_| ())
193            .ok_or_else(|| Error::new("InvalidStateError", "unknown retained callback"))
194    }
195
196    fn register_intrinsic(
197        &mut self,
198        name: &'static str,
199        _arity: u8,
200        callback: NativeIntrinsic<Self>,
201    ) -> Result<(), Self::Error> {
202        self.intrinsics.insert(name.to_owned(), callback);
203        Ok(())
204    }
205
206    fn invoke_retained_callback(
207        &mut self,
208        callback: &RetainedCallback<Self::RealmId, Self::CallbackId>,
209        _arguments: &[Self::Value],
210    ) -> Result<Self::Value, Self::Error> {
211        if !callback.is_current_in(&self.scope()) {
212            return Err(Error::new("InvalidStateError", "stale retained callback"));
213        }
214        if !self.callbacks.contains_key(callback.callback()) {
215            return Err(Error::new("InvalidStateError", "unknown retained callback"));
216        }
217        Err(Error::new(
218            "InvalidStateError",
219            "retained guest callback requires an explicit live document borrow",
220        ))
221    }
222}
223
224impl<B: RuntimeBridge + NativeStorageBridge> TypedNativeGuest for Guest<B> {
225    fn supports_intl(&self) -> bool {
226        self.global.get("Intl").kind() == "Intl"
227            && self.global.get("Intl").get("NumberFormat").kind() == "Native"
228    }
229
230    fn supports_import_maps(&self) -> bool {
231        false
232    }
233
234    fn supports_modules(&self) -> bool {
235        true
236    }
237
238    fn install_document(&mut self, document: &mut BaseDocument) -> Result<(), Self::Error> {
239        if self.disposed {
240            return Err(Error::new("InvalidStateError", "guest has been disposed"));
241        }
242        self.bridge.install(&self.global)?;
243        // install_dom owns the Document-kind realm object. Attach the live root
244        // identity to that object so DOM dispatch keeps its Document semantics.
245        let document_value = self.global.get("document");
246        if document_value.kind() != "Document" {
247            return Err(Error::new(
248                "InvalidStateError",
249                "DOM document binding was not installed",
250            ));
251        }
252        document_value.put_hidden(
253            "__node",
254            Value::string(document.root_node().id.as_u64().to_string()),
255        );
256        self.nodes
257            .insert(document.root_node().id, document_value.clone());
258        self.global.put("window", self.global.clone());
259        self.global.put("self", self.global.clone());
260        self.global.put("globalThis", self.global.clone());
261        self.ready_state = "loading".to_owned();
262        self.sync_document_state();
263        Ok(())
264    }
265
266    fn execute_source(
267        &mut self,
268        document: &mut BaseDocument,
269        source: &str,
270        _source_url: Option<&url::Url>,
271        kind: &ScriptKind,
272    ) -> Result<(), Self::Error> {
273        self.begin_execution();
274        match kind {
275            ScriptKind::Classic => self.evaluate(document, source).map(|_| ()),
276            // The bounded parser admits module bodies that use its supported
277            // statement grammar. Imports and exports remain syntax errors.
278            ScriptKind::Module => self.evaluate(document, source).map(|_| ()),
279            ScriptKind::ImportMap => {
280                Err(Error::syntax("import maps are not supported by this guest"))
281            }
282        }
283    }
284
285    fn install_import_map(
286        &mut self,
287        _source: &str,
288        _base_url: Option<&url::Url>,
289    ) -> Result<(), Self::Error> {
290        Err(Error::syntax("import maps are not supported by this guest"))
291    }
292
293    fn dispatch_ui_event(
294        &mut self,
295        document: &mut BaseDocument,
296        event: UiEvent,
297    ) -> Result<(), Self::Error> {
298        self.begin_execution();
299        self.dispatch_input(document, event, None)
300    }
301
302    fn poll(
303        &mut self,
304        document: &mut BaseDocument,
305        context: Option<Context<'_>>,
306    ) -> Result<bool, Self::Error> {
307        self.bridge_poll(document, context.as_ref(), true)
308    }
309
310    fn poll_for_settle(
311        &mut self,
312        document: &mut BaseDocument,
313        context: Option<Context<'_>>,
314        run_timers: bool,
315    ) -> Result<bool, Self::Error> {
316        self.bridge_poll(document, context.as_ref(), run_timers)
317    }
318
319    fn prepare_teardown(&mut self, _document: &mut BaseDocument) -> Result<(), Self::Error> {
320        self.frozen = true;
321        Ok(())
322    }
323
324    fn dispose_document(&mut self, _document: &mut BaseDocument) -> Result<(), Self::Error> {
325        if !self.disposed {
326            self.disposed = true;
327            self.bridge.teardown();
328            self.jobs.clear();
329            self.callbacks.clear();
330            self.nodes.clear();
331            self.ipc_handler = None;
332            self.global = Value::Undefined;
333        }
334        Ok(())
335    }
336
337    fn finish_loading(&mut self, document: &mut BaseDocument) -> Result<(), Self::Error> {
338        self.begin_execution();
339        self.ready_state = "interactive".to_owned();
340        self.sync_document_state();
341        self.dispatch_lifecycle_event(document, "DOMContentLoaded")?;
342        self.ready_state = "complete".to_owned();
343        self.sync_document_state();
344        self.dispatch_lifecycle_event(document, "load")
345    }
346
347    fn set_page_visible(
348        &mut self,
349        document: &mut BaseDocument,
350        visible: bool,
351    ) -> Result<(), Self::Error> {
352        self.begin_execution();
353        self.visible = visible;
354        self.sync_document_state();
355        self.dispatch_lifecycle_event(document, "visibilitychange")
356    }
357
358    fn freeze(&mut self, document: &mut BaseDocument) -> Result<(), Self::Error> {
359        self.begin_execution();
360        self.dispatch_lifecycle_event(document, "freeze")?;
361        self.frozen = true;
362        Ok(())
363    }
364
365    fn finish_restore(&mut self, document: &mut BaseDocument) -> Result<(), Self::Error> {
366        self.begin_execution();
367        self.frozen = false;
368        self.dispatch_lifecycle_event(document, "pageshow")
369    }
370
371    fn resume(&mut self, document: &mut BaseDocument) -> Result<(), Self::Error> {
372        self.begin_execution();
373        self.frozen = false;
374        self.dispatch_lifecycle_event(document, "resume")?;
375        let _ = self.bridge_poll(document, None, false)?;
376        Ok(())
377    }
378
379    fn storage_get(&mut self, key: &str) -> Result<Option<Self::Value>, Self::Error> {
380        self.bridge.storage_get(key)
381    }
382
383    fn storage_set(&mut self, key: &str, value: Self::Value) -> Result<(), Self::Error> {
384        self.bridge.storage_set(key, value)
385    }
386
387    fn storage_remove(&mut self, key: &str) -> Result<(), Self::Error> {
388        self.bridge.storage_remove(key)
389    }
390
391    fn storage_clear(&mut self) -> Result<(), Self::Error> {
392        self.bridge.storage_clear()
393    }
394}
395
396impl<B: RuntimeBridge + NativeStorageBridge> NativeDocumentRuntime for Guest<B> {
397    fn eval_named(
398        &mut self,
399        document: &mut BaseDocument,
400        source: &str,
401        _name: &str,
402    ) -> Result<(), Self::Error> {
403        self.begin_execution();
404        self.evaluate(document, source).map(|_| ())
405    }
406
407    fn eval_json(
408        &mut self,
409        document: &mut BaseDocument,
410        source: &str,
411    ) -> Result<serde_json::Value, Self::Error> {
412        self.begin_execution();
413        self.evaluate(document, source)?.to_json()
414    }
415
416    fn has_pending_jobs(&self) -> bool {
417        !self.jobs.is_empty() || self.bridge.has_pending_jobs()
418    }
419
420    fn pending_task_count(&self) -> u64 {
421        self.jobs.len() as u64 + self.bridge.pending_task_count()
422    }
423
424    fn diagnostic_batch(
425        &self,
426        console_after: u64,
427        errors_after: u64,
428        limit: usize,
429    ) -> Result<DiagnosticBatch, Self::Error> {
430        let limit = limit.min(DIAGNOSTIC_CAPACITY);
431        Ok(DiagnosticBatch {
432            console: stream_batch(&self.console, console_after, limit),
433            errors: stream_batch(&self.errors, errors_after, limit),
434        })
435    }
436
437    fn dispatch_dom_event(
438        &mut self,
439        document: &mut BaseDocument,
440        event: DomEvent,
441    ) -> Result<(), Self::Error> {
442        self.begin_execution();
443        self.dispatch_native_event(document, event)
444    }
445
446    fn handle_pointer_move_to_node(
447        &mut self,
448        document: &mut BaseDocument,
449        event: BlitzPointerEvent,
450        node: NodeId,
451    ) -> Result<(), Self::Error> {
452        self.begin_execution();
453        self.dispatch_input(document, UiEvent::PointerMove(event), Some(node))
454    }
455
456    fn handle_ui_event_to_node(
457        &mut self,
458        document: &mut BaseDocument,
459        event: UiEvent,
460        node: NodeId,
461    ) -> Result<(), Self::Error> {
462        self.begin_execution();
463        self.dispatch_input(document, event, Some(node))
464    }
465
466    fn dispatch_node_event(
467        &mut self,
468        document: &mut BaseDocument,
469        node: NodeId,
470        name: &str,
471    ) -> Result<bool, Self::Error> {
472        self.begin_execution();
473        if document.get_node(node).is_none() {
474            return Err(Error::new(
475                "NotFoundError",
476                "event target node no longer exists",
477            ));
478        }
479        let event = Value::object("Event");
480        event.put("type", Value::string(name));
481        event.put("bubbles", Value::Bool(true));
482        event.put("cancelable", Value::Bool(true));
483        let target = self.node(node);
484        self.dispatch_event(document, target, event)
485    }
486
487    fn set_ipc_handler(&mut self, handler: Box<dyn Fn(String)>) -> Result<(), Self::Error> {
488        if self.disposed {
489            return Err(Error::new("InvalidStateError", "guest has been disposed"));
490        }
491        self.ipc_handler = Some(handler);
492        let ipc = Value::object("IPC");
493        ipc.put("postMessage", Value::native("IPC.postMessage"));
494        self.global.put("ipc", ipc);
495        Ok(())
496    }
497}
498
499impl<B: RuntimeBridge> NativeHost for GuestHost<B> {
500    type Guest = Guest<B>;
501
502    fn guest(&self) -> &Self::Guest {
503        &self.0
504    }
505
506    fn guest_mut(&mut self) -> &mut Self::Guest {
507        &mut self.0
508    }
509}