@xmaxai/sdk 0.1.0 → 1.0.1

package/dist/experimental/index.d.cts

@@ -1,2 +1,2 @@
-export { D as DragTrackController, a as DragTrackControllerOptions, R as RealtimeConnectOptions, b as RealtimeInitialState, c as RealtimeModel, d as RealtimePrewarmHandle, e as RealtimePromptState, f as RealtimeRestartOptions, g as RealtimeSession, h as RealtimeSetImageOptions, i as RealtimeSetInput, j as RealtimeSetModeOptions, k as RemoteViewHost, X as XmaxClient, l as XmaxClientFiles, m as XmaxClientOptions, n as XmaxRealtimeSession, o as createDragTrackController, q as createRemoteViewHost, r as createXmaxClient, s as getContentRect, t as mapTargetPointToCanvas, u as mapViewportPointToCoordinateSpace, v as models, w as observeDragSurfaceVideoSync, y as syncDragSurfaceToVideo } from '../index-Dai62Sos.cjs';
+export { D as DragTrackController, a as DragTrackControllerOptions, R as RealtimeConnectOptions, b as RealtimeInitialState, c as RealtimeModel, d as RealtimePrewarmHandle, e as RealtimePromptState, f as RealtimeRestartOptions, g as RealtimeSession, h as RealtimeSetImageOptions, i as RealtimeSetInput, j as RealtimeSetModeOptions, k as RemoteViewHost, X as XmaxClient, l as XmaxClientFiles, m as XmaxClientOptions, n as XmaxRealtimeSession, o as createDragTrackController, q as createRemoteViewHost, r as createXmaxClient, s as getContentRect, t as mapTargetPointToCanvas, u as mapViewportPointToCoordinateSpace, v as models, w as observeDragSurfaceVideoSync, y as syncDragSurfaceToVideo } from '../index-Dg1ElHAj.cjs';
 import '../rtc-manager-gYDkADGw.cjs';

package/dist/experimental/index.d.ts

@@ -1,2 +1,2 @@
-export { D as DragTrackController, a as DragTrackControllerOptions, R as RealtimeConnectOptions, b as RealtimeInitialState, c as RealtimeModel, d as RealtimePrewarmHandle, e as RealtimePromptState, f as RealtimeRestartOptions, g as RealtimeSession, h as RealtimeSetImageOptions, i as RealtimeSetInput, j as RealtimeSetModeOptions, k as RemoteViewHost, X as XmaxClient, l as XmaxClientFiles, m as XmaxClientOptions, n as XmaxRealtimeSession, o as createDragTrackController, q as createRemoteViewHost, r as createXmaxClient, s as getContentRect, t as mapTargetPointToCanvas, u as mapViewportPointToCoordinateSpace, v as models, w as observeDragSurfaceVideoSync, y as syncDragSurfaceToVideo } from '../index-BIUk_kvb.js';
+export { D as DragTrackController, a as DragTrackControllerOptions, R as RealtimeConnectOptions, b as RealtimeInitialState, c as RealtimeModel, d as RealtimePrewarmHandle, e as RealtimePromptState, f as RealtimeRestartOptions, g as RealtimeSession, h as RealtimeSetImageOptions, i as RealtimeSetInput, j as RealtimeSetModeOptions, k as RemoteViewHost, X as XmaxClient, l as XmaxClientFiles, m as XmaxClientOptions, n as XmaxRealtimeSession, o as createDragTrackController, q as createRemoteViewHost, r as createXmaxClient, s as getContentRect, t as mapTargetPointToCanvas, u as mapViewportPointToCoordinateSpace, v as models, w as observeDragSurfaceVideoSync, y as syncDragSurfaceToVideo } from '../index-Cw8C8LbO.js';
 import '../rtc-manager-gYDkADGw.js';

package/dist/experimental/index.js

@@ -1,5 +1,5 @@
-export { RealtimePrewarmHandle, RealtimeSession, createRemoteViewHost, createXmaxClient, observeDragSurfaceVideoSync, syncDragSurfaceToVideo } from '../chunk-74ZZWUPI.js';
-export { createDragTrackController, getContentRect, mapTargetPointToCanvas, mapViewportPointToCoordinateSpace, models } from '../chunk-67XSD3QJ.js';
-import '../chunk-PLU2YVAS.js';
+export { RealtimePrewarmHandle, RealtimeSession, createRemoteViewHost, createXmaxClient, observeDragSurfaceVideoSync, syncDragSurfaceToVideo } from '../chunk-VLJZ56PT.js';
+export { createDragTrackController, getContentRect, mapTargetPointToCanvas, mapViewportPointToCoordinateSpace, models } from '../chunk-V4NR6CPP.js';
+import '../chunk-LCPC56BK.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{index-BIUk_kvb.d.ts → index-Cw8C8LbO.d.ts}

@@ -91,8 +91,13 @@ type RealtimeInitialState = {
     autoStart?: boolean;
     /** @internal Business model label in RTC start params; optional — SDK uses a default when omitted. */
     model?: string;
-    /** MoX instant — static image generation that follows drag tracks; sent as `static_generate`. */
+    /** MoX instant — when `true`, sent as `static_generate` on connect start only (never cached). */
     staticGenerate?: boolean;
+    /**
+     * MoX instant — uploaded source still URL (COS). Sent as `static_image_path` on connect
+     * start only (never cached). Local RTC publish is still used for preview / room compatibility.
+     */
+    staticImagePath?: string;
 };
 type RealtimeConnectOptions = {
     model: RealtimeModel;
@@ -126,8 +131,18 @@ type RealtimeRestartOptions = {
     /** @internal Optional business model label; SDK uses a default when omitted. */
     model?: string;
     size?: [number, number];
-    /** MoX instant — static image generation that follows drag tracks; sent as `static_generate`. */
+    /**
+     * MoX instant — when `true`, sent as `static_generate` on this start only (never cached).
+     * Omit on non-Instant starts.
+     */
     staticGenerate?: boolean;
+    /**
+     * MoX instant — COS URL sent as `static_image_path` on this start only (never cached).
+     * Omit on non-Instant starts.
+     */
+    staticImagePath?: string;
+    /** Keep the last rendered remote frame visible while waiting for the next start output. */
+    preserveRemoteOutput?: boolean;
 };
 /** @deprecated Use {@link RealtimeRestartOptions} */
 type RealtimeSetModeOptions = RealtimeRestartOptions;
@@ -207,7 +222,6 @@ declare class RealtimeSession implements XmaxRealtimeSession {
     private localVideoSize;
     private currentPrompt;
     private currentGenerationModel;
-    private currentStaticGenerate;
     private disconnected;
     private remoteViewHost;
     private dragController;
@@ -259,19 +273,23 @@ type DragTrackControllerOptions = {
     fitMode?: 'contain' | 'cover';
     mirrored?: boolean;
     enabled?: boolean;
-    /** When idle (no active pointers), still emit `onTracks([])` on each sample tick. */
-    emitEmptyTracksWhenIdle?: boolean;
     onTracks: (tracks: Array<[number, number]>) => void | Promise<void>;
+    /** Fired once when a real drag stroke begins (first pointer down). */
+    onStrokeStart?: () => void | Promise<void>;
+    /** Fired once when a real drag stroke ends (pointer up/cancel), not on disable/destroy. */
+    onStrokeEnd?: () => void | Promise<void>;
 };
 declare class DragTrackController {
     private readonly container;
     private readonly canvas;
     private readonly onTracks;
+    private readonly onStrokeStart;
+    private readonly onStrokeEnd;
+    private strokeActive;
     private targetSize;
     private fitMode;
     private mirrored;
     private enabled;
-    private emitEmptyTracksWhenIdle;
     private readonly activePointers;
     private readonly lastTargetPoints;
     private readonly segQueue;
@@ -286,7 +304,6 @@ declare class DragTrackController {
     private readonly onPointerCancel;
     constructor(container: HTMLElement, options: DragTrackControllerOptions);
     setEnabled(enabled: boolean): void;
-    setEmitEmptyTracksWhenIdle(emitEmptyTracksWhenIdle: boolean): void;
     setTargetSize(targetSize: [number, number]): void;
     setFitMode(fitMode: 'contain' | 'cover'): void;
     setMirrored(mirrored: boolean): void;

package/dist/{index-Dai62Sos.d.cts → index-Dg1ElHAj.d.cts}

@@ -91,8 +91,13 @@ type RealtimeInitialState = {
     autoStart?: boolean;
     /** @internal Business model label in RTC start params; optional — SDK uses a default when omitted. */
     model?: string;
-    /** MoX instant — static image generation that follows drag tracks; sent as `static_generate`. */
+    /** MoX instant — when `true`, sent as `static_generate` on connect start only (never cached). */
     staticGenerate?: boolean;
+    /**
+     * MoX instant — uploaded source still URL (COS). Sent as `static_image_path` on connect
+     * start only (never cached). Local RTC publish is still used for preview / room compatibility.
+     */
+    staticImagePath?: string;
 };
 type RealtimeConnectOptions = {
     model: RealtimeModel;
@@ -126,8 +131,18 @@ type RealtimeRestartOptions = {
     /** @internal Optional business model label; SDK uses a default when omitted. */
     model?: string;
     size?: [number, number];
-    /** MoX instant — static image generation that follows drag tracks; sent as `static_generate`. */
+    /**
+     * MoX instant — when `true`, sent as `static_generate` on this start only (never cached).
+     * Omit on non-Instant starts.
+     */
     staticGenerate?: boolean;
+    /**
+     * MoX instant — COS URL sent as `static_image_path` on this start only (never cached).
+     * Omit on non-Instant starts.
+     */
+    staticImagePath?: string;
+    /** Keep the last rendered remote frame visible while waiting for the next start output. */
+    preserveRemoteOutput?: boolean;
 };
 /** @deprecated Use {@link RealtimeRestartOptions} */
 type RealtimeSetModeOptions = RealtimeRestartOptions;
@@ -207,7 +222,6 @@ declare class RealtimeSession implements XmaxRealtimeSession {
     private localVideoSize;
     private currentPrompt;
     private currentGenerationModel;
-    private currentStaticGenerate;
     private disconnected;
     private remoteViewHost;
     private dragController;
@@ -259,19 +273,23 @@ type DragTrackControllerOptions = {
     fitMode?: 'contain' | 'cover';
     mirrored?: boolean;
     enabled?: boolean;
-    /** When idle (no active pointers), still emit `onTracks([])` on each sample tick. */
-    emitEmptyTracksWhenIdle?: boolean;
     onTracks: (tracks: Array<[number, number]>) => void | Promise<void>;
+    /** Fired once when a real drag stroke begins (first pointer down). */
+    onStrokeStart?: () => void | Promise<void>;
+    /** Fired once when a real drag stroke ends (pointer up/cancel), not on disable/destroy. */
+    onStrokeEnd?: () => void | Promise<void>;
 };
 declare class DragTrackController {
     private readonly container;
     private readonly canvas;
     private readonly onTracks;
+    private readonly onStrokeStart;
+    private readonly onStrokeEnd;
+    private strokeActive;
     private targetSize;
     private fitMode;
     private mirrored;
     private enabled;
-    private emitEmptyTracksWhenIdle;
     private readonly activePointers;
     private readonly lastTargetPoints;
     private readonly segQueue;
@@ -286,7 +304,6 @@ declare class DragTrackController {
     private readonly onPointerCancel;
     constructor(container: HTMLElement, options: DragTrackControllerOptions);
     setEnabled(enabled: boolean): void;
-    setEmitEmptyTracksWhenIdle(emitEmptyTracksWhenIdle: boolean): void;
     setTargetSize(targetSize: [number, number]): void;
     setFitMode(fitMode: 'contain' | 'cover'): void;
     setMirrored(mirrored: boolean): void;

package/dist/index.cjs

@@ -1278,7 +1278,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)) {
@@ -1430,6 +1431,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,
@@ -1441,7 +1443,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 ?? {}
     }
   };
@@ -1727,7 +1731,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;
     }
@@ -3776,6 +3780,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 = [];
@@ -3785,11 +3790,12 @@ 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;
     this.enabled = options.enabled ?? true;
-    this.emitEmptyTracksWhenIdle = options.emitEmptyTracksWhenIdle ?? false;
     this.canvas = document.createElement("canvas");
     this.canvas.className = "Xmax-drag-track-canvas";
     this.canvas.style.cssText = "position:absolute;inset:0;z-index:21;width:100%;height:100%;pointer-events:none;";
@@ -3803,32 +3809,12 @@ var DragTrackController = class {
     this.bindResizeObserver();
     this.bindPointerEvents();
     this.applyInteractionStyle();
-    if (this.enabled && this.emitEmptyTracksWhenIdle) {
-      this.startSampling();
-    }
   }
   setEnabled(enabled) {
     this.enabled = enabled;
     this.applyInteractionStyle();
     if (!enabled) {
-      this.finishStroke({ stopIdleSampling: true });
-      return;
-    }
-    if (this.emitEmptyTracksWhenIdle && this.activePointers.size === 0) {
-      this.startSampling();
-    }
-  }
-  setEmitEmptyTracksWhenIdle(emitEmptyTracksWhenIdle) {
-    if (this.emitEmptyTracksWhenIdle === emitEmptyTracksWhenIdle) {
-      return;
-    }
-    this.emitEmptyTracksWhenIdle = emitEmptyTracksWhenIdle;
-    if (emitEmptyTracksWhenIdle && this.enabled && this.activePointers.size === 0) {
-      this.startSampling();
-      return;
-    }
-    if (!emitEmptyTracksWhenIdle && this.activePointers.size === 0) {
-      this.stopSampling();
+      this.finishStroke();
     }
   }
   setTargetSize(targetSize) {
@@ -3841,7 +3827,7 @@ var DragTrackController = class {
     this.mirrored = mirrored;
   }
   destroy() {
-    this.finishStroke({ stopIdleSampling: true });
+    this.finishStroke();
     this.unbindPointerEvents();
     this.unbindResizeObserver();
     this.canvas.remove();
@@ -3958,7 +3944,7 @@ var DragTrackController = class {
       return;
     }
     const tracks = this.collectCurrentTracks();
-    if (!tracks.length && !this.emitEmptyTracksWhenIdle) {
+    if (!tracks.length) {
       return;
     }
     this.sampleInFlight = true;
@@ -3976,14 +3962,17 @@ var DragTrackController = class {
       this.flushTracks();
     }, 30);
   }
-  finishStroke(options) {
-    const stopIdleSampling = options?.stopIdleSampling ?? !this.emitEmptyTracksWhenIdle;
-    if (stopIdleSampling) {
-      this.stopSampling();
-    }
+  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) {
@@ -4007,6 +3996,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();
   }
@@ -4039,7 +4034,7 @@ var DragTrackController = class {
     } catch {
     }
     if (this.activePointers.size === 0) {
-      this.finishStroke();
+      this.finishStroke(true);
     }
   }
   handlePointerCancel(e) {
@@ -4049,7 +4044,7 @@ var DragTrackController = class {
     this.activePointers.delete(e.pointerId);
     this.lastTargetPoints.delete(e.pointerId);
     if (this.activePointers.size === 0) {
-      this.finishStroke();
+      this.finishStroke(true);
     }
   }
 };
@@ -4223,7 +4218,6 @@ var RealtimeSession = class _RealtimeSession {
     this.localVideoSize = null;
     this.currentPrompt = "";
     this.currentGenerationModel = "";
-    this.currentStaticGenerate = void 0;
     this.disconnected = false;
     this.remoteViewHost = null;
     this.dragController = null;
@@ -4359,7 +4353,6 @@ var RealtimeSession = class _RealtimeSession {
     const initialState = options.initialState;
     this.currentPrompt = resolvePromptText(initialState?.prompt);
     this.currentGenerationModel = resolveGenerationModel(initialState?.model);
-    this.currentStaticGenerate = initialState?.staticGenerate;
     const publishFpsOptions = {
       mobile: options.mobile,
       highQuality: true,
@@ -4386,7 +4379,8 @@ var RealtimeSession = class _RealtimeSession {
         model: this.currentGenerationModel || void 0,
         size: options.size,
         refImage: initialRefImageUrl,
-        staticGenerate: this.currentStaticGenerate
+        staticGenerate: initialState?.staticGenerate,
+        staticImagePath: initialState?.staticImagePath?.trim() || void 0
       });
     }
   }
@@ -4465,15 +4459,14 @@ var RealtimeSession = class _RealtimeSession {
       if (options?.model !== void 0) {
         this.currentGenerationModel = resolveGenerationModel(options.model);
       }
-      if (options?.staticGenerate !== void 0) {
-        this.currentStaticGenerate = options.staticGenerate;
-      }
       await this.runStart({
         prompt: this.currentPrompt || void 0,
         model: this.currentGenerationModel || void 0,
         size: options?.size,
         refImage: resolvedRefImage,
-        staticGenerate: this.currentStaticGenerate
+        staticGenerate: options?.staticGenerate === true ? true : void 0,
+        staticImagePath: options?.staticImagePath?.trim() || void 0,
+        preserveRemoteOutput: options?.preserveRemoteOutput
       });
     } catch (error) {
       this.reportError(error);
@@ -4564,17 +4557,20 @@ var RealtimeSession = class _RealtimeSession {
     if (!this.rtc.snapshot.joined) {
       return;
     }
+    const preserveRemoteOutput = options.preserveRemoteOutput ?? false;
+    if (preserveRemoteOutput) {
+      this.rtc.setPreserveRemoteDom(true);
+    }
     const startPrompt = options.prompt?.trim() ?? this.currentPrompt;
     if (options.model !== void 0) {
       this.currentGenerationModel = resolveGenerationModel(options.model);
     }
-    if (options.staticGenerate !== void 0) {
-      this.currentStaticGenerate = options.staticGenerate;
-    }
     const modelLabel = resolveGenerationModel(this.currentGenerationModel);
     await this.rtc.ensurePublishedInputBeforeStart();
-    this.rtc.setRemoteVideoContainer(null);
-    this.rtc.clearRemoteVideo();
+    if (!preserveRemoteOutput) {
+      this.rtc.setRemoteVideoContainer(null);
+      this.rtc.clearRemoteVideo();
+    }
     const size = resolveSessionTargetSize({
       localVideoSize: this.localVideoSize,
       overrideSize: options.size ?? this.sessionSizeOverride
@@ -4595,16 +4591,21 @@ var RealtimeSession = class _RealtimeSession {
         size,
         prompt: startPrompt,
         refImagePath: resolveRefImagePath(options.refImage),
-        staticGenerate: this.currentStaticGenerate
+        // Never reuse prior start — caller must pass Instant fields each time.
+        staticGenerate: options.staticGenerate === true ? true : void 0,
+        staticImagePath: options.staticImagePath?.trim() || void 0
       });
-      console.log("[Xmax SDK] \u771F\u5B9E\u53D1\u9001 start ->", startRoomEvent);
       await this.rtc.sendRoomEvent(startRoomEvent);
-      await this.rtc.refreshRemoteVideoBinding({ force: true });
+      await this.rtc.refreshRemoteVideoBinding({ force: !preserveRemoteOutput });
       this.updateDragController(true);
       this.scheduleNotifyRemoteStream();
     } catch (error) {
       this.rtc.configureSessionSei(null);
       throw error;
+    } finally {
+      if (preserveRemoteOutput) {
+        this.rtc.setPreserveRemoteDom(false);
+      }
     }
   }
   isDragEnabled() {
@@ -4731,7 +4732,6 @@ var RealtimeSession = class _RealtimeSession {
     this.taskUid = null;
     this.currentPrompt = "";
     this.currentGenerationModel = "";
-    this.currentStaticGenerate = void 0;
     this.sessionTargetSize = null;
     this.dragController?.destroy();
     this.dragController = null;