@livo-tv/sdk 1.11.0 → 1.12.0-rc.1

package/README.md

@@ -1,17 +1,75 @@
 # @livo-tv/sdk
 
-Embed the Livo **player** (native React) and **studio** (native room or themed iframe) in a third-party app.
+Embed Livo **in-DOM** on your origin. Native React is the partner path: `LivoPlayer`, `LivoHostStudio`, and `LivoGuestStudio`. Do not iframe `player.livo.tv`.
 
 ```tsx
-import { LivoPlayer, LivoStudio, playerUrl } from "@livo-tv/sdk";
-import { LivoHostStudio, LivoGuestStudio } from "@livo-tv/sdk/studio";
+import { LivoPlayer, applyEmbedTheme, type EmbedTheme } from "@livo-tv/sdk";
+import {
+	LivoHostStudio,
+	LivoGuestStudio,
+	StudioWindowGate,
+	studioRoomLabels,
+} from "@livo-tv/sdk/studio";
 import "@livo-tv/sdk/styles.css";
 
-<LivoPlayer streamId="s1" theme={{ primary: "#2563eb", mode: "dark" }} />
-<LivoStudio guestToken="..." theme={{ primary: "#2563eb" }} />
+const theme: EmbedTheme = {
+	accent: "#0F6FF5",
+	background: "#0b1220",
+	foreground: "#f8fafc",
+	radius: "8px",
+	fontFamily: "Inter, sans-serif",
+	mode: "dark",
+};
+
+<LivoPlayer
+	streamId="s1"
+	theme={theme}
+	onPlaybackState={(state) => {
+		/* loading | waiting | playing | paused | ended | error */
+	}}
+	onError={(error) => {
+		/* not_found | playback */
+	}}
+/>;
 ```
 
-`@livo-tv/sdk`, `@livo-tv/sdk/studio`, and `@livo-tv/sdk/condo` (`LivoCommunity`) are client entries (the published bundles start with `"use client"`). Import them from `"use client"` files in Next.js App Router — do not import those entries from a Server Component page. Tailwind hosts must `@source` `node_modules/@livo-tv/sdk/dist/*.{js,cjs,mjs}` like `@livo-tv/blocks`. RealtimeKit is an optional peer (`@cloudflare/realtimekit`). Root `<LivoStudio>` remains the iframe fallback.
+`@livo-tv/sdk`, `@livo-tv/sdk/studio`, and `@livo-tv/sdk/condo` (`LivoCommunity`) are client entries (the published bundles start with `"use client"`). Import them from `"use client"` files in Next.js App Router — do not import those entries from a Server Component page. Tailwind hosts must `@source` `node_modules/@livo-tv/sdk/dist/*.{js,cjs,mjs}` like `@livo-tv/blocks`.
+
+Root `<LivoStudio>` still iframes `app.livo.tv` and is **not** the partner contract. Native studio has no runtime dependency on `player.livo.tv` (no `postMessage` bridge, no hard-coded player origin). The hosted-player URL helpers (`playerUrl`) stay available for Livo's own player app.
+
+## Native studio (RealtimeKit)
+
+Peers (install in the host app):
+
+- `@cloudflare/realtimekit` (optional peer, lazy-imported)
+- `react` / `react-dom`
+- `hls.js` for `<LivoPlayer>`
+
+Send this header on the route that mounts the studio (camera, mic, and screen share):
+
+```
+Permissions-Policy: camera=(self), microphone=(self), display-capture=(self)
+```
+
+Wrap the studio in `StudioWindowGate` with a **stable** `lockKey` (stream id or host token), not the partner pathname. The lock uses `BroadcastChannel` and is origin-scoped, so `/dashboard/studio` and `/events/123/studio` on the same origin still see each other.
+
+```tsx
+<StudioWindowGate lockKey={`host:${streamId}`} labels={gateLabels}>
+	<LivoHostStudio
+		token={hostToken}
+		apiUrl="https://api.livo.tv"
+		labels={studioRoomLabels((key) => key)}
+		embed
+		theme={theme}
+	/>
+</StudioWindowGate>
+```
+
+`theme` is an `EmbedTheme` object (or a hosted encoded string). `applyEmbedTheme` writes CSS variables onto **the studio container**, not `document.documentElement`, so a partner shell keeps its own chrome.
+
+Omit `playerOrigin` in native embeds. The watch-share control only appears when you pass a player origin; native partners should share their own watch URL.
+
+Regression page: `pnpm example:embed` serves `examples/partner-embed` on `http://localhost:3003`.
 
 Community (condo) — comments on every video, live Q&A only while a stream or webinar is `preview` / `public`. After the event, Q&A stays closed. Comments stay closed unless the organizer sets `commentsAfterEnd`.
 
@@ -20,12 +78,10 @@ Community (condo) — comments on every video, live Q&A only while a stream or w
 **Custom layout:** mount `<LivoCommunity>` next to a theater-only player, or call `createCommunityClient` / the public HTTP API for a fully custom UI. Pass a public `apiUrl` for viewers (`mode="viewer"`, polls). Pass JWT / `X-Api-Key` headers and `mode="control"` for settings, pin/hide/delete, and Q&A highlight/dismiss/answer. Unregistered posters send `displayName`, optional `picture` URL, and `guestId`. Supply `displayName` (and optional `picture`) to skip the name field; otherwise the composer asks once and stores `livo-community-identity`. Hosted iframes use `?name=` / `?avatar=` when the built-in panel is on.
 
 ```tsx
-import { LivoPlayer, playerUrl } from "@livo-tv/sdk";
+import { LivoPlayer } from "@livo-tv/sdk";
 import { LivoCommunity } from "@livo-tv/sdk/condo";
 import "@livo-tv/sdk/styles.css";
 
-<iframe src={playerUrl(stream.id, { community: false })} />
-
 <LivoPlayer streamId={stream.id} />
 
 <LivoCommunity
@@ -60,12 +116,20 @@ Server (Node / Workers):
 import { createLivoServerClient } from "@livo-tv/sdk/server";
 
 const livo = createLivoServerClient({ apiKey: process.env.LIVO_API_KEY! });
-const { hostUrl, guestUrl, hostToken, guestToken } = await livo.mintHostSession(
-	streamId,
-	{
-		displayName: "Host",
-	},
-);
+const { vodId, uploadId, partSize } = await livo.createVod({
+	filename: "talk.mp4",
+	contentType: "video/mp4",
+	byteSize: 12_000_000,
+	sha256: "64-lowercase-hex",
+});
+await livo.completeVodUpload(vodId, {
+	parts: [{ partNumber: 1, etag: '"etag-from-put"' }],
+});
+const { hostToken, guestToken } = await livo.mintHostSession(streamId, {
+	displayName: "Host",
+});
 ```
 
+Browser part `PUT`s go to the presigned R2 URL. Bucket CORS is `PUT *` with `ETag` exposed; mint the URL with `lk_` on your server.
+
 GitHub `livo-tv/sdk` + npm OIDC publish are a human handoff (same as `@livo-tv/blocks`).

package/dist/index.cjs

@@ -1008,6 +1008,7 @@ function sanitizeEmbedTheme(value) {
   const row = value;
   const theme = {};
   const primary = sanitizeColor(row.primary);
+  const accent = sanitizeColor(row.accent);
   const background = sanitizeColor(row.background);
   const foreground = sanitizeColor(row.foreground);
   if (typeof row.radius === "string" && RADIUS.test(row.radius.trim())) {
@@ -1017,6 +1018,7 @@ function sanitizeEmbedTheme(value) {
     theme.fontFamily = row.fontFamily.trim();
   }
   if (primary) theme.primary = primary;
+  if (accent) theme.accent = accent;
   if (background) theme.background = background;
   if (foreground) theme.foreground = foreground;
   if (row.mode === "light" || row.mode === "dark") theme.mode = row.mode;
@@ -1031,9 +1033,17 @@ function encodeEmbedTheme(theme) {
 }
 function embedThemeCssVars(theme) {
   const vars = {};
+  const accent = theme.accent ?? theme.primary;
   if (theme.primary) {
     vars["--livo-primary"] = theme.primary;
     vars["--primary"] = theme.primary;
+  } else if (accent) {
+    vars["--livo-primary"] = accent;
+    vars["--primary"] = accent;
+  }
+  if (accent) {
+    vars["--livo-accent"] = accent;
+    vars["--accent"] = accent;
   }
   if (theme.background) {
     vars["--livo-background"] = theme.background;
@@ -1062,8 +1072,12 @@ function decodeEmbedTheme(raw) {
     return null;
   }
 }
+function resolveEmbedThemeInput(value) {
+  if (typeof value === "string") return decodeEmbedTheme(value);
+  return sanitizeEmbedTheme(value ?? null);
+}
 function applyEmbedTheme(root, theme) {
-  if (!theme) return;
+  if (!root || !theme) return;
   if (theme.mode === "dark") root.classList.add("dark");
   if (theme.mode === "light") root.classList.remove("dark");
   for (const [key, value] of Object.entries(embedThemeCssVars(theme))) {
@@ -1183,6 +1197,7 @@ function LivoPlayer({
   waitingLabels,
   className,
   onStatusChange,
+  onPlaybackState,
   onProgress,
   onEnded,
   onError,
@@ -1224,6 +1239,7 @@ function LivoPlayer({
         if (cancelled) return;
         if (!next) {
           onError?.({ code: "not_found" });
+          onPlaybackState?.("error");
           return;
         }
         setStream(next);
@@ -1237,6 +1253,7 @@ function LivoPlayer({
         if (cancelled) return;
         if (!next) {
           onError?.({ code: "not_found" });
+          onPlaybackState?.("error");
           return;
         }
         setVod(next);
@@ -1250,7 +1267,15 @@ function LivoPlayer({
       cancelled = true;
       window.clearInterval(timer);
     };
-  }, [apiUrl, onEnded, onError, onStatusChange, streamId, vodId]);
+  }, [
+    apiUrl,
+    onEnded,
+    onError,
+    onPlaybackState,
+    onStatusChange,
+    streamId,
+    vodId
+  ]);
   react.useEffect(() => {
     if (!streamId) return;
     const sessionId = crypto.randomUUID();
@@ -1277,6 +1302,15 @@ function LivoPlayer({
     () => safeTheme ? embedThemeCssVars(safeTheme) : void 0,
     [safeTheme]
   );
+  react.useEffect(() => {
+    if (!playbackUrl) {
+      onPlaybackState?.(
+        stream?.status === "ended" ? "ended" : resolved ? "waiting" : "loading"
+      );
+      return;
+    }
+    onPlaybackState?.("playing");
+  }, [onPlaybackState, playbackUrl, resolved, stream?.status]);
   const flags = stream?.community ?? vod?.community;
   const communityTargetId = streamId ?? vodId;
   const communityKind = streamId ? "stream" : "vod";
@@ -1358,6 +1392,9 @@ function LivoPlayer({
         captionsEnabled: stream ? Boolean(stream.captionsUrl) : Boolean(vod?.captionsEnabled),
         liveCaptionsBaseUrl: stream?.status === "public" ? stream.captionsUrl ?? void 0 : void 0,
         onFirstPlay: () => beacon?.track({ type: "view" }),
+        onPlayingChange: (playing) => {
+          onPlaybackState?.(playing ? "playing" : "paused");
+        },
         onPlaybackProgress: (currentTime, duration) => {
           beacon?.track({ type: "progress", currentTime, duration });
           onProgress?.({
@@ -1377,6 +1414,7 @@ function LivoPlayer({
             errorCode: error && typeof error === "object" && "kind" in error ? String(error.kind) : "playback"
           });
           onError?.({ code: "playback" });
+          onPlaybackState?.("error");
         }
       }
     )
@@ -1495,6 +1533,7 @@ exports.decodeEmbedTheme = decodeEmbedTheme;
 exports.embedShowsCommunity = embedShowsCommunity;
 exports.encodeEmbedTheme = encodeEmbedTheme;
 exports.playerUrl = playerUrl;
+exports.resolveEmbedThemeInput = resolveEmbedThemeInput;
 exports.sanitizeEmbedTheme = sanitizeEmbedTheme;
 exports.studioGuestUrl = studioGuestUrl;
 exports.studioHostUrl = studioHostUrl;