@weft-js/realtime-webrtc 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @weft-js/realtime-webrtc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Early release (0.1.0).** APIs will change between minor versions.
+
+Cursors over WebRTC data channels, signalled through the room.
+
+```bash
+npm install @weft-js/realtime-webrtc
+```

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@weft-js/realtime-webrtc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "@weft-js/realtime-webrtc: cursors over WebRTC data channels, signalled through the room",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./plugin": "./plugin.mjs"
+  },
+  "peerDependencies": {
+    "@weft-js/start": "^0.1.0",
+    "@weft-js/core": "^0.1.0",
+    "@weft-js/multiplayer": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "files": [
+    "src",
+    "plugin.mjs",
+    "plugin.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.d.mts

@@ -0,0 +1,5 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+declare const plugin: (options?: Record<string, unknown>) => PluginInstance<unknown>
+/** `webrtc()` for `weft.config.ts`: puts peers and ICE servers on the record of what the app reaches. A page passes the transport to `presence`. */
+export default plugin

package/plugin.mjs

@@ -0,0 +1,15 @@
+// webrtc() for weft.config.ts: no slot, since a page passes the transport to `presence`. Listed, what it reaches is on
+// the record. A browser talks to STUN, TURN and peers directly, and none of that goes through the server.
+import { definePlugin } from '@weft-js/core/plugin'
+
+export const webrtc = definePlugin({
+  name: '@weft-js/realtime-webrtc',
+  version: '0.1.0',
+  weft: '*',
+  permissions: { net: ['browser:peers', 'browser:ice-servers'] },
+  contribute: () => ({
+    agents: { title: 'Peer transport (WebRTC)', text: '`presence(conn, { transport: webrtc({ iceServers }) })` sends cursors directly between browsers, and the socket carries them until every peer is connected. Only cursors ride it: state and the relay stay on the server, which checks them.' },
+  }),
+})
+
+export default webrtc

package/src/index.ts

@@ -0,0 +1,107 @@
+// Cursors over WebRTC data channels: a full mesh, with offers and candidates through the room, so `from` on a frame is
+// the peer the server vouched for when the connection was made. Unordered and without retries, like what it carries. A
+// page without a working path to a peer stays on the socket: `up` is true only when every peer is connected.
+//
+//   presence(chat, { transport: webrtc({ iceServers: [{ urls: 'stun:stun.example.com' }] }) })
+
+import { createRoot, derived, effect, state, untrack } from '@weft-js/core'
+import type { PeerLink, PeerRoom, PeerTransport } from '@weft-js/multiplayer'
+
+/** Options of `webrtc()`. */
+export interface WebRtcOptions {
+  /** STUN and TURN. Default none: peers on one network. */
+  iceServers?: RTCIceServer[]
+  /** More peers than this and it stays on the socket: a mesh costs each peer one connection per other. Default 8. */
+  max?: number
+}
+
+interface Conn { pc: RTCPeerConnection; dc?: RTCDataChannel; makingOffer: boolean }
+interface Signal { description?: RTCSessionDescriptionInit; candidate?: RTCIceCandidateInit }
+
+/** A peer transport over a mesh of WebRTC data channels, for `presence(conn, { transport })`. */
+export function webrtc({ iceServers = [], max = 8 }: WebRtcOptions = {}): PeerTransport {
+  return {
+    name: 'webrtc',
+    open(room: PeerRoom): PeerLink {
+      return createRoot(dispose => {
+        const conns = new Map<string, Conn>()
+        const open = state(0)
+        const channel = (id: string, c: Conn, dc: RTCDataChannel) => {
+          c.dc = dc
+          dc.onopen = () => { open.value++ }
+          dc.onclose = () => { open.value++ }
+          dc.onmessage = e => { if (typeof e.data === 'string' && e.data.length < 1024) room.receive(id, e.data) }
+        }
+        const connect = (id: string) => {
+          const had = conns.get(id)
+          if (had) return had
+          const c: Conn = { pc: new RTCPeerConnection({ iceServers }), makingOffer: false }
+          conns.set(id, c)
+          c.pc.onicecandidate = e => { if (e.candidate) room.signal(id, { candidate: e.candidate.toJSON() }) }
+          c.pc.onconnectionstatechange = () => { open.value++ }
+          c.pc.ondatachannel = e => channel(id, c, e.channel)
+          c.pc.onnegotiationneeded = async () => {
+            try {
+              c.makingOffer = true
+              await c.pc.setLocalDescription()
+              room.signal(id, { description: c.pc.localDescription!.toJSON() })
+            } catch {
+              // The other side's offer won: its handler takes over.
+            } finally {
+              c.makingOffer = false
+            }
+          }
+          return c
+        }
+        const answer = async (from: string, data: unknown) => {
+          if (!untrack(() => room.peers.value).includes(from) || typeof data !== 'object' || !data) return
+          const { description, candidate } = data as Signal
+          const c = connect(from)
+          try {
+            if (description) {
+              // Perfect negotiation: the lower id gives way when both offer at once.
+              const collision = description.type === 'offer' && (c.makingOffer || c.pc.signalingState !== 'stable')
+              if (collision && room.self > from) return
+              await c.pc.setRemoteDescription(description)
+              if (description.type === 'offer') {
+                await c.pc.setLocalDescription()
+                room.signal(from, { description: c.pc.localDescription!.toJSON() })
+              }
+            } else if (candidate) await c.pc.addIceCandidate(candidate).catch(() => {})
+          } catch {
+            // A bad frame from a peer costs that peer its link: frames for it stay on the socket.
+          }
+        }
+        const stop = room.onSignal((from, data) => void answer(from, data))
+        const close = (id: string) => {
+          conns.get(id)?.pc.close()
+          conns.delete(id)
+          open.value++
+        }
+        effect(() => room.peers.value, ids => {
+          if (ids.length > max) return
+          for (const id of ids) {
+            if (conns.has(id)) continue
+            const c = connect(id)
+            if (room.self < id) channel(id, c, c.pc.createDataChannel('weft', { ordered: false, maxRetransmits: 0 }))
+          }
+          for (const id of conns.keys()) if (!ids.includes(id)) close(id)
+        })
+        const up = derived(() => {
+          void open.value
+          const ids = room.peers.value
+          return ids.length > 0 && ids.length <= max && ids.every(id => conns.get(id)?.dc?.readyState === 'open')
+        })
+        return {
+          up,
+          send(text) { for (const c of conns.values()) if (c.dc?.readyState === 'open') c.dc.send(text) },
+          close() {
+            stop()
+            for (const id of conns.keys()) close(id)
+            dispose()
+          },
+        }
+      })
+    },
+  }
+}