eframe web: detect and report panics during startup (#2992)

* Detect panics during initialization and show them to the user

* PanicHandler now also logs the panics

* Add example of how to call into your app from JS

* Refactor: break out AppRunner and AppRunnerRef to own files

* Hide AppRunner

* Simplify user code

* AppRunnerRef -> WebRunner

* Better docs

* Don't paint until first animation frame

* Update multiple_apps.html

* Update web demo

* Cleanup and fixes

* left-align panic message in html

crates/eframe/src/lib.rs

@@ -42,15 +42,74 @@
 //!
 //! ## Usage, web:
 //! ``` no_run
-//! #[cfg(target_arch = "wasm32")]
+//! # #[cfg(target_arch = "wasm32")]
 //! use wasm_bindgen::prelude::*;
 //!
-//! /// Call this once from the HTML.
-//! #[cfg(target_arch = "wasm32")]
+//! /// Your handle to the web app from JavaScript.
+//! # #[cfg(target_arch = "wasm32")]
+//! #[derive(Clone)]
 //! #[wasm_bindgen]
-//! pub async fn start(canvas_id: &str) -> Result<AppRunnerRef, eframe::wasm_bindgen::JsValue> {
-//!     let web_options = eframe::WebOptions::default();
-//!     eframe::start_web(canvas_id, web_options, Box::new(|cc| Box::new(MyEguiApp::new(cc)))).await
+//! pub struct WebHandle {
+//!     runner: WebRunner,
+//! }
+//!
+//! # #[cfg(target_arch = "wasm32")]
+//! #[wasm_bindgen]
+//! impl WebHandle {
+//!     /// Installs a panic hook, then returns.
+//!     #[allow(clippy::new_without_default)]
+//!     #[wasm_bindgen(constructor)]
+//!     pub fn new() -> Self {
+//!         // Redirect [`log`] message to `console.log` and friends:
+//!         eframe::web::WebLogger::init(log::LevelFilter::Debug).ok();
+//!
+//!         Self {
+//!             runner: WebRunner::new(),
+//!         }
+//!     }
+//!
+//!     /// Call this once from JavaScript to start your app.
+//!     #[wasm_bindgen]
+//!     pub async fn start(&self, canvas_id: &str) -> Result<(), wasm_bindgen::JsValue> {
+//!         self.runner
+//!             .start(
+//!                 canvas_id,
+//!                 eframe::WebOptions::default(),
+//!                 Box::new(|cc| Box::new(MyEguiApp::new(cc))),
+//!             )
+//!             .await
+//!     }
+//!
+//!     // The following are optional:
+//!
+//!     #[wasm_bindgen]
+//!     pub fn destroy(&self) {
+//!         self.runner.destroy();
+//!     }
+//!
+//!     /// Example on how to call into your app from JavaScript.
+//!     #[wasm_bindgen]
+//!     pub fn example(&self) {
+//!         if let Some(app) = self.runner.app_mut::<MyEguiApp>() {
+//!             app.example();
+//!         }
+//!     }
+//!
+//!     /// The JavaScript can check whether or not your app has crashed:
+//!     #[wasm_bindgen]
+//!     pub fn has_panicked(&self) -> bool {
+//!         self.runner.has_panicked()
+//!     }
+//!
+//!     #[wasm_bindgen]
+//!     pub fn panic_message(&self) -> Option<String> {
+//!         self.runner.panic_summary().map(|s| s.message())
+//!     }
+//!
+//!     #[wasm_bindgen]
+//!     pub fn panic_callstack(&self) -> Option<String> {
+//!         self.runner.panic_summary().map(|s| s.callstack())
+//!     }
 //! }
 //! ```
 //!
@@ -91,7 +150,7 @@ pub use web_sys;
 pub mod web;
 
 #[cfg(target_arch = "wasm32")]
-pub use web::start_web;
+pub use web::WebRunner;
 
 // ----------------------------------------------------------------------------
 // When compiling natively