@xmaxai/sdk 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -13,12 +13,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 构建时区域开关 `XMAX_SDK_REGION`（`cn` | `global`），经 tsup 内联注入默认 `baseUrl`。
 - `XMAX_OPEN_API_BASE_URLS` 常量与 `XmaxSdkRegion` 类型。
 - `build:cn` / `build:global` / `publish:cn` / `publish:global` / `publish:all` 脚本及 `scripts/publish-sdk.mjs`。
+- `connect` 支持可选的 `onError` / `onDisconnect`（与 Decart Overview 对齐；不传则行为与原先一致）。
 
 ### Changed
 
 - `XMAX_OPEN_API_PRODUCTION_BASE_URL` 现按构建区域解析（默认 `cn`），不再硬编码单一地址。
+- **根入口正式对外**：`createXmaxClient` / `models` 等从 `@xmaxai/sdk`（或 `@xmaxai/sdk-global`）直接导入，不再标 `@deprecated`。
+- 移除 `@xmaxai/sdk/experimental` 子路径（发版前无外部依赖）；Realtime API 仅通过根入口导出。
+- 错误通过 `onError` 通知调用方处理。
 
-## [1.0.0 ] - 2026-07-01
+### Removed
+
+- Package export `./experimental` and `src/experimental` barrel.
+- Deprecated aliases and no-ops: `mirrorInput`, `setMode` / `RealtimeSetModeOptions`, `preserveLocalInput`, `getContentRect`, `RTC_PUBLISH_FPS`, `waitForRtcOutboundBeforeStart`, `waitForPublishedInputFramesBeforeStart`, React `changeModel`.
+
+## [1.0.2 ] - 2026-07-01
 
 ### Added
 
@@ -26,7 +35,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `XMAX_OPEN_API_PRODUCTION_BASE_URL` constant for explicit production API endpoint configuration.
 - `@xmaxai/sdk/experimental` subpath for `createXmaxClient`, drag, and related APIs.
 - Unit tests for RTC event builders, video size utilities, and HTTP client request handling.
-- Inline SVG icons for built-in error toasts (no host static assets required).
 
 ### Changed
 

package/README.md

@@ -28,8 +28,8 @@ npm install @xmaxai/sdk-global
 
 | 入口 | 说明 |
 |------|------|
-| `@xmaxai/sdk/experimental` | **推荐** — `createXmaxClient`、`models` |
-| `@xmaxai/sdk` | HTTP Client、`RtcManager`、房间事件等底层 API |
+| `@xmaxai/sdk` | **推荐** — `createXmaxClient`、`models`，以及 HTTP Client / RTC 底层 API |
+| `@xmaxai/sdk/react` | React bindings（可选） |
 
 ## 快速开始
 
@@ -38,7 +38,7 @@ npm install @xmaxai/sdk-global
 `baseUrl` 已内置生产环境默认值，一般无需传入；仅在 staging / 私有部署时覆盖。
 
 ```ts
-import { createXmaxClient, models } from "@xmaxai/sdk/experimental";
+import { createXmaxClient, models } from "@xmaxai/sdk";
 
 const model = models.realtime("x2.0");
 
@@ -84,7 +84,8 @@ await realtimeClient.disconnect();
 - `connect()` 自动完成：createSession → heartbeat → join RTC → 推流 →（`autoStart: true` 时）发送 start。
 - `initialState.prompt` 传 `{ text: string }`；`initialState.image` 传参考图 URL。
 - 宿主自行提供 `#video-input` / `#video-output` 容器元素。
-- 未传 `onError` 时，API/RTC 错误会弹出内置 toast；传入 `onError` 则完全覆盖。
+- API/RTC 错误通过 `onError` 回调交给调用方处理。在 `createXmaxClient` 或 `connect` 任一处传入即可（`connect` 优先）。
+- `onDisconnect` 仅在 session 成功建立后断开时触发；`connect()` 失败不会回调。
 
 ### 自定义 baseUrl（可选）
 
@@ -92,7 +93,7 @@ await realtimeClient.disconnect();
 import {
   createXmaxClient,
   XMAX_OPEN_API_PRODUCTION_BASE_URL,
-} from "@xmaxai/sdk/experimental";
+} from "@xmaxai/sdk";
 
 const client = createXmaxClient({
   apiKey: "<YOUR_XMAX_API_KEY>",
@@ -124,6 +125,9 @@ client.realtime.connect(stream, {
   model: RealtimeModel,     // models.realtime("x2.0")
   localElement?: HTMLElement,
   remoteElement?: HTMLElement,
+  onRemoteStream?: (stream: MediaStream) => void,
+  onError?: (message, error?) => void,  // optional; overrides createXmaxClient.onError
+  onDisconnect?: (reason) => void,      // "client" | "session_inactive" | "heartbeat_error"
   mirror?: "auto" | boolean,
   initialState?: {
     prompt?: string | { text: string },

package/dist/{chunk-M5QA6LWS.js → chunk-F567ONBH.js}

@@ -1,149 +1,14 @@
-import { createSDKI18n, resolveApiErrorMessage, resolvePlaybackDrivenEncoderFps, mountCaptureVideo } from './chunk-PLU2YVAS.js';
+import { createSDKI18n, resolveApiErrorMessage, resolvePlaybackDrivenEncoderFps, mountCaptureVideo } from './chunk-TFGYBN3Q.js';
 import COS from 'cos-js-sdk-v5';
 import VERTC, { VideoSourceType, MediaType, StreamIndex, RoomProfileType, MirrorType, VideoCodecType, VideoRenderMode } from '@volcengine/rtc';
 
-// src/shared/browser-toast.ts
-var TOAST_ROOT_ID = "Xmax-sdk-toast-root";
-var TOAST_DURATION_MS = 3e3;
-var toastSeed = 0;
-var timeoutMap = /* @__PURE__ */ new Map();
-var elementMap = /* @__PURE__ */ new Map();
-function ensureToastRoot() {
-  if (typeof document === "undefined") {
-    return null;
-  }
-  let root = document.getElementById(TOAST_ROOT_ID);
-  if (root) {
-    return root;
-  }
-  root = document.createElement("div");
-  root.id = TOAST_ROOT_ID;
-  root.setAttribute("aria-live", "polite");
-  Object.assign(root.style, {
-    position: "fixed",
-    left: "50%",
-    top: "24px",
-    transform: "translateX(-50%)",
-    zIndex: "3000",
-    display: "flex",
-    flexDirection: "column",
-    alignItems: "center",
-    gap: "12px",
-    pointerEvents: "none"
-  });
-  document.body.appendChild(root);
-  return root;
-}
-function createIcon(type) {
-  const icon = document.createElement("span");
-  icon.setAttribute("aria-hidden", "true");
-  icon.innerHTML = type === "success" ? '<svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 12 12" fill="none"><path d="M10 3L4.5 8.5 2 6" stroke="#4ade80" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>' : '<svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 12 12" fill="none"><circle cx="6" cy="6" r="5" stroke="#f87171" stroke-width="1.5"/><path d="M4 4l4 4M8 4L4 8" stroke="#f87171" stroke-width="1.5" stroke-linecap="round"/></svg>';
-  Object.assign(icon.style, {
-    display: "inline-flex",
-    width: "12px",
-    height: "12px",
-    flexShrink: "0"
-  });
-  return icon;
-}
-function clearToastTimer(id) {
-  const timer = timeoutMap.get(id);
-  if (timer) {
-    window.clearTimeout(timer);
-    timeoutMap.delete(id);
-  }
-}
-function destroyToast(id) {
-  if (!id) {
-    timeoutMap.forEach((timer) => window.clearTimeout(timer));
-    timeoutMap.clear();
-    elementMap.forEach((element2) => element2.remove());
-    elementMap.clear();
-    const root2 = typeof document !== "undefined" ? document.getElementById(TOAST_ROOT_ID) : null;
-    root2?.remove();
-    return;
-  }
-  clearToastTimer(id);
-  const element = elementMap.get(id);
-  element?.remove();
-  elementMap.delete(id);
-  const root = typeof document !== "undefined" ? document.getElementById(TOAST_ROOT_ID) : null;
-  if (root && !root.childElementCount) {
-    root.remove();
-  }
-}
-function showToast(type, message, options) {
-  const root = ensureToastRoot();
-  if (!root) {
-    return "";
-  }
-  const id = options?.key || `toast-${Date.now()}-${++toastSeed}`;
-  clearToastTimer(id);
-  elementMap.get(id)?.remove();
-  const isMobile = typeof window !== "undefined" && window.matchMedia("(max-width: 768px)").matches;
-  const textSize = isMobile ? "12px" : "14px";
-  const toast = document.createElement("div");
-  toast.setAttribute("role", "status");
-  Object.assign(toast.style, {
-    pointerEvents: "auto",
-    display: "flex",
-    alignItems: "center",
-    gap: "12px",
-    minWidth: "240px",
-    padding: "16px",
-    borderRadius: "12px",
-    border: "1px solid rgba(255, 255, 255, 0.20)",
-    background: "rgba(0, 0, 0, 0.80)",
-    boxShadow: "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)",
-    fontFamily: "Rubik, ui-sans-serif, system-ui, sans-serif",
-    fontSize: textSize,
-    fontWeight: "400",
-    lineHeight: "14px"
-  });
-  const content = document.createElement("span");
-  content.textContent = message;
-  Object.assign(content.style, {
-    paddingRight: "0px",
-    textAlign: "center",
-    color: "#ffffff",
-    fontFamily: "Rubik, ui-sans-serif, system-ui, sans-serif",
-    fontSize: textSize,
-    fontWeight: "400",
-    lineHeight: "14px"
-  });
-  toast.appendChild(createIcon(type));
-  toast.appendChild(content);
-  root.appendChild(toast);
-  elementMap.set(id, toast);
-  const timer = window.setTimeout(() => {
-    destroyToast(id);
-  }, options?.duration ?? TOAST_DURATION_MS);
-  timeoutMap.set(id, timer);
-  return id;
-}
-var browserToast = {
-  success(message, options) {
-    return showToast("success", message, options);
-  },
-  error(message, options) {
-    return showToast("error", message, options);
-  },
-  destroy(id) {
-    destroyToast(id);
-  }
-};
-
 // src/shared/error-utils.ts
 function notifyError(error, notifier, fallbackMessage) {
   const resolved = error instanceof Error ? error : Object.assign(new Error(fallbackMessage), { cause: error });
-  if (!resolved.__XmaxNotified) {
+  if (!resolved.__XmaxNotified && notifier) {
     resolved.__XmaxNotified = true;
     const message = resolved.message || fallbackMessage;
-    if (notifier) {
-      notifier(message, error);
-    } else if (typeof window !== "undefined" && typeof document !== "undefined") {
-      browserToast.error(message);
-    }
+    notifier(message, error);
   }
   return resolved;
 }
@@ -215,7 +80,7 @@ var XmaxOpenClient = class {
     }
     throw notifyError(error, this.onError, message);
   }
-  /** Stop heartbeat, abort in-flight API requests, and suppress error toasts during teardown. */
+  /** Stop heartbeat, abort in-flight API requests, and suppress error notifications during teardown. */
   beginTeardown() {
     this.suppressErrorNotification = true;
     this.stopHeartbeat();
@@ -271,7 +136,8 @@ var XmaxOpenClient = class {
         return p.data;
       }
       const mappedMessage = resolveApiErrorMessage(p.code, this.i18n.locale);
-      const errorMessage = mappedMessage ?? this.i18n.t("errors.requestRetry");
+      const backendMessage = typeof p.message === "string" && p.message.trim() ? p.message.trim() : void 0;
+      const errorMessage = mappedMessage ?? backendMessage ?? this.i18n.t("errors.requestRetry");
       throw new Error(errorMessage);
     } catch (error) {
       if (this.isAbortError(error)) {
@@ -423,6 +289,7 @@ function createStartRtcRoomEvent(input) {
   const resolvedPrompt = input.prompt?.trim() ?? "";
   const refImagePath = input.refImagePath?.trim() || input.refImage?.trim() || void 0;
   const useRefImage = !!refImagePath;
+  const staticImagePath = input.staticImagePath?.trim() || void 0;
   return {
     event: "start",
     user_id: input.userId?.trim() || void 0,
@@ -434,7 +301,9 @@ function createStartRtcRoomEvent(input) {
       prompt: resolvedPrompt,
       ref_image_path: useRefImage ? refImagePath : void 0,
       ref_image: useRefImage ? refImagePath : void 0,
-      static_generate: input.staticGenerate === void 0 ? void 0 : input.staticGenerate,
+      // Instant-only — omit when false/undefined so non-instant starts never carry leftover flags.
+      static_generate: input.staticGenerate === true ? true : void 0,
+      static_image_path: staticImagePath,
       ...input.extraParams ?? {}
     }
   };
@@ -714,7 +583,7 @@ var _RtcManager = class _RtcManager {
     this.lastRemoteSei = null;
     this.lastRemoteSeiUserId = null;
     this.hasLoggedSeiSendFailure = false;
-    if (previousExpectedRemoteSei !== this.expectedRemoteSei && this.remoteVideoUserId) {
+    if (previousExpectedRemoteSei !== this.expectedRemoteSei && this.remoteVideoUserId && !this.preserveRemoteDom) {
       this.pendingRemoteVideoUserId = this.remoteVideoUserId;
       this.remoteVideoUserId = null;
     }
@@ -1062,45 +931,6 @@ var _RtcManager = class _RtcManager {
       sentFrameRate: this.lastObservedSentFrameRate
     });
   }
-  /** @deprecated Use {@link ensurePublishedInputBeforeStart}. */
-  async waitForRtcOutboundBeforeStart(options) {
-    const timeoutMs = options?.timeoutMs ?? PUBLISH_READY_TIMEOUT_MS;
-    const publishAgeMs = this.publishStartedAtMs > 0 ? performance.now() - this.publishStartedAtMs : 0;
-    const localFramesPromise = publishAgeMs >= PUBLISH_WARM_SKIP_MS ? Promise.resolve({ ready: true, frameCount: 0, elapsedMs: 0 }) : this.waitForPublishedInputFrames({
-      minFrames: PUBLISH_START_MIN_FRAMES,
-      timeoutMs: PUBLISH_START_FRAME_TIMEOUT_MS
-    });
-    const [, rtcReady] = await Promise.all([
-      localFramesPromise,
-      this.waitForLocalPublishReady({ timeoutMs })
-    ]);
-    return rtcReady;
-  }
-  /** @deprecated Use {@link waitForRtcOutboundBeforeStart}. */
-  async waitForPublishedInputFramesBeforeStart() {
-    const waitOptions = this.resolveInputFrameWaitOptions();
-    const waitTasks = [
-      this.waitForLocalPublishReady({ timeoutMs: PUBLISH_READY_TIMEOUT_MS })
-    ];
-    if (waitOptions) {
-      waitTasks.push(
-        this.waitForMinPublishDuration(waitOptions.minPublishMs),
-        this.waitForPublishedInputFrames({
-          minFrames: waitOptions.minFrames,
-          timeoutMs: waitOptions.timeoutMs
-        })
-      );
-    }
-    const [rtcResult, ...rest] = await Promise.all(waitTasks);
-    const rtcSend = rtcResult;
-    const frameResult = waitOptions ? rest[1] : { ready: true, frameCount: 0, elapsedMs: 0 };
-    return {
-      ...frameResult,
-      rtcSendReady: rtcSend.ready,
-      rtcSendReason: rtcSend.reason,
-      rtcSendElapsedMs: rtcSend.elapsedSincePublishMs
-    };
-  }
   async waitForMinPublishDuration(minMs) {
     if (minMs <= 0 || this.publishStartedAtMs <= 0) {
       return;
@@ -2202,9 +2032,6 @@ function getFitContentRect(rect, targetSize, fitMode = "contain") {
     height
   };
 }
-function getContentRect(rect, targetSize) {
-  return getFitContentRect(rect, targetSize, "contain");
-}
 function findDragMediaElement(dragSurface) {
   const root = dragSurface.parentElement ?? dragSurface;
   if (typeof root.querySelector !== "function") {
@@ -2370,6 +2197,7 @@ function drawNeon(ctx, segs, container, targetSize, dpr, fitMode, mirrored) {
 }
 var DragTrackController = class {
   constructor(container, options) {
+    this.strokeActive = false;
     this.activePointers = /* @__PURE__ */ new Map();
     this.lastTargetPoints = /* @__PURE__ */ new Map();
     this.segQueue = [];
@@ -2379,6 +2207,8 @@ var DragTrackController = class {
     this.resizeObserver = null;
     this.container = container;
     this.onTracks = options.onTracks;
+    this.onStrokeStart = options.onStrokeStart;
+    this.onStrokeEnd = options.onStrokeEnd;
     this.targetSize = options.targetSize;
     this.fitMode = options.fitMode ?? "cover";
     this.mirrored = options.mirrored ?? false;
@@ -2549,11 +2379,17 @@ var DragTrackController = class {
       this.flushTracks();
     }, 30);
   }
-  finishStroke() {
+  finishStroke(emitEnd = false) {
+    const wasActive = this.strokeActive;
+    this.strokeActive = false;
     this.stopSampling();
     this.stopDrawLoop();
     this.segQueue.length = 0;
     this.clearCanvas();
+    if (emitEnd && wasActive && this.onStrokeEnd) {
+      Promise.resolve(this.onStrokeEnd()).catch(() => {
+      });
+    }
   }
   handlePointerDown(e) {
     if (!this.enabled) {
@@ -2577,6 +2413,12 @@ var DragTrackController = class {
     if (targetPoint) {
       this.lastTargetPoints.set(e.pointerId, targetPoint);
     }
+    const strokeWasActive = this.strokeActive;
+    this.strokeActive = true;
+    if (!strokeWasActive && this.onStrokeStart) {
+      Promise.resolve(this.onStrokeStart()).catch(() => {
+      });
+    }
     this.startDrawLoop();
     this.startSampling();
   }
@@ -2609,7 +2451,7 @@ var DragTrackController = class {
     } catch {
     }
     if (this.activePointers.size === 0) {
-      this.finishStroke();
+      this.finishStroke(true);
     }
   }
   handlePointerCancel(e) {
@@ -2619,7 +2461,7 @@ var DragTrackController = class {
     this.activePointers.delete(e.pointerId);
     this.lastTargetPoints.delete(e.pointerId);
     if (this.activePointers.size === 0) {
-      this.finishStroke();
+      this.finishStroke(true);
     }
   }
 };
@@ -2644,6 +2486,6 @@ var models = {
   }
 };
 
-export { ACTIVE_STATUS, PREVIEW_CONTAIN_ATTR, PREVIEW_COVER_ATTR, PREVIEW_OUTPUT_LAYOUT_ATTR, PREVIEW_UPLOAD_FIT_ATTR, PREVIEW_UPLOAD_LAYOUT_ATTR, PUBLISH_COLD_FRAME_TIMEOUT_MS, PUBLISH_COLD_MIN_FRAMES, PUBLISH_COLD_WARMUP_MS, PUBLISH_START_FRAME_TIMEOUT_MS, PUBLISH_START_MIN_FRAMES, PUBLISH_WARM_SKIP_MS, RtcManager, XMAX_OPEN_API_BASE_URLS, XMAX_OPEN_API_PRODUCTION_BASE_URL, XmaxOpenClient, applyUploadPreviewMediaLayout, browserToast, classifyCameraAccessError, createDragTrackController, createNativeCameraStream, createStartRtcRoomEvent, createStopRtcRoomEvent, createTaskUid, createTracksRtcRoomEvent, getCameraEnvironmentIssue, getContentRect, getFitContentRect, isCameraAccessError, mapTargetPointToCanvas, mapViewportPointToCoordinateSpace, models, notifyError, observeUploadPreviewMediaLayout, openNativeCameraStream, requestCameraMediaStream, stabilizeCameraVideoTrack };
-//# sourceMappingURL=chunk-M5QA6LWS.js.map
-//# sourceMappingURL=chunk-M5QA6LWS.js.map
+export { ACTIVE_STATUS, PREVIEW_CONTAIN_ATTR, PREVIEW_COVER_ATTR, PREVIEW_OUTPUT_LAYOUT_ATTR, PREVIEW_UPLOAD_FIT_ATTR, PREVIEW_UPLOAD_LAYOUT_ATTR, PUBLISH_COLD_FRAME_TIMEOUT_MS, PUBLISH_COLD_MIN_FRAMES, PUBLISH_COLD_WARMUP_MS, PUBLISH_START_FRAME_TIMEOUT_MS, PUBLISH_START_MIN_FRAMES, PUBLISH_WARM_SKIP_MS, RtcManager, XMAX_OPEN_API_BASE_URLS, XMAX_OPEN_API_PRODUCTION_BASE_URL, XmaxOpenClient, applyUploadPreviewMediaLayout, classifyCameraAccessError, createDragTrackController, createNativeCameraStream, createStartRtcRoomEvent, createStopRtcRoomEvent, createTaskUid, createTracksRtcRoomEvent, getCameraEnvironmentIssue, getFitContentRect, isCameraAccessError, mapTargetPointToCanvas, mapViewportPointToCoordinateSpace, models, notifyError, observeUploadPreviewMediaLayout, openNativeCameraStream, requestCameraMediaStream, stabilizeCameraVideoTrack };
+//# sourceMappingURL=chunk-F567ONBH.js.map
+//# sourceMappingURL=chunk-F567ONBH.js.map