@comfyorg/comfyui-desktop-bridge-types 0.9.0 → 0.11.0

package/README.md

@@ -41,15 +41,20 @@ while omitting part of it.
 
 ## Comfy pages hosted in Desktop's Apps view
 
-A Comfy page that Desktop shows in its Apps view gets `window.comfyDesktopAuth`
-instead: Desktop's account session, and nothing else of the bridge above.
+A Comfy page that Desktop shows in its Apps view gets two objects instead, and
+nothing else of the bridge above: `window.comfyDesktopAuth`, Desktop's account
+session, and `window.comfyDesktopLocal`, a ComfyUI on this computer.
 
 ```ts
-import type { ComfyDesktopHostedAuthBridge } from '@comfyorg/comfyui-desktop-bridge-types'
+import type {
+  ComfyDesktopHostedAuthBridge,
+  ComfyDesktopHostedLocalBridge
+} from '@comfyorg/comfyui-desktop-bridge-types'
 
 declare global {
   interface Window {
     comfyDesktopAuth?: ComfyDesktopHostedAuthBridge
+    comfyDesktopLocal?: ComfyDesktopHostedLocalBridge
   }
 }
 ```
@@ -57,8 +62,26 @@ declare global {
 The page reads the session with `getState()`, follows it with `onChanged()`,
 asks for the workspace credential with `getWorkspaceToken(workspaceId)` each
 time it calls Comfy Cloud, and starts a sign-in with `requestSignIn()`. It
-cannot sign Desktop out or switch workspace. The object is absent in a
-browser, so a page keeps its own sign-in as the fallback.
+cannot sign Desktop out or switch workspace.
+
+For a run on this computer the page asks `getLocal({ minVersion })` which of
+the person's builds Desktop would use, starts it with `startLocal()`, and then
+talks to it through `localFetch()`. Desktop forwards only the calls a run
+needs, and only for runs the page started; `onLocalEvent()` carries ComfyUI's
+updates for those runs. `localDownload()` saves a safetensors model from
+Hugging Face into that build's models folder.
+
+`openInComfy({ prompt, where, name, build })` opens a run's API-format
+workflow in a ComfyUI window in Desktop: the build the page runs on (or the
+build `build` names, an id from `localBuilds()`) for `where: 'local'`, or the
+person's Comfy Cloud for `where: 'cloud'`. Desktop starts the build or shows
+its window if needed, and resolves `{ opened: true }` once ComfyUI has loaded
+the workflow, or `{ opened: false, error }` with the reason in words. Both
+members are absent on Desktop builds that predate them, so a page checks for
+them and keeps its file download as the fallback.
+
+Both objects are absent in a browser, so a page keeps its own sign-in and its
+own way to reach a local ComfyUI as the fallback.
 
 ## Provenance
 

package/comfyDesktopBridge.d.ts

@@ -187,6 +187,122 @@ export type ComfyDesktopHostedAuthBridge = Required<
     'getState' | 'getWorkspaceToken' | 'getPartnerNodeToken' | 'requestSignIn' | 'onChanged'
   >
 >
+/** What a hosted page needs from the ComfyUI on this computer. */
+export interface ComfyDesktopLocalRequirements {
+  /** The oldest ComfyUI the page can run on, such as `0.41.0`. */
+  minVersion?: string
+}
+/**
+ * The ComfyUI on this computer that Desktop uses for a hosted page.
+ * `running`: it answers now. `stopped`: one of the person's builds fits and
+ * `startLocal` starts it. `unsupported`: no build here can run the page, and
+ * `error` says why in words for the person.
+ */
+export interface ComfyDesktopLocalComfy {
+  state: 'running' | 'stopped' | 'unsupported'
+  /** True when it is one of the person's own builds. */
+  own?: boolean
+  name?: string
+  version?: string
+  /** The `client_id` Desktop listens with; updates for runs sent through `localFetch` arrive on `onLocalEvent`. */
+  clientId?: string
+  error?: string
+}
+/**
+ * One call to that ComfyUI. Desktop forwards only what a run needs:
+ * `GET /queue`, `GET /history/<run>`, `GET /view`, `GET /object_info/<node>`,
+ * `POST /prompt`, `POST /upload/image`, `POST /queue` to take a run out, and
+ * `POST /interrupt` to stop one. History, files, removal and stopping work
+ * only for runs the page started through this bridge.
+ */
+export interface ComfyDesktopLocalRequest {
+  method?: 'GET' | 'POST'
+  path: string
+  /** JSON text, or a file's bytes for `/upload/image`. */
+  body?: string | Uint8Array
+  /** The name to save an upload under. */
+  fileName?: string
+}
+/** ComfyUI's answer, or status 403 for a call Desktop does not forward. */
+export interface ComfyDesktopLocalAnswer {
+  status: number
+  contentType: string
+  body: Uint8Array
+}
+/** A safetensors file on Hugging Face to save as `name` in the models folder `folder`. */
+export interface ComfyDesktopLocalModel {
+  url: string
+  folder: string
+  name: string
+}
+export interface ComfyDesktopLocalDownload {
+  state: 'done' | 'failed' | 'cancelled'
+  error?: string
+}
+/**
+ * A model download's progress (`type: 'download'`, with `name`, `done` and
+ * `total` bytes in `data`), or one ComfyUI socket message about a run the page
+ * started (`execution_start`, `executing`, `progress`, `progress_state`,
+ * `execution_success`, `execution_error`, `execution_interrupted`).
+ */
+export interface ComfyDesktopLocalEvent {
+  type: string
+  data?: Record<string, unknown>
+}
+/**
+ * A workflow a hosted page asks Desktop to open in a ComfyUI window.
+ * `prompt` is the API-format graph: an object of nodes that each have a
+ * `class_type` and `inputs`, at most 500 nodes and 1 MB. `where: 'local'`
+ * opens it in the build the page runs on, or in `build` (an id from
+ * `localBuilds`); `where: 'cloud'` opens it in the person's Comfy Cloud.
+ * `name` titles the workflow tab.
+ */
+export interface ComfyDesktopOpenInComfyRequest {
+  prompt: Record<string, unknown>
+  where: 'local' | 'cloud'
+  name: string
+  build?: string
+}
+/** Whether the workflow opened, and if not, why in words for the person. */
+export type ComfyDesktopOpenInComfy =
+  | {
+      opened: true
+    }
+  | {
+      opened: false
+      error: string
+    }
+/** One of the person's ComfyUI builds on this computer. */
+export interface ComfyDesktopLocalBuild {
+  id: string
+  name: string
+}
+/**
+ * A ComfyUI on this computer, run by Desktop, for a Comfy page hosted in
+ * Desktop's Apps view. Desktop exposes it to that page as
+ * `window.comfyDesktopLocal`. The page builds and follows its own runs;
+ * Desktop finds or starts the ComfyUI, forwards the page's calls to it,
+ * downloads a model the page asks for and opens a run's workflow in a ComfyUI
+ * window.
+ */
+export interface ComfyDesktopHostedLocalBridge {
+  getLocal(want?: ComfyDesktopLocalRequirements): Promise<ComfyDesktopLocalComfy>
+  /** Starts the ComfyUI if it is stopped and resolves once it answers, or with the state and `error` if it could not start. */
+  startLocal(want?: ComfyDesktopLocalRequirements): Promise<ComfyDesktopLocalComfy>
+  /** Rejects when no ComfyUI is running to forward to. */
+  localFetch(request: ComfyDesktopLocalRequest): Promise<ComfyDesktopLocalAnswer>
+  /** Downloads into the running ComfyUI's models folder and resolves when the file is there. */
+  localDownload(model: ComfyDesktopLocalModel): Promise<ComfyDesktopLocalDownload>
+  onLocalEvent(callback: (event: ComfyDesktopLocalEvent) => void): () => void
+  /**
+   * Opens the workflow in a ComfyUI window in Desktop, starting the build or
+   * showing its window first if needed, and resolves once ComfyUI has loaded
+   * it. Absent on Desktop builds that predate it.
+   */
+  openInComfy?(request: ComfyDesktopOpenInComfyRequest): Promise<ComfyDesktopOpenInComfy>
+  /** The person's ComfyUI builds on this computer. Absent on Desktop builds that predate it. */
+  localBuilds?(): Promise<ComfyDesktopLocalBuild[]>
+}
 export interface ComfyDesktop2TerminalBridge {
   subscribe(installationId?: string): Promise<TerminalRestore>
   unsubscribe(installationId?: string): Promise<void>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfyorg/comfyui-desktop-bridge-types",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "TypeScript definitions for the Comfy Desktop hosted frontend bridge",
   "type": "module",
   "main": "./index.js",