lumiverse-spindle-types 0.6.6 → 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -727,6 +727,11 @@ export interface ImageGenProviderDTO {
     modelListStyle: "static" | "dynamic" | "google";
     staticModels?: Array<{ id: string; label: string }>;
     defaultUrl: string;
+    /** Present only when the provider supports Lumiverse's WebSocket preview/status stream. */
+    websocketPreviewStreaming?: {
+      previews: true;
+      status: true;
+    };
   };
 }
 
@@ -761,6 +766,47 @@ export interface ImageGenResultDTO {
   imageUrl?: string;
 }
 
+/** Input for {@link SpindleAPI.imageGen.generateStream}. */
+export interface ImageGenStreamRequestDTO extends ImageGenRequestDTO {
+  /** Abort the upstream generation and close its WebSocket stream. */
+  signal?: AbortSignal;
+}
+
+/** A progress/status update received from the provider WebSocket. */
+export interface ImageGenStreamStatusDTO {
+  type: "status";
+  /** Current step when the provider reports numerical progress. */
+  step?: number;
+  /** Total steps when the provider reports numerical progress. */
+  totalSteps?: number;
+  /** Current workflow node, when supplied by the provider. */
+  nodeId?: string;
+}
+
+/** A preview image received from the provider WebSocket. */
+export interface ImageGenStreamPreviewDTO {
+  type: "preview";
+  /** Preview image as a base64 data URL. */
+  imageDataUrl: string;
+  /** Status reported with this preview, when available. */
+  step?: number;
+  totalSteps?: number;
+  nodeId?: string;
+}
+
+/** Terminal success event for an image generation stream. */
+export interface ImageGenStreamDoneDTO {
+  type: "done";
+  /** Final image and its persisted asset identifiers. */
+  result: ImageGenResultDTO;
+}
+
+/** Events yielded by {@link SpindleAPI.imageGen.generateStream}. */
+export type ImageGenStreamEventDTO =
+  | ImageGenStreamStatusDTO
+  | ImageGenStreamPreviewDTO
+  | ImageGenStreamDoneDTO;
+
 // ─── Image DTOs ─────────────────────────────────────────────────────────
 
 export type ImageSpecificityDTO = "full" | "sm" | "lg";
@@ -3384,6 +3430,12 @@ export type WorkerToHost =
   | { type: "macros_resolve"; requestId: string; template: string; chatId?: string; characterId?: string; userId?: string; commit?: boolean }
   // ─── Image Generation (gated: "image_gen") ──────────────────────────
   | { type: "image_gen_generate"; requestId: string; input: ImageGenRequestDTO }
+  /**
+   * Start a WebSocket-backed image stream. Only providers that advertise
+   * `websocketPreviewStreaming` accept this request.
+   */
+  | { type: "image_gen_generate_stream"; requestId: string; input: Omit<ImageGenStreamRequestDTO, "signal"> }
+  | { type: "image_gen_cancel_stream"; requestId: string }
   | { type: "image_gen_providers"; requestId: string; userId?: string }
   | { type: "image_gen_connections_list"; requestId: string; userId?: string }
   | { type: "image_gen_connections_get"; requestId: string; connectionId: string; userId?: string }
@@ -3622,4 +3674,6 @@ export type HostToWorker =
    * `request_generation_stream`. Mutually exclusive with the `done`
    * chunk in `generation_stream_chunk`. Aborts surface here too.
    */
-  | { type: "generation_stream_error"; requestId: string; error: string };
+  | { type: "generation_stream_error"; requestId: string; error: string }
+  | { type: "image_gen_stream_chunk"; requestId: string; event: ImageGenStreamEventDTO }
+  | { type: "image_gen_stream_error"; requestId: string; error: string };

package/src/index.ts

@@ -155,9 +155,14 @@ export type {
    ImageGenConnectionDTO,
    ImageGenParameterSchemaDTO,
     ImageGenProviderDTO,
-    ImageGenRequestDTO,
-    ImageGenResultDTO,
-    ImageGetOptionsDTO,
+   ImageGenRequestDTO,
+   ImageGenResultDTO,
+   ImageGenStreamRequestDTO,
+   ImageGenStreamStatusDTO,
+   ImageGenStreamPreviewDTO,
+   ImageGenStreamDoneDTO,
+   ImageGenStreamEventDTO,
+   ImageGetOptionsDTO,
     ImageDTO,
     ImageListOptionsDTO,
     ImageSpecificityDTO,

package/src/spindle-api.ts

@@ -70,6 +70,8 @@ import type {
   ChatMemoryResultDTO,
   ImageGenRequestDTO,
   ImageGenResultDTO,
+  ImageGenStreamRequestDTO,
+  ImageGenStreamEventDTO,
   ImageGenConnectionDTO,
   ImageGenProviderDTO,
   ImageGetOptionsDTO,
@@ -800,6 +802,16 @@ export interface SpindleAPI {
      * Returns the image as a base64 data URL.
      */
     generate(input: ImageGenRequestDTO): Promise<ImageGenResultDTO>;
+    /**
+     * Generate through a provider that supports WebSocket preview images and
+     * status updates (currently SwarmUI and ComfyUI). The terminal `done`
+     * event carries the same result as {@link generate}. Breaking from the
+     * iterator or aborting `input.signal` cancels the upstream generation.
+     *
+     * Throws if the selected provider does not advertise
+     * `websocketPreviewStreaming` in {@link getProviders}.
+     */
+    generateStream(input: ImageGenStreamRequestDTO): AsyncGenerator<ImageGenStreamEventDTO, void, void>;
     /**
      * List available image generation providers with their capability schemas.
      * The schemas describe supported parameters, models, and features.

package/test/image-gen-stream-consumer.ts

@@ -0,0 +1,44 @@
+import type {
+  HostToWorker,
+  ImageGenStreamEventDTO,
+  SpindleAPI,
+  WorkerToHost,
+} from "lumiverse-spindle-types";
+
+declare const spindle: SpindleAPI;
+
+async function consumePreviews(): Promise<void> {
+  const stream = spindle.imageGen.generateStream({
+    connection_id: "swarm-connection",
+    prompt: "A quiet observatory under a starry sky",
+  });
+
+  for await (const event of stream) {
+    if (event.type === "preview") {
+      const preview: string = event.imageDataUrl;
+      void preview;
+    } else if (event.type === "status") {
+      const step: number | undefined = event.step;
+      void step;
+    } else {
+      const finalImage: string = event.result.imageDataUrl;
+      void finalImage;
+    }
+  }
+}
+
+const event: ImageGenStreamEventDTO = { type: "status", step: 2, totalSteps: 20 };
+const startStream: WorkerToHost = {
+  type: "image_gen_generate_stream",
+  requestId: "request-1",
+  input: { prompt: "A quiet observatory under a starry sky" },
+};
+const preview: HostToWorker = {
+  type: "image_gen_stream_chunk",
+  requestId: "request-1",
+  event: { type: "preview", imageDataUrl: "data:image/png;base64,preview" },
+};
+void event;
+void startStream;
+void preview;
+void consumePreviews;

package/tsconfig.consumer.json

@@ -5,5 +5,5 @@
     "outDir": "./.consumer-dist",
     "declaration": false
   },
-  "include": ["test/loom-block-editor-consumer.ts", "test/bound-generation-consumer.ts", "test/interceptor-consumer.ts", "test/host-runtime-contract-consumer.ts"]
+  "include": ["test/loom-block-editor-consumer.ts", "test/bound-generation-consumer.ts", "test/interceptor-consumer.ts", "test/host-runtime-contract-consumer.ts", "test/image-gen-stream-consumer.ts"]
 }