@nowsoft-lab/chear-widget-react 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @nowsoft-lab/chear-widget-react
+
+치어(CHEAR) 위젯 — 방송 **플레이어**와 **채팅**을 리액트 앱에 컴포넌트로 넣습니다.
+스튜디오 › 위젯의 iframe 위젯과 같은 화면 · 같은 동작이고, 위젯이 바뀌면 이 패키지를 다시 설치하지 않아도 같이 바뀝니다.
+
+## 설치
+
+```sh
+npm i @nowsoft-lab/chear-widget-react
+```
+
+React 18 이상. Next.js(App Router)에서도 그대로 씁니다(`"use client"` 포함 — 서버에서는 빈 div 만 그리고 브라우저에서 위젯이 뜹니다).
+npm 을 쓸 수 없으면 위젯 출처의 설치 파일로도 받을 수 있습니다: `npm i https://player.chear.live/sdk/chear-widget-react.tgz`
+
+## 사용
+
+```tsx
+import { ChearPlayer, ChearChat } from "@nowsoft-lab/chear-widget-react";
+
+<ChearPlayer channel="채널아이디" />
+<ChearChat channel="채널아이디" />
+```
+
+`channel` 은 스튜디오에 보이는 @아이디입니다. 이것만 넣으면 동작합니다.
+
+### 플레이어 `<ChearPlayer>`
+
+| prop | 기본 | 뜻 |
+|---|---|---|
+| `channel` | (필수) | 채널 아이디 |
+| `autoplay` | `true` | 자동 재생(브라우저 정책상 소리 끔과 함께만 확실) |
+| `muted` | `true` | 소리 끔으로 시작 |
+| `controls` | `true` | 플레이어 컨트롤 |
+| `chat` | `false` | 오른쪽(좁은 세로 화면은 아래)에 채팅 같이 |
+| `stats` | `true` | 왼쪽 위 LIVE · 시청 중 |
+
+크기: 폭 100% · 16:9 가 기본. `style={{ width: 1280 }}` · `className` 으로 바꿉니다.
+
+### 채팅 `<ChearChat>`
+
+| prop | 기본 | 뜻 |
+|---|---|---|
+| `channel` | (필수) | 채널 아이디 |
+| `theme` | `"dark"` | `"dark"` · `"light"` |
+
+크기: 폭 100% · 부모 높이(없으면 최소 480px). 로그인은 위젯 안에서 합니다(이메일 · 가입).
+
+### 공통
+
+| prop | 뜻 |
+|---|---|
+| `ssoToken` | 간편 로그인(SSO) 토큰 — 파트너 회원으로 바로 채팅(스튜디오 › 위젯 › 채팅 › 간편 로그인 안내). 바뀌면 다시 로그인 |
+| `origin` | 위젯 출처(기본 `https://player.chear.live`). 여러 개면 `<ChearProvider origin="…">` 로 감쌉니다 |
+| `onError` | 위젯을 불러오지 못했을 때(네트워크 · 사이트 보안 정책) |
+
+## 동작 방식 · 주의
+
+- 화면은 위젯 출처의 런타임(`https://player.chear.live/sdk/v1/runtime.js`)이 그립니다. 처음 한 번 받고 캐시합니다.
+- 컴포넌트의 div 안 **Shadow DOM** 에 그려서 페이지 스타일과 섞이지 않습니다. 모달 · 로그인 창도 위젯 틀 안에만 뜹니다.
+- 사이트에 CSP 를 쓰면 `script-src` · `connect-src` · `media-src` · `img-src` 에 위젯 출처와 영상 · Firebase 주소를 넣어야 합니다.
+- 로그인 토큰은 이 페이지의 localStorage(`chear.widget:` 로 시작하는 키)에 둡니다. 채팅 · 내 정보 · 신고 · 팔로우만 되는 짧은 토큰입니다. 더 강한 격리가 필요하면 iframe 위젯을 쓰세요.
+- 채널 설정의 "퍼가기 허용"을 그대로 따릅니다(꺼져 있으면 안내만). 채널에 허용 도메인이 있으면 그 사이트에서만 로그인할 수 있습니다(아니면 EMB-005).
+
+## 판
+
+- 이 패키지는 껍데기라 판이 거의 바뀌지 않습니다. 위젯 화면 · 기능 개선은 런타임(`/sdk/v1/`)으로 바로 반영됩니다.
+- props 가 바뀌는 큰 변경이면 런타임 `/sdk/v2/` 와 이 패키지 2.x 를 같이 냅니다(1.x 는 한동안 유지).
 
-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.

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { ChatOptions, PlayerOptions } from "./types";
+export { DEFAULT_ORIGIN, loadRuntime, runtimeUrl } from "./loader";
+export type { ChatOptions, PlayerOptions } from "./types";
+/** 위젯 출처를 바꿀 때만(개발서버 · 다른 플랫폼). 운영 치어는 필요 없음 */
+export declare function ChearProvider({ origin, children }: {
+    origin: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+interface CommonProps {
+    /** 채널 아이디 — 스튜디오에 보이는 @아이디(위젯 주소의 /embed/{아이디}/…) */
+    channel: string;
+    /** 간편 로그인(SSO) 토큰 — 파트너 회원으로 바로 채팅. 없으면 위젯 안 로그인 */
+    ssoToken?: string;
+    /** 위젯 출처 — ChearProvider 보다 우선 */
+    origin?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** 런타임을 못 불러왔을 때(네트워크 · 사이트 CSP 등) */
+    onError?: (error: unknown) => void;
+}
+export type ChearPlayerProps = CommonProps & PlayerOptions;
+export type ChearChatProps = CommonProps & ChatOptions;
+/** 플레이어 — 기본 폭 100% · 16:9. `chat` 이면 오른쪽에 채팅 같이 */
+export declare function ChearPlayer({ autoplay, muted, controls, chat, stats, ...common }: ChearPlayerProps): import("react").JSX.Element;
+/** 채팅 — 실제로 채팅(위젯 안 로그인 · 이모티콘 · 신고). 기본 폭 100% · 부모 높이(없으면 최소 480px) */
+export declare function ChearChat({ theme, ...common }: ChearChatProps): import("react").JSX.Element;

package/dist/index.js

@@ -0,0 +1,66 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+import { DEFAULT_ORIGIN, loadRuntime } from "./loader";
+export { DEFAULT_ORIGIN, loadRuntime, runtimeUrl } from "./loader";
+/**
+ * 치어 위젯 — 플레이어 · 채팅을 리액트 컴포넌트로 (docs/design/embed-sdk.md).
+ * 화면은 위젯 출처의 런타임(`/sdk/v1/runtime.js`)이 그린다 — 스튜디오 › 위젯의 iframe 위젯과 같은 화면 · 같은 동작.
+ * 파트너 페이지 스타일과 섞이지 않게 컴포넌트의 div 안 Shadow DOM 에 그린다.
+ */
+const OriginContext = createContext(DEFAULT_ORIGIN);
+/** 위젯 출처를 바꿀 때만(개발서버 · 다른 플랫폼). 운영 치어는 필요 없음 */
+export function ChearProvider({ origin, children }) {
+    return _jsx(OriginContext.Provider, { value: origin, children: children });
+}
+/** 정의된 값만 — 없는 옵션은 위젯 기본값 */
+function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+function Widget({ kind, channel, ssoToken, origin, className, style, onError, options, defaultStyle }) {
+    const fromContext = useContext(OriginContext);
+    const target = origin ?? fromContext;
+    const host = useRef(null);
+    const instance = useRef(null);
+    const [failed, setFailed] = useState(false);
+    const config = { kind, channel, options: defined(options), ssoToken };
+    const latest = useRef(config);
+    latest.current = config;
+    const onErrorRef = useRef(onError);
+    onErrorRef.current = onError;
+    // 출처마다 한 번 그린다 — 옵션 · 채널이 바뀌면 아래 update 로
+    useEffect(() => {
+        const el = host.current;
+        if (!el)
+            return;
+        let cancelled = false;
+        setFailed(false);
+        loadRuntime(target).then((runtime) => {
+            if (!cancelled)
+                instance.current = runtime.mount(el, latest.current);
+        }, (error) => {
+            if (cancelled)
+                return;
+            setFailed(true);
+            onErrorRef.current?.(error);
+        });
+        return () => {
+            cancelled = true;
+            instance.current?.unmount();
+            instance.current = null;
+        };
+    }, [target]);
+    const key = JSON.stringify(config);
+    useEffect(() => {
+        instance.current?.update(latest.current);
+    }, [key]);
+    return _jsx("div", { ref: host, className: className, style: { ...defaultStyle, ...style }, "data-chear-widget": kind, "data-failed": failed || undefined });
+}
+/** 플레이어 — 기본 폭 100% · 16:9. `chat` 이면 오른쪽에 채팅 같이 */
+export function ChearPlayer({ autoplay, muted, controls, chat, stats, ...common }) {
+    return _jsx(Widget, { kind: "player", options: { autoplay, muted, controls, chat, stats }, defaultStyle: { display: "block", width: "100%", aspectRatio: "16 / 9" }, ...common });
+}
+/** 채팅 — 실제로 채팅(위젯 안 로그인 · 이모티콘 · 신고). 기본 폭 100% · 부모 높이(없으면 최소 480px) */
+export function ChearChat({ theme, ...common }) {
+    return _jsx(Widget, { kind: "chat", options: { theme }, defaultStyle: { display: "block", width: "100%", height: "100%", minHeight: 480 }, ...common });
+}

package/dist/loader.d.ts

@@ -0,0 +1,13 @@
+import type { WidgetRuntime } from "./types";
+/** 운영 위젯 출처 — 개발 · 다른 플랫폼은 <ChearProvider origin="…"> */
+export declare const DEFAULT_ORIGIN = "https://player.chear.live";
+/** 런타임 판 — 위젯 출처의 /sdk/v{N}/runtime.js */
+export declare const RUNTIME_VERSION = 1;
+/** `https://player.chear.live/` · 경로가 붙은 주소 → 출처만 */
+export declare function normalizeOrigin(origin: string): string;
+export declare const runtimeUrl: (origin: string) => string;
+/**
+ * 런타임을 위젯 출처에서 한 번만 받는다(같은 출처면 컴포넌트 여러 개가 같이 씀).
+ * 화면은 런타임에 있어서 위젯이 바뀌면 이 패키지를 다시 받지 않아도 같이 바뀐다. 실패하면 다음 시도 때 다시 받는다
+ */
+export declare function loadRuntime(origin?: string): Promise<WidgetRuntime>;

package/dist/loader.js

@@ -0,0 +1,32 @@
+/** 운영 위젯 출처 — 개발 · 다른 플랫폼은 <ChearProvider origin="…"> */
+export const DEFAULT_ORIGIN = "https://player.chear.live";
+/** 런타임 판 — 위젯 출처의 /sdk/v{N}/runtime.js */
+export const RUNTIME_VERSION = 1;
+/** `https://player.chear.live/` · 경로가 붙은 주소 → 출처만 */
+export function normalizeOrigin(origin) {
+    return new URL(origin).origin;
+}
+export const runtimeUrl = (origin) => `${normalizeOrigin(origin)}/sdk/v${RUNTIME_VERSION}/runtime.js`;
+const loading = new Map();
+/**
+ * 런타임을 위젯 출처에서 한 번만 받는다(같은 출처면 컴포넌트 여러 개가 같이 씀).
+ * 화면은 런타임에 있어서 위젯이 바뀌면 이 패키지를 다시 받지 않아도 같이 바뀐다. 실패하면 다음 시도 때 다시 받는다
+ */
+export function loadRuntime(origin = DEFAULT_ORIGIN) {
+    const url = runtimeUrl(origin);
+    let pending = loading.get(url);
+    if (!pending) {
+        // 런타임 조각들이 실행되기 전에 "위젯 SDK 로 돈다 · 위젯 출처"를 알린다(런타임이 파트너 문서의 <html> 을 건드리지 않게)
+        const g = globalThis;
+        g.__CHEAR_SDK__ ?? (g.__CHEAR_SDK__ = { origin: normalizeOrigin(origin) });
+        pending = import(/* @vite-ignore */ /* webpackIgnore: true */ url).then((mod) => {
+            const runtime = mod.default;
+            if (!runtime || runtime.version !== RUNTIME_VERSION)
+                throw new Error(`치어 위젯 런타임을 불러오지 못했어요(${url})`);
+            return runtime;
+        });
+        pending.catch(() => loading.delete(url));
+        loading.set(url, pending);
+    }
+    return pending;
+}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 위젯 런타임과의 약속(v1) — 런타임 쪽 같은 모양: user-web `src/sdk/types.ts`. 바꾸면 둘 다 같이(docs/design/embed-sdk.md 2장)
+ */
+/** 플레이어 옵션 — 위젯 주소 쿼리와 같은 이름 · 같은 기본값 */
+export interface PlayerOptions {
+    /** 자동 재생(기본 켬 — 브라우저 정책상 소리 끔과 함께만 확실) */
+    autoplay?: boolean;
+    /** 소리 끔(기본 켬) */
+    muted?: boolean;
+    /** 플레이어 컨트롤(기본 켬) */
+    controls?: boolean;
+    /** 오른쪽(좁은 세로 화면은 아래)에 채팅 같이(기본 끔) */
+    chat?: boolean;
+    /** 왼쪽 위 LIVE · 시청 중(기본 켬) */
+    stats?: boolean;
+}
+/** 채팅 옵션 */
+export interface ChatOptions {
+    /** 다크(기본) · 라이트 */
+    theme?: "dark" | "light";
+}
+export type WidgetKind = "player" | "chat";
+export interface WidgetConfig {
+    kind: WidgetKind;
+    channel: string;
+    options?: PlayerOptions | ChatOptions;
+    ssoToken?: string;
+}
+export interface WidgetInstance {
+    update(config: WidgetConfig): void;
+    unmount(): void;
+}
+export interface WidgetRuntime {
+    version: 1;
+    origin: string;
+    mount(host: HTMLElement, config: WidgetConfig): WidgetInstance;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * 위젯 런타임과의 약속(v1) — 런타임 쪽 같은 모양: user-web `src/sdk/types.ts`. 바꾸면 둘 다 같이(docs/design/embed-sdk.md 2장)
+ */
+export {};

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@nowsoft-lab/chear-widget-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "치어(CHEAR) 위젯 — 플레이어 · 채팅을 리액트 컴포넌트로. <ChearPlayer channel=\"…\" />",
+  "keywords": [
+    "chear",
+    "react",
+    "live",
+    "streaming",
+    "player",
+    "chat",
+    "widget"
+  ],
+  "homepage": "https://www.chear.live/developers/api#widget-sdk",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "pack:sdk": "pnpm build && node scripts/pack-sdk.mjs",
+    "prepublishOnly": "pnpm build && pnpm test",
+    "release": "bash scripts/publish.sh"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "vitest": "^5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}