@actrium/actr-dom
v0.4.0
Published
Actrium browser DOM-side fixed forwarding layer
Downloads
2,012
Readme
@actrium/actr-dom
Actor-RTC DOM-side Fixed Forwarding Layer
This package is the fixed JavaScript layer provided by the Actor-RTC framework. It acts as a hardware-abstraction-style bridge for DOM-side WebRTC management and data forwarding.
Design Philosophy
DOM side = "network driver", Service Worker side = "application code"
All user business logic lives in the Service Worker runtime, typically in WASM. The DOM side is a fixed framework-provided implementation that users are not expected to modify.
Core Responsibilities
- WebRTC connection management: create and manage
RTCPeerConnectioninstances, which are only available in DOM contexts - Fast Path data forwarding: forward data received from WebRTC DataChannels to the Service Worker with minimal copying
- PostMessage bridge: provide bidirectional communication between the DOM and the Service Worker
Installation
npm install @actrium/actr-domUsage
Basic Usage
import { initActrDom } from '@actrium/actr-dom';
// Initialize the DOM runtime
const runtime = await initActrDom({
serviceWorkerUrl: '/my-actor.sw.js', // Service Worker script path
webrtcConfig: {
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
},
});
console.log('Actor-RTC DOM runtime initialized');
// The runtime automatically:
// 1. Registers the Service Worker
// 2. Establishes PostMessage communication
// 3. Listens for WebRTC commands from the SW
// 4. Forwards Fast Path data back to the SWHTML Usage
<!DOCTYPE html>
<html>
<head>
<title>Actor-RTC App</title>
</head>
<body>
<div id="app"></div>
<!-- Load the DOM runtime -->
<script type="module">
import { initActrDom } from 'https://cdn.example.com/@actrium/actr-dom/dist/index.js';
const runtime = await initActrDom({
serviceWorkerUrl: '/worker.js',
});
// Your UI code...
</script>
</body>
</html>API Reference
initActrDom(config)
Initialize the Actor-RTC DOM runtime.
Parameters:
config.serviceWorkerUrl(string): Service Worker script pathconfig.webrtcConfig(object, optional): WebRTC configurationiceServers(RTCIceServer[]): ICE server listiceTransportPolicy(RTCIceTransportPolicy): ICE transport policy
Returns: Promise<ActrDomRuntime>
ActrDomRuntime
DOM runtime instance.
Methods:
getSWBridge(): return the Service Worker bridgegetForwarder(): return the Fast Path forwardergetCoordinator(): return the WebRTC coordinatordispose(): release all resources
Architecture
See: WASM-DOM Integration Architecture
Data Flow
WebRTC data arrives in the DOM
↓
WebRtcCoordinator receives it
↓
FastPathForwarder forwards it with minimal copying using Transferable ArrayBuffer
↓
PostMessage → Service Worker WASM
↓
Fast Path Registry.dispatch()
↓
User callback in RustPerformance Characteristics
- Zero-copy style transfer: uses Transferable ArrayBuffer
- Batch forwarding: configurable batching reduces PostMessage overhead
- Target latency: about
6-13msversus30-40msfor the State Path
Components
ServiceWorkerBridge
Handles PostMessage communication between the DOM and the Service Worker.
FastPathForwarder
Forwards WebRTC DataChannel payloads to the Service Worker.
Supports two modes:
forward(): immediately forward one payloadforwardBatch(): batch forwarding for high-throughput scenarios
WebRtcCoordinator
Manages WebRTC connections and DataChannels.
Core functions:
- create
RTCPeerConnection - create four negotiated DataChannels, one per payload type
- handle SDP offer/answer exchange
- handle ICE candidates
- automatically forward received data
Development
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run watch
# Clean
npm run cleanRelated Documents
License
Apache-2.0
Maintainer: Actor-RTC Team Version: 0.1.0 Last updated: 2025-11-11