@weft-js/realtime-livekit 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-livekit
 
-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 a LiveKit room, with the token signed by the room.
+
+```bash
+npm install @weft-js/realtime-livekit
+```

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@weft-js/realtime-livekit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "@weft-js/realtime-livekit: cursors over a LiveKit room, with the token signed by the room",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts",
+    "./plugin": "./plugin.mjs"
+  },
+  "dependencies": {
+    "livekit-client": "2.23.0"
+  },
+  "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>
+/** `livekit()` for `weft.config.ts`: puts LiveKit on the record of what the app reaches. A page passes the transport to `presence`. */
+export default plugin

package/plugin.mjs

@@ -0,0 +1,14 @@
+// livekit() for weft.config.ts: no slot, since a page passes the transport to `presence`.
+import { definePlugin } from '@weft-js/core/plugin'
+
+export const livekit = definePlugin({
+  name: '@weft-js/realtime-livekit',
+  version: '0.1.0',
+  weft: '*',
+  permissions: { net: ['browser:livekit'], env: ['LIVEKIT_API_KEY', 'LIVEKIT_API_SECRET'] },
+  contribute: () => ({
+    agents: { title: 'Peer transport (LiveKit)', text: '`presence(conn, { transport: livekit({ url }) })` sends cursors through LiveKit, and `link.room` is the room for audio and video. Pass `ticket: livekitTicket({ media })` from `@weft-js/realtime-livekit/server` to `multiplayer()`, with `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET` on the server.' },
+  }),
+})
+
+export default livekit

package/src/index.ts

@@ -0,0 +1,41 @@
+// Cursors over a LiveKit room. `ticket` from the server is the token, and LiveKit proves a frame's sender: a participant's
+// identity is the connection the room signed it for. The room is there for audio and video too: `link.room`.
+
+import { createRoot, derived, state, untrack } from '@weft-js/core'
+import { Room, RoomEvent } from 'livekit-client'
+import type { PeerLink, PeerRoom, PeerTransport } from '@weft-js/multiplayer'
+
+const TOPIC = 'weft'
+
+/** Options of `livekit()`. */
+export interface LivekitOptions {
+  /** `wss://…` */
+  url: string
+}
+
+/** A peer transport over a LiveKit room, for `presence(conn, { transport })`. The link's `room` carries audio and video too. */
+export function livekit({ url }: LivekitOptions): PeerTransport {
+  return {
+    name: 'livekit',
+    open(room: PeerRoom): PeerLink & { room: Room } {
+      return createRoot(dispose => {
+        const live = new Room()
+        const here = state<string[]>([])
+        const sync = () => { here.value = [...live.remoteParticipants.values()].map(p => p.identity) }
+        const decoder = new TextDecoder(), encoder = new TextEncoder()
+        live.on(RoomEvent.DataReceived, (bytes, participant, _kind, topic) => { if (topic === TOPIC && participant) room.receive(participant.identity, decoder.decode(bytes)) })
+        for (const e of [RoomEvent.ParticipantConnected, RoomEvent.ParticipantDisconnected, RoomEvent.Connected, RoomEvent.Disconnected]) live.on(e, sync)
+        if (room.ticket) void live.connect(url, room.ticket as string).then(sync, () => {})
+        return {
+          room: live,
+          up: derived(() => { const ids = room.peers.value; return ids.length > 0 && ids.every(id => here.value.includes(id)) }),
+          send(text) { if (untrack(() => here.value.length)) void live.localParticipant.publishData(encoder.encode(text), { reliable: false, topic: TOPIC }).catch(() => {}) },
+          close() {
+            void live.disconnect()
+            dispose()
+          },
+        }
+      })
+    },
+  }
+}

package/src/server.ts

@@ -0,0 +1,21 @@
+// The token, for `multiplayer({ ticket })`: signed with the room's identity, so no client can name itself to LiveKit.
+import { roomId, signTicket } from '@weft-js/multiplayer/server'
+
+/** Options of `livekitTicket()`. */
+export interface LivekitTicketOptions {
+  /** Default `LIVEKIT_API_KEY`. */
+  key?: string
+  /** Default `LIVEKIT_API_SECRET`. */
+  secret?: string
+  /** Seconds. Default 3600. */
+  ttl?: number
+  /** Audio and video too. Default false: data only, which is what cursors need. */
+  media?: boolean
+}
+
+/** For `multiplayer({ ticket })`: a LiveKit token that names the connection and its room. Refuses to run without a key and secret. */
+export const livekitTicket = ({ key = process.env.LIVEKIT_API_KEY, secret = process.env.LIVEKIT_API_SECRET, ttl = 3600, media = false }: LivekitTicketOptions = {}) => async ({ id, user, params }: { id: string; user: { name?: string }; params: unknown }) => {
+  if (!key || !secret) throw new Error('`livekitTicket` needs `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET`')
+  const now = Math.floor(Date.now() / 1000)
+  return signTicket({ iss: key, sub: id, name: user.name, nbf: now, exp: now + ttl, video: { room: await roomId(params), roomJoin: true, canPublish: media, canSubscribe: true, canPublishData: true } }, secret)
+}