browser library

Browser-only entry point for Bloom JS Native.

The core library (package:bloom_js_native/bloom_js_native.dart) is pure Dart — descriptor trees, HTML rendering, npm registry, router matching — so it loads and tests on the plain VM. This library adds the real-DOM backend (package:web + dart:js_interop).

Web apps import both:

import 'package:bloom_js_native/bloom_js_native.dart';
import 'package:bloom_js_native/browser.dart';

void main() {
  mount(App(), '#app');
}

Classes

BloomIsland
Emits a server-rendered island placeholder element configured with the given hydration strategy and props.
BloomIslandDefinition
Specification of a registered island component definition.
BloomIslandInstance
Represents an individual island placeholder element discovered in the browser DOM.
BloomIslandOrchestrator
Orchestrates discovery, hydration strategy evaluation, and lifecycle management for Bloom islands.
BloomIslandRegistry
Registry storing client-side island builders keyed by name.
BloomMountHandle
Handle representing an active Bloom application mounted in the browser DOM.
BloomRouterController
Client-side router controller using the HTML5 History API.
BloomVirtualItem
Represents a single visible row or item calculated by BloomVirtualizer.
BloomVirtualizer
Reactive list virtualization engine wrapping vendored @tanstack/virtual-core.
BrowserRealtimeClient
Browser-only BloomRealtimeChannelClient backed by native browser WebSockets (package:web).
CustomElementContext
Context provided to the component builder inside defineCustomElement.
CustomElementEvent<T>
A strongly-typed event wrapper for custom element DOM events carrying a deserialized detail payload.

Enums

HydrationStrategy
Hydration trigger strategies for Bloom islands.
IslandStatus
Lifecycle status of an island instance managed by BloomIslandOrchestrator.

Constants

bloomHydratedAttribute → const String
DOM attribute name added to an island placeholder element once hydration is complete.
bloomIslandAttribute → const String
DOM attribute name used to identify an island placeholder and specify its registered name.
bloomMediaAttribute → const String
DOM attribute name specifying the CSS media query string for HydrationStrategy.media.
bloomPropsAttribute → const String
DOM attribute name containing JSON-encoded props passed to the island's BloomIslandBuilder.
bloomRootMarginAttribute → const String
DOM attribute name specifying the rootMargin CSS string for the HydrationStrategy.visible observer.
bloomStrategyAttribute → const String
DOM attribute name specifying the HydrationStrategy for an island placeholder.
defaultRealtimeBackoffMultiplier → const double
Default exponential backoff multiplier applied on consecutive reconnection failures.
defaultRealtimeInitialReconnectDelay → const Duration
Default initial reconnection delay before the first retry attempt (500ms).
defaultRealtimeMaxReconnectDelay → const Duration
Default maximum delay ceiling for exponential reconnection backoff (30s).
defaultRealtimePingInterval → const Duration
Default keep-alive heartbeat ping interval (30s).

Properties

bloomDevErrorOverlayEnabled ↔ bool
When true, uncaught errors thrown while mounting or rendering a tree display a full-screen visual error overlay (renderDevErrorOverlay) in the browser DOM instead of propagating and throwing.
getter/setter pair
bloomHotReloadTrackingEnabled ↔ bool
When true, active mounted applications (BloomMountHandle) are tracked to enable clean in-page teardown and remounting during hot reload development cycles.
getter/setter pair
bloomStyleNonce ↔ String?
Optional Content-Security-Policy (CSP) nonce applied to <style> elements created and injected by the framework.
getter/setter pair

Functions

attachBloomListener(Element el, String type, BloomEventHandler handler) → void
Attaches a synthetic BloomEvent listener of the given type to DOM element el.
bloomDisposeActiveMount() → void
Disposes the currently active mounted application tracked by development hot reload, tearing down its DOM elements, disposing all reactive signal effects, and clearing the active mount handle reference.
bloomIsland({required String name, BloomNode? child, List<BloomNode>? children, HydrationStrategy strategy = HydrationStrategy.immediate, Map<String, dynamic>? props, String? rootMargin, String? media, String tag = 'div', String? className, String? style, Map<String, String>? attrs}) → BloomIsland
Helper function to construct a BloomIsland placeholder descriptor.
browserRealtimeClient({required Uri uri, Duration initialReconnectDelay = defaultRealtimeInitialReconnectDelay, Duration maxReconnectDelay = defaultRealtimeMaxReconnectDelay, double backoffMultiplier = defaultRealtimeBackoffMultiplier, bool autoReconnect = true, Duration pingInterval = defaultRealtimePingInterval, List<String>? protocols}) → BrowserRealtimeClient
Convenience factory for creating a BrowserRealtimeClient.
customElement(String tag, {Map<String, Object?>? properties, Map<String, String>? attrs, String? className, String? style, Map<String, CustomElementEventHandler>? events, Map<String, BloomEventHandler>? on, List<BloomNode> children = const [], String? text, Ref<Element>? ref, bool waitForUpgrade = true, Duration upgradeTimeout = const Duration(seconds: 3)}) → BloomNode
Creates a BloomNode representing a browser Custom Element / Web Component with reactive property bindings, custom event listeners, and SSR attribute support.
dartToJsValue(Object? value) → JSAny?
Converts a Dart value into its corresponding JavaScript interop representation (JSAny).
defineCustomElement(String tagName, BloomNode builder(CustomElementContext context), {List<String> observedAttributes = const [], bool useShadowDom = true, String shadowMode = 'open'}) → void
Registers a native browser Custom Element with tagName backed by a Bloom descriptor tree.
extractIslandProps(Element element) → Map<String, dynamic>
Extracts decoded props from an island placeholder element.
hydrate(BloomNode root, String selector) → BloomMountHandle
Hydrates a server-rendered DOM tree matching selector with event listeners in place.
hydrateElement(BloomNode root, Element element) → BloomMountHandle
Hydrates a server-rendered DOM tree inside element with event listeners in place.
isHotReloadTrackingActive() → bool
Determines whether hot-reload active-mount tracking is currently active.
jsToDartValue(JSAny? jsVal) → Object?
Converts a JavaScript interop value (JSAny) into its corresponding idiomatic Dart representation.
mount(BloomNode node, String selector) → BloomMountHandle
Mounts a BloomNode descriptor tree into the DOM element matching selector.
mountToElement(BloomNode node, Element root) → BloomMountHandle
Mounts a BloomNode descriptor tree directly into the provided DOM root element.
orchestrateIslands({BloomIslandRegistry? registry, Element? rootElement, String defaultRootMargin = '200px'}) → BloomIslandOrchestrator
Boots and starts an island orchestrator managing client-side island hydration.
registerIsland(String name, BloomIslandBuilder builder, {HydrationStrategy defaultStrategy = HydrationStrategy.immediate}) → void
Registers an island builder in the default global BloomIslandRegistry.instance.
unregisterIsland(String name) → bool
Removes an island definition by name from the global BloomIslandRegistry.instance.
whenCustomElementDefined(String tag, {Duration timeout = const Duration(seconds: 3)}) → Future<void>
Asynchronously waits for a custom element tag to be registered and upgraded in the browser's CustomElementRegistry.

Typedefs

BloomIslandBuilder = BloomNode Function(Map<String, dynamic> props)
Builder function that instantiates a BloomNode tree for an island, given its decoded props.
CustomElementEventHandler<T> = void Function(CustomElementEvent<T> event)
Handler callback signature for custom element events carrying a deserialized detail payload.