restream-sdk 0.8.0 → 0.10.0

package/README.md

@@ -33,6 +33,8 @@ Your existing live stream  ──►  Twitch
 - [The `userId` contract & persistence](#the-userid-contract--persistence)
 - [Connecting accounts](#connecting-accounts)
 - [Going live](#going-live)
+- [Screen share & live layout](#screen-share--live-layout)
+- [Collaboration (split-screen)](#collaboration-split-screen)
 - [Live chat & viewers](#live-chat--viewers)
 - [Banners / overlays](#banners--overlays)
 - [Auth modes: publishable key vs. token](#auth-modes-publishable-key-vs-token)
@@ -72,6 +74,13 @@ To go from zero to live you provide exactly **four** things. Everything else is
 You do **not** register OAuth apps, host OAuth callbacks, configure platform
 webhooks, or handle any platform tokens. That's all server-side.
 
+> **The golden rule: keep ONE publisher session for the whole stream.** Publish the
+> camera once and reuse that `publisherSessionId`. **Never re-publish (a new session)
+> or call `goLive()` again** on reconnect, screen toggle, or collaborator change — those
+> are *live* changes: use `setStreamState()`, `startScreenShare()`, and `acceptCollab()`.
+> `goLive()` **throws if a stream is already live**; call `stopLive()` to cleanly end one
+> before starting another.
+
 ---
 
 ## What you get from your operator
@@ -301,9 +310,14 @@ await stopLive();
 
 - **One encode → many destinations.** Restreaming to 2 platforms or 5 costs the
   same on the source; it's a single encode fanned out.
-- **One live stream per streamer.** Calling `goLive()` again for the same `userId`
-  **supersedes** the previous job (the new one takes over). This prevents duplicate
-  streams if a streamer double-clicks or reloads mid-stream.
+- **One live stream per streamer.** `goLive()` **throws** if a job is already live for
+  this streamer — guarding against accidental double-clicks / re-go-lives (the #1 cause
+  of duplicate + stale jobs). Call `stopLive()` first to intentionally restart. Screen /
+  collab / layout are *live* changes — use `setStreamState()`, `startScreenShare()`,
+  `acceptCollab()`, never a second `goLive()`.
+- **`participantOnly: true`** goes live as a compositing-only participant — a collab
+  guest with **no** socials: the job runs (pullable into a host's composite) but fans
+  out nowhere. Pass no `destinations`.
 - **Watch links.** Once broadcasts are created, `job.broadcasts` carries
   `{ platform, watchUrl }` for each destination — handy for "Watch on Twitch ↗".
 - **`arm({ destinations })`** pre-selects destinations so you can fire `goLive`
@@ -312,6 +326,62 @@ await stopLive();
 
 ---
 
+## Screen share & live layout
+
+Screen share is a **separate layer** on your existing stream — never a re-publish or a new `goLive`:
+
+```js
+await startScreenShare();   // publishes the screen session + composites it (solo → screen_camera, collab → collab_screen)
+await stopScreenShare();    // reverts the layout
+```
+
+Push presence/layout live (debounced, best-effort) with `setStreamState`:
+
+```js
+setStreamState({ screenShare: true, camera: true, collab: false,
+                 cameraPosition: "bottom-right", cameraSize: "small" });
+```
+
+---
+
+## Collaboration (split-screen)
+
+Two creators appear side-by-side. Your operator picks the model per client:
+
+**Per-creator (default)** — each creator keeps their **own** live stream; the composite is fanned to **both** creators' own socials:
+
+```js
+// A (host, already live) invites B
+await requestCollab({ collaboratorUserId, publisherSessionId, destinations: ["twitch", "kick"] });
+// B (already live) accepts with their live session
+await acceptCollab(inviteId, { publisherSessionId });
+```
+
+When a collaborator leaves or drops, each still-live creator **automatically reverts to solo** — no stream stops. Send `setStreamState({ collab: false })` for an immediate clean transition.
+
+**Merged (host + challenger)** — only the **host** creates the stream; the challenger joins as a **feed**, with **no job of their own**:
+
+```js
+// Challenger: publish a camera, then join — NO goLive:
+await acceptCollab(inviteId, { publisherSessionId });   // participantOnly guest
+```
+
+- A **new** challenger calling `acceptCollab` while the host is live **swaps** the current one out — **live**, on the host's same session (the host never re-publishes).
+- Live swap is **feed-only**: a swapped-in challenger must have no own socials. An audience-carrying swap is refused — end the collab and start fresh.
+
+**Realtime** — open the collab stream to react to invites/starts/ends live:
+
+```js
+studio.on("collab-composite",  (e) => enterCollabUI(e.job));  // you're in the composite
+studio.on("collab-reassigned", (e) => followJob(e.job));      // your job changed (reverted to solo / swapped out)
+studio.on("collab-ended",      ()  => exitCollabUI());
+await startCollabRealtime();
+```
+
+The SDK **auto-adopts** the new `job.id` on `collab-composite` / `collab-reassigned`, so your `job` state follows the right stream automatically.
+
+---
+
 ## Live chat & viewers
 
 ```js
@@ -426,6 +496,13 @@ defaults to `15000`. On mount it auto-loads connections; `job.status` is polled
 | `refreshJob()` | `Promise<Job>` | re-fetch job status |
 | `sendChat(message, platforms?)` | `Promise` | outbound chat fan-out |
 | `updateOverlay(opts)` | `Promise` | live banner update |
+| `setStreamState(patch)` | — | push live presence/layout (screen/camera/collab, position/size) |
+| `startScreenShare()` / `stopScreenShare()` | `Promise` | screen as a live layer (no re-publish) |
+| `requestCollab(opts)` / `acceptCollab(id, opts)` | `Promise` | invite / join a collab — see [Collaboration](#collaboration-split-screen) |
+| `declineCollab(id)` / `revokeCollab(id)` / `endCollab(id?)` | `Promise` | decline / cancel / end a collab |
+| `setCollabRestream(id, on)` | `Promise` | toggle a guest's own-socials fan-out |
+| `listCollabInvites()` · `collabInvites` | `Promise` · state | sent + received invites |
+| `startCollabRealtime()` / `stopCollabRealtime()` | `Promise` | collab event stream (SSE) |
 | `studio` | `RestreamStudio` | the underlying controller |
 
 ### Convenience hooks
@@ -483,6 +560,12 @@ interface Viewers {
 }
 ```
 
+**Events** — subscribe with `studio.on(type, cb)` (the hook subscribes for you):
+`connections` · `job` · `viewers` · `comment` · `comments` · `error` · `state` ·
+`screenshare` · and collab: `collab-invite` · `collab-accepted` · `collab-declined` ·
+`collab-revoked` · `collab-ended` · `collab-expired` · `collab-composite` ·
+**`collab-reassigned`** (your job id changed — the SDK adopts it) · `collab-snapshot`.
+
 ---
 
 ## Scopes
@@ -521,8 +604,9 @@ A `403 "Missing required scope"` means your key needs that scope added.
   catch (e) { if (e.status === 403) showUpgrade(); else toast(e.message); }
   ```
 - Common statuses: `401` (bad/expired credential — token mode re-mints automatically),
-  `403` (origin not allowed, or missing scope), `409`/supersede (a newer stream took
-  over), `0` (network/timeout).
+  `403` (origin not allowed, or missing scope), `409` (a stream is already live for this
+  streamer, or a duplicate collab), `0` (network/timeout). Note: `goLive()` also **throws
+  client-side** if a job is already live — call `stopLive()` first.
 - Realtime is resilient: transient SSE drops reconnect automatically and chat
   history de-dupes on replay; job-status polling retries on transient failures.
 
@@ -538,7 +622,7 @@ A `403 "Missing required scope"` means your key needs that scope added.
 | Connections empty after refresh | You passed a **different `userId`** — it must be stable per streamer. |
 | Job goes `running` but nothing on the platforms | The `publisherSessionId` must be a **live** session actively sending media when you `goLive()`. |
 | Worker seems to wait / no audio | Your session has no audio track — pass `trackNames: ["video"]`. |
-| Starting a 2nd stream stops the first | Expected — **one live stream per streamer**; a new `goLive` supersedes the old. |
+| `goLive()` throws "a stream is already live" | Expected (0.7.0+) — **one live stream per streamer**. Call `stopLive()` first; use `setStreamState()` / `startScreenShare()` / `acceptCollab()` for live changes (don't re-`goLive`). |
 | `Missing required scope` (403) | Key needs that scope (`connect` / `restream` / `read` / `chat:write`). |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "restream-sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Plug-and-play headless React hooks to add multi-platform restreaming (connect socials, go live, live chat + viewers, collaborative split-screen) with zero client backend.",
   "type": "module",
   "main": "src/index.js",

package/src/core.js

@@ -102,6 +102,98 @@ export class RestreamStudio extends EventTarget {
     return { Authorization: `Bearer ${await this._getToken()}` };
   }
 
+  /**
+   * Wait until a published Cloudflare Realtime session is GENUINELY transmitting media — not merely
+   * ICE/SDP-connected. This closes the "the worker pulled before the publisher was actually sending"
+   * race: a CF `tracks/new` success returns the moment the SDP answer is accepted, but Cloudflare
+   * only registers a "live" remote peer once the publisher's RTCPeerConnection hits connectionState
+   * 'connected' AND every active sender starts emitting RTP packets (outbound-rtp.packetsSent > 0).
+   *
+   * Call this RIGHT AFTER your tracks/new / publish helper resolves and BEFORE you fan-out (goLive,
+   * requestCollab, acceptCollab, setMode). The restream worker pulls immediately at that point; if
+   * you signal before media is flowing, the pull fails transitently ("Track not found on remote
+   * peer") and the composite can drop.
+   *
+   * Resolves when BOTH are true (or rejects on timeout). Pure local getStats polling — no server
+   * round-trip. Picks senders dynamically so a replaceTrack mid-wait is tolerated.
+   *
+   * @param {RTCPeerConnection} pc    the publisher PeerConnection (from your publish helper)
+   * @param {object} [opts]
+   * @param {number} [opts.timeoutMs=8000]   hard cap; rejects with a clear error if media never flows
+   * @param {number} [opts.minPackets=1]     per-sender packet count considered "transmitting"
+   * @param {number} [opts.pollMs=250]       getStats interval
+   * @returns {Promise<{ok:true, senders:number}>}
+   * @throws {Error} on timeout or if the connection dies during the wait
+   */
+  async waitUntilPublishing(pc, { timeoutMs = 8000, minPackets = 1, pollMs = 250 } = {}) {
+    if (!pc || typeof pc.getStats !== "function") {
+      throw new Error("waitUntilPublishing: an RTCPeerConnection is required");
+    }
+    const deadline = Date.now() + Math.max(500, timeoutMs);
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+    // A dead/failing connection is a terminal failure — surface it instead of waiting out the timer.
+    let dead = false;
+    const onFail = () => { dead = true; };
+    const wrap = () => {
+      try { pc.addEventListener("connectionstatechange", onFail); } catch {}
+    };
+    const unwrap = () => {
+      try { pc.removeEventListener("connectionstatechange", onFail); } catch {}
+    };
+    wrap();
+
+    try {
+      while (Date.now() < deadline) {
+        if (dead || pc.connectionState === "failed" || pc.connectionState === "closed") {
+          throw new Error(`waitUntilPublishing: connection ${pc.connectionState} before media flowed`);
+        }
+        const connected = pc.connectionState === "connected" || pc.iceConnectionState === "connected";
+        let transmitting = connected;
+        let senderCount = 0;
+        if (connected) {
+          try {
+            const stats = await pc.getStats();
+            // Map each sender to whether its outbound-rtp shows real packets. Every sender must pass,
+            // so a single stalled track holds the resolve (that's the whole point — the worker pulls
+            // every track and any one missing makes CF reject the pull).
+            const senders = pc.getSenders ? pc.getSenders() : [];
+            for (const s of senders) {
+              if (!s.track) continue; // a sender without a live track (e.g. stopped) doesn't count
+              senderCount++;
+              let trackReport = null;
+              stats.forEach((report) => {
+                if (report.type === "outbound-rtp" && report.track === s.track.id && !report.isReceiving) {
+                  trackReport = report;
+                }
+              });
+              // Some UA variants expose the sender via report trackIdentifier / mediaSource — cover both.
+              if (!trackReport) {
+                stats.forEach((report) => {
+                  if (report.type === "outbound-rtp" && (report.trackIdentifier === s.track.id || (report.id && s.track.id && report.track === s.track.id))) {
+                    trackReport = report;
+                  }
+                });
+              }
+              if (!trackReport || !Number.isFinite(trackReport.packetsSent) || trackReport.packetsSent < minPackets) {
+                transmitting = false;
+                break;
+              }
+            }
+            if (senderCount === 0) transmitting = false; // nothing to transmit yet
+          } catch {
+            transmitting = false; // transient getStats failure — keep polling
+          }
+        }
+        if (transmitting && senderCount > 0) return { ok: true, senders: senderCount };
+        await sleep(pollMs);
+      }
+      throw new Error(`waitUntilPublishing: timed out after ${timeoutMs}ms (connectionState=${pc.connectionState}) — media never flowed`);
+    } finally {
+      unwrap();
+    }
+  }
+
   async _authQuery() {
     if (this.publishableKey) {
       const q = { pk: this.publishableKey };
@@ -400,7 +492,7 @@ export class RestreamStudio extends EventTarget {
    *                                           Restream channels. Any field omitted falls back to the
    *                                           default pre-set for this creator on the platform.
    */
-  async goLive({ publisherSessionId, destinations, overlay, recording, trackNames, restreamChannels, streamMeta, destinationMeta, streamingProvider, layout, screenSessionId, participantOnly } = {}) {
+  async goLive({ publisherSessionId, destinations, overlay, recording, trackNames, restreamChannels, streamMeta, destinationMeta, streamingProvider, layout, screenSessionId, participantOnly, metadata, preComposited } = {}) {
     if (!publisherSessionId) throw new Error("publisherSessionId is required (from your existing stream session)");
     // Idempotency guard: refuse a second goLive while a job is already live. Re-publishing a fresh
     // session and calling goLive() again on reconnect / screen toggle / collaborator change is the #1
@@ -449,6 +541,13 @@ export class RestreamStudio extends EventTarget {
       body.screenSessionId = screenId;
       body.screenTrackName = this._screen?.trackName || "screen";
     }
+    // Arbitrary job metadata + the pre-composited flag. preComposited:true tells the backend this
+    // publisher session already contains the partner (client-side composite / chart-canvas), so the
+    // per-creator collab reconciler must NOT attach the partner's feed to this job (it would double-
+    // composite + flip to sidebyside). Both forms land at restream_jobs.metadata.preComposited.
+    const meta = { ...(metadata || {}) };
+    if (preComposited) meta.preComposited = true;
+    if (Object.keys(meta).length) body.metadata = meta;
     if (this.publishableKey && this.userId) body.clientUserId = this.userId; // token mode binds server-side
     const job = await this._req("POST", "/api/v1/jobs", body);
     this.job = job;
@@ -527,6 +626,41 @@ export class RestreamStudio extends EventTarget {
     return this._streamState;
   }
 
+  /**
+   * Switch a LIVE job's MODE (the new single-job model: one job holds the host's stream; modes
+   * change which feeds are composited + their positions — solo / host_screen / 1v1 / 1v1_screen / …).
+   * The ingest + RTMP fan-out NEVER restart on a mode change (immutable-job invariant); only the
+   * compositor layers/positions change. A guest may arrive later or a different guest swap in
+   * without a new job — the compositor is "always ready".
+   *
+   * On scene_engine='legacy' (default) this drives a brief restartWithFeeds internally; on
+   * 'live_v2' it is a true zero-restart sink mutation. The SDK call is identical either way —
+   * Stage 2 swaps the engine under you with no client change.
+   *
+   * @param {string} mode  a preset key (solo / host_screen / 1v1 / 1v1_screen / solo_fullscreen_cam)
+   *                       or a per-creator override key configured in the admin
+   * @returns {Promise<{ok:boolean, mode:string, applied:boolean, engine:string}>}
+   */
+  async setMode(mode) {
+    if (!mode) throw new Error("mode is required (e.g. 'solo', '1v1', '1v1_screen')");
+    const jobId = this.job?.id;
+    if (!jobId) throw new Error("Not live — go live before switching modes");
+    const r = await this._req("POST", `/api/v1/jobs/${jobId}/mode`, this._withUser({ mode }));
+    if (r?.ok) this._emit("mode", { mode, engine: r.engine });
+    return r;
+  }
+
+  /**
+   * The job's CURRENTLY-active mode (resolved from its live state against the client's presets +
+   * per-creator overrides). Returns { mode, template, layoutState }. Read-only.
+   */
+  async getMode() {
+    const jobId = this.job?.id;
+    if (!jobId) throw new Error("Not live");
+    const r = await this._req("GET", `/api/v1/jobs/${jobId}/mode`, this._withUser({}));
+    return r;
+  }
+
   /** Last presence/layout state set via setStreamState() (local view). */
   get streamState() { return this._streamState; }
 
@@ -542,25 +676,44 @@ export class RestreamStudio extends EventTarget {
    * go-live if called first, or LIVE mid-stream via the layout transition. Restream-only; not shown
    * in the client's own player. Must be called from a user gesture (getDisplayMedia requires it).
    *
-   * @param {object} [opts] { trackName='screen', audio=false }
+   * A CALLER-SUPPLIED track may be passed instead of capturing the OS screen — e.g. a
+   * `canvas.captureStream()` video track that already contains a pre-composited frame (host cam +
+   * guest cam + chart). When `track` is given we skip `getDisplayMedia` entirely (no OS picker, no
+   * permission prompt) and publish that track as the layer. The CALLER owns that track's lifecycle:
+   * we never stop it (on `stopScreenShare` or teardown), so a single continuous canvas track can
+   * survive stop/restart and coin switches with no media blip.
+   *
+   * NOTE on layout: this publishes as the SCREEN layer, so the backend composites `screen_camera`
+   * (screen full-frame + camera PiP). For a PRE-COMPOSITED pass-through feed where you do NOT want a
+   * camera PiP, publish the canvas as your PRIMARY track instead (the backend renders `solo` =
+   * full-frame, no PiP, mic audio) — see the chart-canvas integration guide.
+   *
+   * @param {object} [opts] { trackName='screen', audio=false, track?: MediaStreamTrack }
    * @returns {Promise<{sessionId:string, trackName:string}>}
    */
-  async startScreenShare({ trackName = "screen", audio = false } = {}) {
-    if (typeof navigator === "undefined" || !navigator.mediaDevices?.getDisplayMedia) {
-      throw new Error("Screen sharing is not supported in this environment");
-    }
+  async startScreenShare({ trackName = "screen", audio = false, track = null } = {}) {
     if (this._screen) return { sessionId: this._screen.sessionId, trackName: this._screen.trackName };
 
-    // 1) Capture the screen.
-    const stream = await navigator.mediaDevices.getDisplayMedia({ video: true, audio });
-    const track = stream.getVideoTracks()[0];
-    if (!track) { stream.getTracks().forEach((t) => t.stop()); throw new Error("no screen video track"); }
+    // 1) Obtain the video track: caller-supplied (pre-composited, caller-owned) or captured screen.
+    let stream = null;
+    let videoTrack = track;
+    const callerOwnsTrack = !!track;
+    if (!callerOwnsTrack) {
+      if (typeof navigator === "undefined" || !navigator.mediaDevices?.getDisplayMedia) {
+        throw new Error("Screen sharing is not supported in this environment");
+      }
+      stream = await navigator.mediaDevices.getDisplayMedia({ video: true, audio });
+      videoTrack = stream.getVideoTracks()[0];
+      if (!videoTrack) { stream.getTracks().forEach((t) => t.stop()); throw new Error("no screen video track"); }
+    }
+    if (!videoTrack) throw new Error("startScreenShare: no video track (pass { track } or enable screen capture)");
+    const track_ = videoTrack;
 
     try {
       // 2) ICE servers + peer connection.
       const { iceServers } = await this._req("GET", "/api/streams/turn-credentials");
       const pc = new RTCPeerConnection({ iceServers, bundlePolicy: "max-bundle" });
-      const transceiver = pc.addTransceiver(track, { direction: "sendonly" });
+      const transceiver = pc.addTransceiver(track_, { direction: "sendonly" });
 
       // 3) New Cloudflare Realtime session (brokered by our backend — CF creds stay server-side).
       const session = await this._req("POST", "/api/streams/sessions", {});
@@ -576,17 +729,19 @@ export class RestreamStudio extends EventTarget {
       });
       if (res?.sessionDescription) await pc.setRemoteDescription(new RTCSessionDescription(res.sessionDescription));
 
-      // Stop-sharing from the browser's own UI must tear us down too.
-      track.addEventListener("ended", () => { this.stopScreenShare().catch(() => {}); });
+      // Stop-sharing from the browser's own UI must tear us down too — but ONLY for a screen we
+      // captured. A caller-supplied track's lifecycle belongs to the caller (e.g. a canvas capture
+      // that must outlive stop/restart), so we don't bind its 'ended' to our teardown.
+      if (!callerOwnsTrack) track_.addEventListener("ended", () => { this.stopScreenShare().catch(() => {}); });
 
-      this._screen = { pc, track, stream, sessionId, trackName };
+      this._screen = { pc, track: track_, stream, sessionId, trackName, callerOwnsTrack };
       // Signal the backend WHICH session/track the screen is on so it can pull it as a live layer
       // and transition the layout server-side (solo → screen_camera, collab → collab_screen).
       this.setStreamState({ screenShare: true, screenSessionId: sessionId, screenTrackName: trackName });
       this._emit("screenshare", { active: true, sessionId, trackName });
       return { sessionId, trackName };
     } catch (err) {
-      try { stream.getTracks().forEach((t) => t.stop()); } catch { /* ignore */ }
+      if (stream) { try { stream.getTracks().forEach((t) => t.stop()); } catch { /* ignore */ } }
       throw err;
     }
   }
@@ -597,8 +752,12 @@ export class RestreamStudio extends EventTarget {
     if (!s) return;
     this._screen = null;
     try { await this._req("POST", `/api/streams/sessions/${s.sessionId}/tracks/close`, { tracks: [{ mid: s.pc?.getTransceivers?.()[0]?.mid, trackName: s.trackName }], force: true }); } catch { /* best-effort */ }
-    try { s.track.stop(); } catch { /* ignore */ }
-    try { s.stream.getTracks().forEach((t) => t.stop()); } catch { /* ignore */ }
+    // Only stop tracks WE created (captured screen). A caller-supplied track (e.g. a continuous
+    // canvas capture) is owned by the caller and must keep running across stop/restart + coin switches.
+    if (!s.callerOwnsTrack) {
+      try { s.track.stop(); } catch { /* ignore */ }
+      try { s.stream?.getTracks().forEach((t) => t.stop()); } catch { /* ignore */ }
+    }
     try { s.pc.close(); } catch { /* ignore */ }
     // Clear the screen session so the backend reverts the layout (screen_camera → solo,
     // collab_screen → sidebyside).
@@ -720,20 +879,27 @@ export class RestreamStudio extends EventTarget {
    * starts only when they accept. Pass your own publisherSessionId + destinations so
    * the server can begin the merged broadcast on accept (or rely on your active job).
    *
-   * collaboratorRestreamOn defaults to TRUE: the invited creator's connected social
-   * accounts MUST receive the side-by-side composite unless they explicitly opt out
-   * (pass `collaboratorRestreamOn: false`). This matches the server product intent in
-   * routes/collab.js and CollabService.createInvite. The bug: defaulting the SDK to
-   * `false` here sent `false` in the request body, which the server honored, so the
-   * collaborator's broadcasts/fan-out were silently skipped and the collab frame never
-   * appeared on the collaborator's own social accounts.
+   * collaboratorRestreamOn controls whether the invited creator gets THEIR OWN job +
+   * fan-out (their own socials broadcast the composite), and is RESOLVED SERVER-SIDE
+   * by default so a single SDK works for both product models:
+   *   - host/challenger products (Aurealone): only the HOST restreams. The guest is a
+   *     feed-only participant inside the host's composite and creates NO job. The
+   *     client's per-server default (collab_guest_restream=false) applies.
+   *   - symmetric products (fomo.gg): both creators restream their own composite.
+   *     The client's per-server default is true.
+   * Pass `collaboratorRestreamOn: true|false` ONLY to override the per-client default
+   * for this specific invite (rare). Omit it (do NOT default it client-side) so the
+   * server's per-client rule is the single source of truth.
    * @param {object} opts { collaboratorUserId, collaboratorRestreamOn?, publisherSessionId?, destinations?, metadata? }
    */
-  async requestCollab({ collaboratorUserId, collaboratorRestreamOn = true, publisherSessionId, destinations, metadata } = {}) {
+  async requestCollab({ collaboratorUserId, collaboratorRestreamOn, publisherSessionId, destinations, metadata } = {}) {
     if (!collaboratorUserId) throw new Error("collaboratorUserId is required");
-    const invite = await this._req("POST", "/api/v1/collab/request", this._withUser({
-      collaboratorUserId, collaboratorRestreamOn, publisherSessionId, destinations, metadata,
-    }));
+    const body = this._withUser({ collaboratorUserId, publisherSessionId, destinations, metadata });
+    // Only send the flag if the caller EXPLICITLY set it — otherwise omit so the server resolves
+    // the per-client default (host-only vs symmetric). Previously this defaulted to TRUE client-side
+    // and was sent on every call, forcing a guest fan-out for host-only products → duplicate jobs.
+    if (collaboratorRestreamOn === true || collaboratorRestreamOn === false) body.collaboratorRestreamOn = collaboratorRestreamOn;
+    const invite = await this._req("POST", "/api/v1/collab/request", body);
     this._emit("collab-invite", { type: "collab-invite", invite, mine: true });
     return invite;
   }

package/types/index.d.ts

@@ -104,6 +104,15 @@ export interface GoLiveParams {
   destinationMeta?: DestinationMeta;
   /** Initial presence/layout state for the stream (same shape as setStreamState). */
   layout?: StreamState;
+  /** Arbitrary job metadata (stored on the job row, readable by the backend). */
+  metadata?: Record<string, unknown>;
+  /**
+   * Mark this publisher session as PRE-COMPOSITED: it already contains the partner (host + guest
+   * composited client-side onto one canvas). The backend renders it full-frame (solo) and the
+   * per-creator collab reconciler will NOT attach the partner's feed to this job (which would
+   * double-composite + flip to sidebyside). Folded into metadata.preComposited.
+   */
+  preComposited?: boolean;
   /** Cloudflare session of a screen-share publish (from startScreenShare) to composite as a
    *  separate layer. Defaults to the SDK's active screen share if omitted. */
   screenSessionId?: string;
@@ -273,11 +282,19 @@ export class RestreamStudio extends EventTarget {
   /** Capture the screen and publish it as its OWN Cloudflare session (a separate layer the
    *  backend composites via templates). Pass the returned sessionId to goLive({ screenSessionId }).
    *  Restream-only; must be called from a user gesture. */
-  startScreenShare(opts?: { trackName?: string; audio?: boolean }): Promise<{ sessionId: string; trackName: string }>;
+  startScreenShare(opts?: { trackName?: string; audio?: boolean; track?: MediaStreamTrack }): Promise<{ sessionId: string; trackName: string }>;
   /** Stop screen sharing (close the Cloudflare track + peer connection). */
   stopScreenShare(): Promise<void>;
   /** Cloudflare session id of the live screen-share publish, or null. */
   readonly screenSessionId: string | null;
+  /** Wait until a published Cloudflare Realtime session is genuinely transmitting media
+   *  (connectionState 'connected' AND every active sender's outbound-rtp.packetsSent > minPackets),
+   *  not merely ICE/SDP-connected. Call this RIGHT AFTER your tracks/new/publish helper resolves
+   *  and BEFORE you signal fan-out (goLive / requestCollab / acceptCollab / setMode) so the
+   *  restream-side pull never races the publisher's first RTP packets ('Track not found on
+   *  remote peer'). Pure local getStats polling; no server round-trip. Rejects on timeout /
+   *  connection failure. New in 0.9.0. */
+  waitUntilPublishing(pc: RTCPeerConnection, opts?: { timeoutMs?: number; minPackets?: number; pollMs?: number }): Promise<{ ok: true; senders: number }>;
   startRealtime(jobId: string): Promise<void>;
   stopRealtime(): void;
   // collaborative split-screen
@@ -327,7 +344,7 @@ export interface UseRestream {
   sendChat(message: string, platforms?: Platform[]): Promise<unknown>;
   updateOverlay(opts: OverlayUpdate): Promise<unknown>;
   setStreamState(patch: StreamState): StreamState;
-  startScreenShare(opts?: { trackName?: string; audio?: boolean }): Promise<{ sessionId: string; trackName: string }>;
+  startScreenShare(opts?: { trackName?: string; audio?: boolean; track?: MediaStreamTrack }): Promise<{ sessionId: string; trackName: string }>;
   stopScreenShare(): Promise<void>;
   requestCollab(opts: RequestCollabParams): Promise<CollabInvite>;
   acceptCollab(inviteId: string, opts: AcceptCollabParams): Promise<{ invite: CollabInvite; job: Job }>;