1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
//! Browser-side runtime for Krab's island architecture.
//!
//! Krab renders a page on the server and ships it as HTML. Only the
//! interactive parts — *islands* — are then brought to life in the browser by
//! this crate. It is the WASM half of the framework: it adopts the
//! server-rendered DOM instead of rebuilding it, wires event listeners onto the
//! nodes that are already there, and keeps [`Node::Dynamic`] regions in sync
//! with the reactive graph re-exported from `krab_core`.
//!
//! # The `web` feature
//!
//! Everything that touches the DOM is behind the `web` feature. Without it the
//! crate still compiles — so a workspace-wide `cargo check` on the host target
//! succeeds — but [`hydrate`] does nothing and the DOM entry points below are
//! not compiled at all. Anything built for the browser must enable `web`.
//!
//! The optional `debug` feature adds informational `console.log` tracing of the
//! hydration pass. Warnings and errors are always reported; `debug` only
//! controls the chatter, so production bundles stay quiet.
//!
//! # The hydration model
//!
//! The server emits each island as an element carrying `data-island` (the
//! registered component name), `data-props` (its JSON props), and a
//! `data-krab-boundary-id`. [`hydrate`] finds those elements, rebuilds each
//! island's virtual tree by calling the factory registered for its name, and
//! walks that tree against the live DOM:
//!
//! - a matching element is **reused**, and its listeners are attached to it;
//! - a text node whose content differs is **patched in place**, which is what
//! lets a selection or an IME composition survive hydration;
//! - only a genuine shape mismatch causes a node to be replaced.
//!
//! Every boundary is stamped with the outcome — `data-krab-boundary-state`
//! (`ok`, `patched`, `error`, `missing-definition`, …) and
//! `data-krab-boundary-mismatches` — so monitoring can see a drifting boundary
//! without reading the console.
//!
//! That stamp is also what makes hydration **idempotent**. The server ships
//! `data-krab-boundary-state="ssr"`; a boundary whose state has moved off `ssr`
//! is skipped, so a second pass cannot bind a second copy of every handler.
//! [`unmount`] reverses a pass — releasing event closures and dynamic-region
//! effects, and clearing the stamp — so `unmount` followed by
//! [`hydrate_within`] is a supported re-hydration cycle.
//!
//! # Usage
//!
//! Islands register themselves; the application only has to call [`hydrate`]
//! once the WASM module is loaded.
//!
//! ```ignore
//! use krab_client::{create_signal, hydrate};
//! use krab_macros::{island, view};
//!
//! #[island]
//! fn Counter(start: i32) -> Node {
//! let (count, set_count) = create_signal(start);
//! view! {
//! <button on:click={move |_| set_count.set(count.get() + 1)}>
//! {move || count.get().to_string()}
//! </button>
//! }
//! }
//!
//! // Exported entry point, called by the page's module script once the WASM
//! // module is instantiated. NOT `#[wasm_bindgen(start)]`: `krab_client`
//! // already owns the bundle's single start function, and a second one is a
//! // wasm-bindgen error.
//! #[wasm_bindgen]
//! pub fn krab_boot() {
//! hydrate();
//! }
//! ```
//!
//! The page loads it from a same-origin module file (an inline script is
//! blocked by Krab's CSP, `script-src 'self' 'wasm-unsafe-eval'`):
//!
//! ```js
//! import init, { krab_boot } from '/pkg/my_app.js';
//! init().then(() => krab_boot());
//! ```
//!
//! `examples/reference_apps/islands_rpc` does exactly this, and also starts the
//! client router after hydrating.
//!
//! To bring up a fragment that arrived after the initial load — a modal, a
//! client-routed view — hydrate just that subtree, and release it when it goes
//! away:
//!
//! ```ignore
//! krab_client::hydrate_within(&panel);
//! // …later…
//! krab_client::unmount(&panel);
//! panel.remove();
//! ```
extern crate self as krab_client;
use Node;
use *;
use console;
// The runtime is split along the seams it already had inside one file:
//
// - `hydration` walks server-rendered islands and stamps each boundary;
// - `reconcile` builds and patches DOM for `Node::Dynamic` regions after
// hydration, and is the only code that creates DOM from a vnode;
// - `resources` owns the two registries both of them write to — event-listener
// closures and live dynamic regions — and releases them.
//
// Only `hydration` exists without `web`, because `hydrate()` is a `#[wasm_bindgen]`
// export that must link (as a no-op) in a build that leaves the DOM out.
// Per-island panic isolation: the JS `try`/`catch` trampoline and the panic
// hook that records what trapped. Only wasm32 needs it — everywhere else
// unwinding is real and `catch_unwind` does the job.
pub use hydrate;
pub use ;
pub use build_dom_for_test;
pub use ;
pub use *;
// Re-exported from `krab_core` so an island reaches it without importing a
// second crate. The type is transport-independent and lives there.
pub use ;
pub use ;
/// Spawn a future on the browser's task queue.
///
/// Island event handlers are synchronous — `on:click` takes an `FnMut(Event)` —
/// but `#[server]` functions are `async` on the client, where the call becomes a
/// `fetch`. This is the bridge.
///
/// ```ignore
/// on:click={
/// move |_| {
/// krab_client::spawn(async move {
/// let _ = add_task("from the island".to_string()).await;
/// });
/// }
/// }
/// ```
///
/// Before this existed, the reference application and the getting-started guide
/// both told users to write the `cfg` and the transport by hand:
///
/// ```ignore
/// #[cfg(target_arch = "wasm32")]
/// wasm_bindgen_futures::spawn_local(async move { … });
/// ```
///
/// which leaks the transport into application code and does not compile off
/// wasm32.
///
/// # Scope
///
/// This is a browser task spawner, and it lives in `krab_client` because that
/// crate is browser-only by construction. It is deliberately **not** in
/// `krab_core`: the future here captures signals and is therefore `!Send`, and
/// inventing a native spawning story for a `!Send` future — a `LocalSet`, or a
/// silent no-op — would be a worse answer than not offering one.
///
/// For richer needs (pending state, error handling, cancellation) this is the
/// primitive that `Action`-style async state is built on.
// Function type for creating a component from JSON props
pub type ComponentFactory = fn ;
// Register the inventory
collect!;