The all-in-one local AI studio for your desktop: chat, image and video generation and a coding agent in one free, open source app. Windows and Linux. No Docker, no terminal, no cloud required.
TypeScript agentai-chatai-studioall-in-onecoding-agentdesktop-appfluximage-generationlinuxllmlocal-ailocal-llmopen-sourceprivacyself-hostedstable-diffusionuncensoreduncensored-aivideo-generationwindows
import { comfyuiUrl, localFetch, fetchLocalhostBytes, isTauri, backendCall, isMacOS } from "./backend"
import { log } from "../lib/logger"
import { LU_CLIENT_PREFIX } from "./comfyui-ws"
import { nodeComboOptions } from "./comfyui-enum"
import { resolveRunSeed } from '../lib/run-seed'
import { blobFromUrl } from '../lib/render/data-url'
// Audit W-T2: videoDecodeNode/promptFilenamePrefix kamen hier bis eben per
// `await import('./dynamic-workflow')` mitten in den Buildern herein — ein
// dynamischer Import, der nur den Zyklus comfyui ↔ dynamic-workflow
// verdeckt hat. Beide sind reine Graph-Bausteine und wohnen jetzt in
// comfyui-graph.ts, das nichts importiert.
import { videoDecodeNode, promptFilenamePrefix, tagOutputPrefixes, newRunTag, addVideoSave } from './comfyui-graph'
import type { ComfyApiGraph, ComfyApiNode, ComfyHistoryEntry } from '../types/comfy-graph'
import type { ComfyModelSource } from '../types/models'
import { isRecord, asString, asRecordArray } from '../types/json-guards'
// Audit W-T2: der Katalog kam bis eben per `await import('./discover')` in
// getKnownFileSizes() herein, „to break the cycle at runtime". Die
// Bundle-Daten gehören weder hierher noch nach discover.ts — sie liegen
// jetzt in model-bundles.ts, das beide Seiten statisch lesen.
import { getImageBundles, getVideoBundles } from './model-bundles'
import { isQwenEnhancerFile } from '../lib/render/qwen-enhancer'
import { pickQwenEncoder, qwenEncoderFile, type QwenEncoderChoice } from '../lib/render/qwen-text-encoder'
import { COMPONENT_REGISTRY, type ComponentSpec } from './component-registry'
// ─── Control-plane fetch timeouts ───
//
// These ComfyUI endpoints enqueue / list / poll / free and MUST answer in well
// under a few seconds on localhost: ComfyUI serves them on its asyncio event
// loop while the actual generation runs on a SEPARATE worker thread, so HTTP
// stays responsive even mid-render. A generation's real compute time is observed
// by repeatedly polling /history (each poll quick), NOT by any single long-lived
// fetch. Without an explicit cap every call below inherits the Rust proxy's
// 300 s default — and ONE wedged control call (e.g. /object_info right after a
// ComfyUI restart, or a /prompt POST that never returns) froze the whole image-
// MCP VRAM hand-off for minutes with the text model left unloaded (chat-agent
// hang, 2026-06-03). Bounding each call converts that infinite stall into a fast,
// clean error so the hand-off's `finally` can always free VRAM + reload the model.
const COMFY_LIST_TIMEOUT_MS = 15_000 // /object_info/<Node> single-node listings
const COMFY_SUBMIT_TIMEOUT_MS = 30_000 // POST /prompt — validates + enqueues, returns prompt_id only
const COMFY_POLL_TIMEOUT_MS = 15_000 // GET /history/<id> per status poll
const COMFY_STATS_TIMEOUT_MS = 10_000 // /system_stats, /api/refresh, /interrupt
const COMFY_FREE_TIMEOUT_MS = 20_000 // POST /free — VRAM release
// ─── Types ───
export interface GenerateParams {
prompt: string
negativePrompt: string
model: string
sampler: string
scheduler: string
steps: number
cfgScale: number
width: number
height: number
seed: number
batchSize: number
inputImage?: string // I2I source image filename (uploaded to ComfyUI)
/** C75: a Qwen-Image 2.1 edit in the shape of width x height instead of
* the source's. Absent or 'source': the source's shape, as before. */
editShape?: 'source' | 'canvas'
/** Edit: further reference images (ComfyUI upload names) after the source,
* for the families lib/edit-references names. GH #144. */
referenceImages?: string[]
/** What the model file carries besides the diffusion model (header sniff).
* Lets an all-in-one file in models/checkpoints use its own encoder/VAE. */
modelParts?: { textEncoder: boolean; vae: boolean }
denoise?: number // I2I denoise strength (0.0–1.0, default 1.0 = full txt2img)
/** Qwen edits only (Qwen-Image 2.1, Qwen-Image-Edit 2509/2511): the Edit
* strength, 0.05 to 1. 1 or unset is the template's edit from noise;
* lower starts the sampler from the source and keeps more of it (B46). */
editStrength?: number
removebg?: boolean // Background removal: LoadImage → RMBG → SaveImage cutout (no diffusion)
/** Qwen-Image 2.1 text-to-image only: ask for an RGBA picture with a
* transparent background (lib/transparent-image.ts). Ignored elsewhere. */
transparent?: boolean
/** Qwen-Image 2.1 only: which installed text encoder reads the prompt, the
* official one or the edition without refusals
* (lib/render/qwen-text-encoder.ts). Ignored elsewhere. */
qwenTextEncoder?: QwenEncoderChoice
// Local Edit (mask inpaint): ComfyUI /upload/image filename of the painted
// mask (white = repaint). With inputImage set this selects the inpaint
// pipeline (VAEEncodeForInpaint / InpaintModelConditioning) on the
// SDXL/SD1.5 checkpoint path — same contract as the web app's builder.
maskImage?: string
growMaskBy?: number // Mask edge feather in pixels (VAEEncodeForInpaint grow_mask_by, default 6)
// F2 (GH#4), extended for multi-LoRA (a user 2026-06-09:
// "agent cannot load multiple loras"): one filename or an ordered list.
// Multiple LoRAs are CHAINED — LoraLoader N feeds (model, clip) into
// LoraLoader N+1, exactly like stacking them in the ComfyUI graph editor.
// `loraStrength` mirrors LoraLoader's `strength_model` (0..2 typical):
// a single number applies to every LoRA, an array maps per-LoRA by index.
lora?: string | string[]
loraStrength?: number | number[]
// F3 (GH#4): override the checkpoint's bundled VAE with an
// explicit VAELoader. 'auto' / undefined / empty = keep the
// checkpoint VAE.
vae?: string
// F3: optional CLIPSetLastLayer injection. 0 = no skip (the
// checkpoint default). Common values: 1 for SD1.5/SDXL,
// 2 for some abliterated finetunes.
clipSkip?: number
}
export interface VideoParams extends GenerateParams {
frames: number
fps: number
inputImage?: string // Uploaded image filename for I2V models (SVD, FramePack)
/** Animate: the picture the clip ends on (B38), for the models
* lib/frame-refs localEndFrame names. Any other model refuses it. */
endImage?: string
// SVD motion strength (motion_bucket_id, 1–255). Lower = more faithful to the
// source still / calmer motion; 127 (SVD default) drifts hard. We default ~90
// for I2V fidelity (2026-06-11). Honoured only by the SVD path.
motionBucketId?: number
/** A later section of a long clip (B18): the clip so far in ComfyUI's input
* folder and how many of its last frames this section repeats. The graph
* starts on those frames and outputs the whole clip (api/video-continue). */
continueFrom?: { video: string; overlap: number }
/** One pass with sliding context windows instead of sections (B18). */
contextWindows?: boolean
}
export interface ComfyUIOutput {
filename: string
subfolder: string
type: string
}
/**
* Bug R (v2.4.7 — GH Discussion #6, 2026-05-20).
*
* Pre-v2.4.7 LU only scraped `images` / `gifs` / `videos` from a ComfyUI
* history `outputs[nodeId]` payload. That worked for the canonical SaveImage
* / SaveAnimatedWEBP / VHS_VideoCombine nodes, but plenty of custom save
* nodes (community workflows from CivitAI, SaveImageWithMetadata,
* SaveImageHTML, audio save nodes, etc.) post under different keys —
* `audio`, `result`, `files`, `latents`, `meshes`, model-specific keys.
* The file lands in ComfyUI's `output/` folder but never makes it into LU's
* gallery, exactly the symptom a user reported.
*
* Generic extractor: scan every key on the node output, collect any array
* whose entries look like `{ filename, subfolder?, type? }`. Defaults fill
* in subfolder='' and type='output' so the gallery + comfyImageUrl can build
* a working URL even when a custom save node omits them.
*/
export function extractComfyOutputFiles(nodeOutput: unknown): ComfyUIOutput[] {
if (!nodeOutput || typeof nodeOutput !== 'object') return []
const found: ComfyUIOutput[] = []
for (const value of Object.values(nodeOutput as Record<string, unknown>)) {
if (!Array.isArray(value)) continue
for (const item of value) {
if (
item &&
typeof item === 'object' &&
'filename' in item &&
typeof (item as { filename: unknown }).filename === 'string'
) {
const it = item as { filename: string; subfolder?: unknown; type?: unknown }
// A file of ComfyUI's INPUT folder is never a result. Core LoadVideo
// reports a preview of the video it loaded under that type (B18 box
// run, 27.10.2026: every continued section of a long clip listed the
// clip so far next to its own output, and the chain took the input
// for the new section). Motion Control's driving video is the same.
if (it.type === 'input') continue
found.push({
filename: it.filename,
subfolder: typeof it.subfolder === 'string' ? it.subfolder : '',
type: typeof it.type === 'string' ? it.type : 'output',
})
}
}
}
return found
}
/** Gallery media type for a finished output file. The render mode alone
* mistagged audio outputs (SaveAudio & friends post .flac/.mp3/.wav) as
* image/video, so their tiles rendered as broken <img>/<video>. Only the
* audio axis is decided by extension — everything else keeps the mode, so
* the long-standing image/video tagging (incl. the animated-webp fallback)
* is untouched. */
const AUDIO_OUTPUT_EXTS = new Set(['mp3', 'wav', 'flac', 'ogg', 'opus', 'm4a'])
/** 3.1.0: the mesh formats a 3D save node writes. SaveGLB (nodes_save_3d.py,
* ComfyUI v0.42.4) always writes .glb for a mesh and keeps the format of a
* File3D it is handed, so the other four can come out of it too. */
const MESH_OUTPUT_EXTS = new Set(['glb', 'gltf', 'obj', 'ply', 'stl'])
export function galleryTypeForFile(
filename: string,
mode: 'image' | 'video',
): 'image' | 'video' | 'audio' | '3d' {
const ext = (filename.split('.').pop() || '').toLowerCase()
if (MESH_OUTPUT_EXTS.has(ext)) return '3d'
return AUDIO_OUTPUT_EXTS.has(ext) ? 'audio' : mode
}
// 2.5.8: ace / wans2v / wananimate / wanvace are the specialized local-lane
// architectures (music, talking character, motion control). They are neither
// image nor video picker material — each lane has its own model list.
export type ModelType = 'flux' | 'flux2' | 'krea2' | 'zimage' | 'ernie_image' | 'qwenimage' | 'qwenimage1' | 'chroma' | 'hidream' | 'sd3' | 'lumina2' | 'sdxl' | 'sd15' | 'wan' | 'wan22' | 'hunyuan' | 'ltx' | 'ltx25' | 'mochi' | 'cosmos' | 'cogvideo' | 'svd' | 'framepack' | 'pyramidflow' | 'allegro' | 'ace' | 'yue2' | 'wans2v' | 'wananimate' | 'wanvace' | 'animatediff' | 'minimaxh3' | 'minimaxh3image' | 'mossimage' | 'unknown'
export type VideoBackend = 'wan' | 'animatediff' | 'none'
export interface ClassifiedModel {
name: string
type: ModelType
/** Which ComfyUI enum listed this file. `motion_module` is the AnimateDiff
* one, and it lives outside ComfyUI\models entirely (see getMotionModels).
* The rest are the addon folders: files that are not a model on their own,
* take up real disk, and used to appear in no list and no counter at all
* (counter-check 2026-08-29, and five more folders in the R5 re-measure
* the day after). */
source: ComfyModelSource
/** What the file carries besides the diffusion model, read from its header
* (commands/model_sniff.rs). Absent when the header was not readable. */
parts?: { textEncoder: boolean; vae: boolean }
/** Whether a video model starts from an image, where a catalogue says so
* (the Mac's MLX catalogue, api/mlx-video.ts). Absent on a ComfyUI file,
* whose name is all there is to go by (isI2VModel, isT2VCapable). */
startImage?: 'none' | 'optional' | 'required'
/** How many images an edit with this model takes in all, where a catalogue
* says so (the Mac's MLX catalogue, api/mlx-image.ts). 0: it makes images
* from text alone. Absent on a ComfyUI file, where the family decides
* (lib/edit-references). */
editImages?: number
/** The size of the model's weights in GB, where the Mac's MLX catalogue
* says so. An edit on the Mac counts it into the memory the run takes
* (lib/mac-edit-memory). Absent on a ComfyUI file. */
packGb?: number
/** The model runs at its own steps and guidance, and Create's sliders do not
* reach it (a pack of the Mac's second image engine that is tuned to one
* count, lib/image-engines). Absent everywhere else. */
ownSampling?: boolean
/** A run with this model takes the LoRA stack from the Mac's LoRA folder
* (a pack of the Mac's second image engine, lib/image-engines). Absent
* everywhere else: on a ComfyUI host the stack is ComfyUI's. */
mlxLoras?: boolean
/** What a clip of this model is, where the Mac's video catalogue says so
* (api/mlx-video.ts): how many frames it has by default, the rate it plays
* at, the grid its frame count sits on, the size it is made at and whether
* the model reads a negative prompt. The Mac's video engines take a length
* and, where the entry says so, a negative prompt, another size on
* `sizeGrid` up to `maxPixels`, and a step count from 1 to `maxSteps`
* around `steps`, so this is all Create has to set for them. Absent on a
* ComfyUI file, where the family's defaults stand. */
mlxVideo?: {
frames: number; fps: number; frameStep: number; width: number; height: number; negativePrompt: boolean
loras?: boolean; recommendedRamGB?: number; measuredRunSecondsPerClipSecond?: number
sizeGrid?: number; maxPixels?: number; minSide?: number; maxSide?: number
steps?: number; maxSteps?: number
/** The shot list reaches the model (LTX-2.5, lib/ltx-multishot). */
multishot?: boolean
/** A run can follow a motion video (Motion Control on the Mac). */
motion?: boolean
/** Talking Character on a Mac (api/mlx-video `mlxTalking`): the model
* runs it once its own download is on disk ('ready'), and not before
* ('missing'). Absent for a model that does not talk. */
talking?: 'ready' | 'missing'
/** The size of that download, in decimal GB. */
talkingGB?: number
}
}
/** The ComfyUI\models folders that hold files a user installs, none of which
* is a main model. One name per folder, and INSTALLED_ADDON_LANES below is
* the single place that says which loader enumerates it.
*
* Carved out of `ComfyModelSource` (types/models.ts) rather than spelled out
* a second time: the inventory rows carry that field into the views, and two
* hand-written copies of one folder list is exactly the drift
* COMFY_MODEL_FOLDERS below exists to stop. */
export type AddonSource =
Exclude<ComfyModelSource, 'checkpoint' | 'diffusion_model' | 'motion_module'>
/** Where a listed file actually sits, by the enum that listed it. The disk
* probe needs the folder, and the delete command resolves the same set.
*
* The motion-module folder comes from ANIMATEDIFF_SUBFOLDER below rather than
* being spelled out a second time: it used to live in discover.ts, which
* imports back into this module, and the duplicate was held together by a unit
* test instead of by there being only one of it. */
export function subfolderForSource(source: ClassifiedModel['source']): string {
switch (source) {
case 'checkpoint': return 'checkpoints'
case 'diffusion_model': return 'diffusion_models'
case 'motion_module': return ANIMATEDIFF_SUBFOLDER
case 'lora': return 'loras'
case 'vae': return 'vae'
case 'text_encoder': return 'text_encoders'
case 'clip_vision': return 'clip_vision'
case 'controlnet': return 'controlnet'
case 'upscale_model': return 'upscale_models'
case 'embedding': return 'embeddings'
case 'style_model': return 'style_models'
}
}
// ─── Model Classification ───
// Known community models → pre-classified for reliability
const KNOWN_MODELS: Record<string, ModelType> = {
juggernaut: 'sdxl',
realvis: 'sdxl',
animagine: 'sdxl',
pony: 'sdxl',
illustrious: 'sdxl',
noobai: 'sdxl',
proteus: 'sdxl',
copax: 'sdxl',
zavychroma: 'sdxl',
epicrealism: 'sdxl',
realisticvision: 'sd15',
deliberate: 'sd15',
revanimated: 'sd15',
dreamshaper: 'sd15', // dreamshaper XL handled by 'xl' check first
absolutereality: 'sd15',
}
/** C78: a file name of MiniMax H3 Image (minimax_h3_image_pruned_w4a8,
* MiniMax-H3-Image-Q8_0.gguf, minimaxh3image_*). */
export function isMinimaxH3ImageName(name: string): boolean {
return /minimax[_-]?h3[_-]?image/.test(name.toLowerCase())
}
/** GH #192: a file name of MOSS Image (OpenMOSS, 16.10.2026): the CivitAI
* repack mossImage_sft_pruned_int8, MOSS-Image_SFT_int8, moss_image_*. */
export function isMossImageName(name: string): boolean {
return /(^|[^a-z0-9])moss[_-]?image/.test(name.toLowerCase())
}
/** FastVideo's distilled MiniMax H3 (fastvideo_fasth3_8step_v2_*). A full
* checkpoint, not a LoRA, and it only does text to video: the model card says
* the first/last frame and reference tasks were not distilled. */
export function isFastH3(name: string): boolean {
return name.toLowerCase().includes('fasth3')
}
/** Wan 2.2 A14B: the i2v/t2v pair in its high noise and low noise halves,
* any quant (Comfy-Org fp8/fp16, QuantStack GGUF, Kijai). Wan 2.1
* architecture under a 2.2 tag: WanImageToVideo and the 16-channel
* wan_2.1_vae. Only the TI2V-5B uses the 48-channel wan2.2_vae (GH #193). A
* 2.2 name that says neither 14B nor high/low noise nor i2v/t2v stays on the
* 5B path it always took. */
export function isWan22A14B(name: string): boolean {
const lower = name.toLowerCase()
if (!/wan[._-]?2[._-]?2/.test(lower)) return false
if (lower.includes('ti2v') || /(^|[^0-9])5b/.test(lower)) return false
return /(^|[^0-9])a?14b/.test(lower)
|| /(high|low)[._-]?noise/.test(lower)
|| /(^|[^a-z])[it]2v([^a-z]|$)/.test(lower)
}
/** The low noise half that finishes what this high noise A14B file starts,
* from the names the loader lists, or null. Same name with the one "high"
* turned into "low": high_noise → low_noise (Comfy-Org), HighNoise →
* LowNoise (QuantStack GGUF), HIGH → LOW (Kijai). */
export function wan22LowNoisePartner(name: string, listed: string[]): string | null {
if (!isWan22A14B(name)) return null
const lower = name.toLowerCase()
const at = lower.search(/high(?=[._-]?noise|[._-])/)
if (at < 0) return null
const want = lower.slice(0, at) + 'low' + lower.slice(at + 4)
return listed.find((n) => n.toLowerCase() === want) ?? null
}
export function classifyModel(name: string | null | undefined): ModelType {
// Defensive: treat empty/missing names as unknown. Older installs can persist
// stale model strings that no longer exist; callers should not crash on those.
if (!name || typeof name !== 'string') return 'unknown'
const lower = name.toLowerCase()
// 2.5.8 specialized lanes — must beat the generic wan/ace substrings below.
// 'vace' before 'ace' (contains it), s2v/animate before the wan2.2 match
// (wan2.2_s2v / wan2.2_animate carry the wan2.2 tag too).
if (lower.includes('vace')) return 'wanvace'
if (lower.includes('s2v')) return 'wans2v'
if (lower.includes('animate') && lower.includes('wan') && !lower.includes('animatediff')) return 'wananimate'
// A motion module is neither an image nor a standalone video model: it is the
// second half of the AnimateDiff lane, which also needs an SD checkpoint. Its
// own type keeps it out of isImageModelType (which lets 'unknown' through and
// would otherwise offer a motion module in the image picker).
if (lower.includes('animatediff')) return 'animatediff'
if (lower.includes('ace_step') || lower.includes('ace-step') || lower.includes('acestep')) return 'ace'
// YuE2 (Comfy-Org/YuE2, ComfyUI 0.36.0): an all in one music checkpoint
// that lives in models/checkpoints next to ACE Step, so it needs its own
// type or it would land in the image picker as 'unknown'.
if (/(^|[^a-z0-9])yue[._-]?2/.test(lower)) return 'yue2'
// Merged 14B "rapid AIO" builds (e.g. wan2.2-i2v-rapid-aio) are Wan 14B
// architecture: classic WanImageToVideo graph + wan_2.1_vae — NOT the
// TI2V-5B path the wan2.2 tag would otherwise route them onto.
if (lower.includes('rapid') && lower.includes('aio')) return 'wan'
// The Wan 2.2 A14B pair is the same architecture (GH #193, see isWan22A14B).
if (isWan22A14B(lower)) return 'wan'
// MiniMax H3 (Comfy-Org/MiniMax-H3): video with its own sound track, from
// text, a first/last frame (fl2va) or references (ref2va). Before every
// generic tag: its CivitAI repacks carry anything in their names.
// FastH3 (FastVideo's 8 step distillation of H3) is the same architecture
// under a file name that never says "minimax": fastvideo_fasth3_8step_v2_*.
// MiniMax H3 Image (Comfy-Org/MiniMax-H3-Image, minimax_h3_image_*) is a
// still model on the H3 layout, not a video (C78). The header decides for a
// name that says neither (model_sniff.rs, applyHeaderSniff).
if (isMinimaxH3ImageName(lower)) return 'minimaxh3image'
// GH #192: MOSS Image, an image model of its own (Qwen3.5 9B encoder, the
// FLUX.2 VAE). Before any family a word in its name could look like.
if (isMossImageName(lower)) return 'mossimage'
if (lower.includes('minimax_h3') || lower.includes('minimaxh3') || lower.includes('minimax-h3') || isFastH3(lower)) return 'minimaxh3'
// Video models — most specific first (order matters: specific before generic)
if (lower.includes('cogvideo')) return 'cogvideo'
if (lower.includes('framepack')) return 'framepack'
if (lower.includes('mochi')) return 'mochi'
if (lower.includes('cosmos')) return 'cosmos'
if (lower.includes('allegro')) return 'allegro'
if (lower.includes('svd') || lower.includes('stable-video-diffusion')) return 'svd'
if (lower.includes('pyramid') && (lower.includes('flow') || lower.includes('dit'))) return 'pyramidflow'
// Wan 2.2 TI2V-5B — unified text+image-to-video. Detect BEFORE the generic Wan
// match: it needs its own latent node (Wan22ImageToVideoLatent), the Wan 2.2 VAE
// and the dual T2V/I2V path, none of which the Wan 2.1 'unet_video' strategy has.
if (lower.includes('ti2v') || lower.includes('wan2.2') || lower.includes('wan2_2') || lower.includes('wan22')) return 'wan22'
if (lower.includes('wan')) return 'wan'
if (lower.includes('hunyuan')) return 'hunyuan'
// LTX 2.5 (Lightricks, Aug 2026) has its own two pass graph with sound, so
// it must beat the generic LTX match below, which is the 2.3 pipeline.
if (/ltx[._\- ]?2[._\- ]?5/.test(lower)) return 'ltx25'
if (lower.includes('ltx')) return 'ltx'
// ERNIE-Image (Baidu, uses flux2 CLIP type + ConditioningZeroOut for negative)
if (lower.includes('ernie-image') || lower.includes('ernie_image')) return 'ernie_image'
// Qwen-Image 2.1 (Comfy-Org repack, September 2026): ONE model for both
// generating and editing, on UNETLoader + CLIPLoader(qwen_image) + its own
// 64-channel VAE, encoded through TextEncodeQwenImage21.
//
// Version-bound on purpose. The older Qwen-Image (2508) and Qwen-Image-Edit
// (2509/2511) files carry the same `qwen_image` stem but need a different
// text-encode node, so a bare stem match would route them onto the 2.1
// pipeline and ComfyUI would reject the graph. They keep falling through to
// 'unknown', which refuses honestly with "LU could not determine this
// model's architecture" instead of guessing.
//
// Deliberately NOT caught here: the 2.1 text encoder itself
// (qwen3vl_8b_int8_convrot) and Z-Image's qwen_3_4b carry no `qwen_image`
// stem, and Krea 2's companion qwen_image_vae carries no 2.1 tag. This
// function also sees VAE and text-encoder filenames (addonLane), so a match
// that was any wider would mislabel a companion file as a main model.
// Before the 'krea' check and the 'xl' suffix scan below, so no later tag
// can take a 2.1 file first.
if (/qwen[._-]?image/.test(lower) && /2[._-]?1/.test(lower)) return 'qwenimage'
// Noct Q (Noctaluna, September 2026): a Qwen-Image 2.1 finetune whose file
// names say neither "qwen" nor "2.1" (NoctQ_V4_int8_convrot.safetensors on
// Hugging Face, the CivitAI spelling noctQ_v4). Its header carries the
// tensor names and shapes of the official file, so it runs on the same lane.
if (/(^|[^a-z0-9])noct[._ -]?q(?![a-z])/.test(lower)) return 'qwenimage'
// Qwen-Image 1 (2508, 2512) and Qwen-Image-Edit (2509, 2511, FireRed):
// Qwen2.5-VL 7B encoder, qwen_image_vae, and for the edit files
// TextEncodeQwenImageEditPlus (Discord 2026-09-28: "every model except
// Juggernaut" — these used to fall through to 'unknown' and the checkpoint
// loader). Never the VAE that carries the same stem.
if ((/qwen[._-]?image/.test(lower) || lower.includes('firered_image_edit')) && !/[._-]vae/.test(lower)) return 'qwenimage1'
// Families that used to fall through to 'unknown' and the checkpoint loader.
// The header sniff (commands/model_sniff.rs) finds them under any name; the
// names here cover a ComfyUI on another machine, where no header is readable.
// Word start only: zavychromaXL is an SDXL checkpoint.
if (/(^|[^a-z])chroma/.test(lower)) return 'chroma'
if (lower.includes('hidream')) return 'hidream'
if (/(^|[^a-z0-9])sd[._-]?3|stable[._-]?diffusion[._-]?3/.test(lower)) return 'sd3'
if (lower.includes('lumina') || lower.includes('netayume')) return 'lumina2'
// Z-Image (uses qwen_image CLIP type, NOT flux2 — different embedding dimensions)
if (lower.includes('z_image') || lower.includes('z-image') || lower.includes('zimage')) return 'zimage'
if (lower.includes('flux-2') || lower.includes('flux2')) return 'flux2'
if (lower.includes('flux')) return 'flux'
// Krea 2 (K9, GH #136): CivitAI ships these as a single checkpoint
// file, but the base model is a decoupled UNETLoader + CLIPLoader(type=
// "krea2") + VAE pipeline, NOT a self-contained CheckpointLoaderSimple
// graph. Before this check the name fell through to 'unknown', which
// CLASSIFIED it as an ordinary checkpoint and loaded it with
// CheckpointLoaderSimple, and the file has no embedded CLIP, so ComfyUI
// answered "clip input is invalid: None". Detect before the 'xl' suffix
// scan below: CivitAI filenames commonly end "...Krea2_fp8.safetensors",
// which would otherwise never reach it anyway, but keep the ordering
// explicit so a future tag never sneaks in ahead of it.
if (lower.includes('krea')) return 'krea2'
// Explicit architecture tags
if (lower.includes('sdxl') || lower.includes('sd_xl')) return 'sdxl'
if (lower.includes('sd15') || lower.includes('sd_1') || lower.includes('v1-5') || lower.includes('sd1.5')) return 'sd15'
// "xl" suffix/tag (but not "xxl" which is a text encoder)
if (/[_\-.]xl[_\-.]|[_\-.]xl$|_xl_/i.test(name)) return 'sdxl'
// Known community model names
for (const [keyword, type] of Object.entries(KNOWN_MODELS)) {
if (lower.includes(keyword)) return type
}
// SD 1.5 patterns
if (lower.includes('1.5') || lower.includes('v1_5')) return 'sd15'
return 'unknown'
}
/** HiDream I1 ships as fast, dev and full, three different samplers
* (hidream_i1_fast / _dev / _full templates). Fast is the type default. */
export function hidreamSampling(model: string): { steps: number; cfg: number; sampler: string; scheduler: string } {
const lower = model.toLowerCase()
if (lower.includes('full')) return { steps: 50, cfg: 5.0, sampler: 'uni_pc', scheduler: 'simple' }
if (lower.includes('dev')) return { steps: 28, cfg: 1.0, sampler: 'lcm', scheduler: 'normal' }
const d = MODEL_TYPE_DEFAULTS.hidream
return { steps: d.steps, cfg: d.cfg, sampler: d.sampler, scheduler: d.scheduler }
}
export function isImageModelType(type: ModelType): boolean {
return type === 'flux' || type === 'flux2' || type === 'krea2' || type === 'zimage' || type === 'ernie_image' || type === 'qwenimage'
|| type === 'qwenimage1' || type === 'chroma' || type === 'hidream' || type === 'sd3' || type === 'lumina2'
|| type === 'sdxl' || type === 'sd15' || type === 'minimaxh3image' || type === 'mossimage' || type === 'unknown'
}
export function isVideoModelType(type: ModelType): boolean {
return type === 'wan' || type === 'wan22' || type === 'hunyuan' || type === 'ltx' || type === 'ltx25' || type === 'mochi' || type === 'cosmos'
|| type === 'cogvideo' || type === 'svd' || type === 'framepack' || type === 'pyramidflow' || type === 'allegro'
|| type === 'minimaxh3'
}
/**
* Can this model accept a source still (image-to-video)? True for explicit i2v
* tags, SVD, FramePack, Wan 2.2 TI2V (dual T2V/I2V), LTX-Video (its base
* checkpoints drive both graphs via LTXVImgToVideo), and Cosmos Video2World.
* Used to build the Animate picker list and to route an inputImage to the I2V
* branch (local lane restored 2026-07-17).
*/
export function isI2VModel(name: string): boolean {
const lower = name.toLowerCase()
// FastH3 is text to video only (see isFastH3), whatever its H3 family says.
if (isFastH3(lower)) return false
// An A14B half is one or the other, never both like the TI2V-5B.
if (isWan22A14B(lower)) return lower.includes('i2v') || !lower.includes('t2v')
// Wan 2.1 FLF2V (wan2.1_flf2v_720p_14B) starts from an image and ends on
// a second one (B38); its name carries no i2v tag.
if (/(^|[^a-z0-9])flf2v([^a-z0-9]|$)/.test(lower)) return true
return lower.includes('i2v') || lower.includes('svd') || lower.includes('framepack')
|| lower.includes('ti2v') || lower.includes('wan2.2') || lower.includes('wan2_2') || lower.includes('wan22')
|| lower.includes('ltx') || lower.includes('video2world') || classifyModel(name) === 'minimaxh3'
}
/**
* Can this model do TEXT-to-video (no source image required)? Everything EXCEPT
* the I2V-ONLY checkpoints: SVD and FramePack load via image-only/wrapper loaders,
* a CogVideoX *I2V* checkpoint needs a still, and Cosmos Video2World is the
* conditioned variant (Text2World is its t2v sibling) — none can run a T2V graph.
* Wan 2.2 TI2V is dual-capable, so it stays in the T2V list too (the
* `ti2v`/`wan2.2` guard wins over the generic `i2v` substring), and LTX base
* checkpoints stay because they run both graphs.
*/
export function isT2VCapable(name: string): boolean {
const lower = name.toLowerCase()
// Merged i2v-only builds (rapid AIO) carry the wan2.2 tag but cannot run a
// T2V graph — check before the generic wan2.2 pass-through.
if (lower.includes('rapid') && lower.includes('i2v')) return false
if (isWan22A14B(lower)) return !lower.includes('i2v')
if (lower.includes('ti2v') || lower.includes('wan2.2') || lower.includes('wan2_2') || lower.includes('wan22')) return true
if (lower.includes('svd') || lower.includes('framepack')) return false
if (lower.includes('video2world')) return false
if (lower.includes('i2v') || /(^|[^a-z0-9])flf2v([^a-z0-9]|$)/.test(lower)) return false
return true
}
/**
* Reference to video (Ref2V, D24): models that take the user's picture as a
* REFERENCE for who or what is in the clip, not as its first frame. Animate
* offers them next to the i2v models. MiniMax H3 (ref2va) is not here: it is
* an i2v family of its own and its builder already takes the reference.
*
* vace Wan 2.1 VACE, WanVaceToVideo with only a reference_image
* phantom Phantom Wan (subject references)
* magref Wan 2.1 MAGREF (masked multi references)
* r2v any other file whose name says r2v / ref2v
*/
export type Ref2VFamily = 'vace' | 'phantom' | 'magref' | 'r2v'
export function ref2vFamily(name: string | null | undefined): Ref2VFamily | null {
if (!name) return null
const lower = name.toLowerCase()
if (classifyModel(name) === 'minimaxh3') return null
if (lower.includes('vace')) return 'vace'
if (lower.includes('phantom')) return 'phantom'
if (lower.includes('magref')) return 'magref'
if (/(^|[^a-z0-9])(ref2v|r2v)([^a-z0-9]|$)/.test(lower)) return 'r2v'
return null
}
/**
* Why Animate cannot run this reference model, or null when it can. LU builds
* the reference graph for one family only (Wan 2.1 VACE, the same
* WanVaceToVideo node the Motion tab already drives). The others need a graph
* LU does not have, and a guess would end in a ComfyUI error at best and a
* clip that silently ignores the picture at worst.
*/
export function ref2vRefusal(name: string | null | undefined): string | null {
const family = ref2vFamily(name)
if (!family) return null
const lower = (name ?? '').toLowerCase()
switch (family) {
case 'vace':
if (lower.includes('module')) {
return 'This file is a VACE add-on module for the WanVideoWrapper nodes, not a full model. Animate runs full Wan 2.1 VACE models such as wan2.1_vace_14B_fp16.'
}
if (/wan[._-]?2[._-]?2|(^|[^a-z])fun([^a-z]|$)|high[._-]?noise|low[._-]?noise/.test(lower)) {
return 'Wan 2.2 VACE Fun needs its own VAE and, for the 14B, a high noise and a low noise model run one after the other. LU builds neither yet. Animate runs Wan 2.1 VACE models.'
}
return null
case 'phantom':
return 'Phantom needs its own subject reference workflow, which LU does not build yet. Animate runs Wan 2.1 VACE as a reference model.'
case 'magref':
return 'MAGREF needs its own masked reference workflow, which LU does not build yet. Animate runs Wan 2.1 VACE as a reference model.'
case 'r2v':
return 'LU cannot tell from this file name which reference workflow the model needs. Animate runs Wan 2.1 VACE as a reference model.'
}
}
/** Can Animate run this model with the picture as a reference? */
export function isRunnableRef2V(name: string | null | undefined): boolean {
return ref2vFamily(name) !== null && ref2vRefusal(name) === null
}
/** The second line of a reference model's row in the Animate picker: what
* the picture becomes, or that the model cannot run here (Create then says
* why in full). Nothing on the other tabs or for any other model. */
export function ref2vRowNote(name: string, intent: string): string | undefined {
if (intent !== 'animate' || !ref2vFamily(name)) return undefined
return ref2vRefusal(name) ? 'Reference model, not supported yet' : 'Uses your image as a reference'
}
/** The Animate list of a ComfyUI host takes the reference models of the
* Motion lane (VACE sits there, not on the video list) next to the video
* models. A name on both lists is kept once. */
export function withReferenceModels(video: ClassifiedModel[], motion: ClassifiedModel[]): ClassifiedModel[] {
const seen = new Set(video.map((m) => m.name))
return [...video, ...motion.filter((m) => m.type === 'wanvace' && !seen.has(m.name))]
}
/** Can this model run the given video intent? Animate/Extend feed a start
* image (i2v), everything else on the video lane is a text-to-video run.
* ONE rule for the picker, the starter-bundle gate and submit: whenever two
* of them disagreed a real user hit a wall. SVD-only boxes showed
* "No matches" yet never offered the starter bundle, and a fresh boot
* submitted a persisted SVD pick into the T2V lane, which builds SVD's
* LoadImage graph and dies on "Custom validation failed" (2026-08-01). */
export function canRunVideoIntent(name: string, intent: string): boolean {
return intent === 'animate' || intent === 'extend' ? isI2VModel(name) : isT2VCapable(name)
}
/** Can this model run the given video intent? The catalogue's own word
* where the entry carries one, the name otherwise (canRunVideoIntent). An MLX
* display name is not a file name: "MLX LTX-2.3 Dev" reads as image to video
* by name and fails on a start image in the engine. */
export function canRunVideoLane(m: ClassifiedModel, intent: string): boolean {
if (!m.startImage) {
// A reference model is offered on Animate only: it does not continue a
// clip (Extend), and VACE without a reference has no graph on Video.
// One it cannot run stays listed, so its row and Create say why.
if (intent === 'animate' && ref2vFamily(m.name)) return true
if (m.type === 'wanvace' || ref2vFamily(m.name) === 'vace') return false
return canRunVideoIntent(m.name, intent)
}
return intent === 'animate' || intent === 'extend' ? m.startImage !== 'none' : m.startImage !== 'required'
}
/** The video models the CURRENT intent can actually run (see canRunVideoLane).
* On Animate a reference model LU cannot run goes to the end, so it is never
* the pick a fresh lane falls back to. */
export function videoLaneModels(list: ClassifiedModel[], intent: string): ClassifiedModel[] {
const lane = list.filter((m) => canRunVideoLane(m, intent))
if (intent !== 'animate') return lane
return [...lane.filter((m) => !ref2vRefusal(m.name)), ...lane.filter((m) => ref2vRefusal(m.name))]
}
/** The video models a run of `intent` can really use: videoLaneModels without
* the reference models Animate lists only to say why they cannot run. The
* "nothing installed" gates count these, so a lone Phantom file does not hide
* the starter download. */
export function runnableVideoLaneModels(list: ClassifiedModel[], intent: string): ClassifiedModel[] {
return videoLaneModels(list, intent).filter((m) => !ref2vRefusal(m.name))
}
/** Where a bundle keeps the thing that actually generates. The rest of a
* bundle is VAE and text encoder, and those names say nothing about i2v. */
const BUNDLE_MODEL_SUBFOLDERS = new Set(['diffusion_models', 'checkpoints', 'unet'])
/**
* The starter bundle whose MODEL this lane can actually run.
*
* Third place that has to obey canRunVideoIntent, and the one that did not.
* Stage decides "this lane has no models" through that rule, while the
* installer always took the first video bundle, a Wan 2.1 **T2V**. On Extend
* Video and Animate Image, which are i2v lanes, that bundle can never satisfy
* the gate: the card offers a 9.2 GB download, the download succeeds, ComfyUI
* lists every file, and the card comes back unchanged. Pressing the button
* again does exactly the same thing, forever.
*
* Measured on the box 2026-08-15 on Extend Video, and it is the other half of
* what Two users reported on 2026-08-13. The C8 fix cured
* the frozen status line; this cures the reason the card stayed at all.
*
* The other lanes need no such pick: their gate is a plain length check on
* their own list, and their single bundle always lands in it.
*/
export function bundleForVideoIntent<B extends { files: Array<{ filename?: string; subfolder?: string }> }>(
bundles: B[],
intent: string,
): B | undefined {
return bundles.find((b) =>
b.files.some((f) =>
!!f.filename &&
BUNDLE_MODEL_SUBFOLDERS.has(f.subfolder ?? '') &&
canRunVideoIntent(f.filename, intent)),
)
}
// ─── Default generation parameters per model type ───
export interface ModelTypeDefaults {
steps: number
cfg: number
sampler: string
scheduler: string
width: number
height: number
frames: number
fps: number
}
export const MODEL_TYPE_DEFAULTS: Record<string, ModelTypeDefaults> = {
// ── Image (frames/fps = 1; per-architecture so the chat-gen image path stops
// using a single hardcoded cfg 7 for everything — Flux/Z-Image are distilled
// and need a LOW cfg, SD1.5 must default to 512 not 1024). Values mirror the
// Create-tab MODEL_TYPE_DEFAULTS (createStore.ts) so both surfaces agree. ──
sd15: { steps: 25, cfg: 7.0, sampler: 'euler_ancestral', scheduler: 'normal', width: 512, height: 512, frames: 1, fps: 1 },
sdxl: { steps: 25, cfg: 7.0, sampler: 'dpmpp_2m', scheduler: 'karras', width: 1024, height: 1024, frames: 1, fps: 1 },
flux: { steps: 20, cfg: 1.0, sampler: 'euler', scheduler: 'simple', width: 1024, height: 1024, frames: 1, fps: 1 },
flux2: { steps: 20, cfg: 1.0, sampler: 'euler', scheduler: 'simple', width: 1024, height: 1024, frames: 1, fps: 1 },
// Krea 2 (GH #136, corrected Runde 3): the issue documents two author
// recipes that share nothing but euler / CFG 1 / 8 steps / 1024x1024 -
// FinePorn v4 NVFP4 (the reporter's only PROVEN successful run) uses
// scheduler 'beta' and no extra sampling node; LUSTIFY! v10 Krea2 uses
// 'simple' plus ModelSamplingAuraFlow shift 4 (see buildDynamicWorkflow's
// unet_krea2 comment). classifyModel cannot tell the two apart, so this
// default follows the one run the issue actually confirms working rather
// than guessing at the other.
krea2: { steps: 8, cfg: 1.0, sampler: 'euler', scheduler: 'beta', width: 1024, height: 1024, frames: 1, fps: 1 },
zimage: { steps: 12, cfg: 3.5, sampler: 'euler', scheduler: 'simple', width: 1024, height: 1024, frames: 1, fps: 1 },
// Qwen-Image 2.1: every number is the one the official Comfy-Org templates
// ship (image_qwen_image_2_1_t2i.json and image_qwen_image_2_1_image_edit.json,
// KSampler widgets: 25 steps, cfg 1, euler, simple; canvas 1024x1024 at
// 1 megapixel). Native 2K is available by raising width/height.
qwenimage: { steps: 25, cfg: 1.0, sampler: 'euler', scheduler: 'simple', width: 1024, height: 1024, frames: 1, fps: 1 },
// Numbers from the official Comfy-Org templates (image_qwen_image, image_qwen_image_edit_2509,
// image_chroma_text_to_image, hidream_i1_fast, sd3.5_simple_example) and nodes_lumina2.
qwenimage1: { steps: 20, cfg: 4.0, sampler: 'euler', scheduler: 'simple', width: 1328, height: 1328, frames: 1, fps: 1 },
chroma: { steps: 26, cfg: 3.5, sampler: 'euler', scheduler: 'beta', width: 1024, height: 1024, frames: 1, fps: 1 },
hidream: { steps: 16, cfg: 1.0, sampler: 'lcm', scheduler: 'normal', width: 1024, height: 1024, frames: 1, fps: 1 },
sd3: { steps: 20, cfg: 4.0, sampler: 'euler', scheduler: 'sgm_uniform', width: 1024, height: 1024, frames: 1, fps: 1 },
lumina2: { steps: 25, cfg: 4.0, sampler: 'res_multistep', scheduler: 'simple', width: 1024, height: 1024, frames: 1, fps: 1 },
unknown:{ steps: 25, cfg: 7.0, sampler: 'euler', scheduler: 'normal', width: 1024, height: 1024, frames: 1, fps: 1 },
// ── Video ──
wan: { steps: 30, cfg: 6.0, sampler: 'euler', scheduler: 'normal', width: 832, height: 480, frames: 81, fps: 16 },
// Wan 2.2 TI2V-5B — native 1280×704 @ 24 fps, unified T2V/I2V. Default to a
// VRAM-/speed-friendly 1024×576 16:9 on 12 GB cards (native res is still available
// by setting width/height); 49 frames ≈ 2 s, the duration matrix runs up to ~7 s.
wan22: { steps: 30, cfg: 5.0, sampler: 'euler', scheduler: 'simple', width: 1024, height: 576, frames: 49, fps: 24 },
hunyuan: { steps: 30, cfg: 6.0, sampler: 'euler', scheduler: 'normal', width: 848, height: 480, frames: 45, fps: 24 },
ltx: { steps: 20, cfg: 3.0, sampler: 'euler', scheduler: 'normal', width: 768, height: 512, frames: 97, fps: 24 },
// LTX 2.5 (official Comfy-Org templates video_ltx2_5_t2v / _i2v, read
// 2026-10-02): the distilled model runs two fixed sigma passes (8 steps, then
// 3) on euler_ancestral at CFG 1, so steps and sampler here are only what the
// sliders show. 1280x704 is the template's 16:9 canvas on the 64 pixel grid
// the half size first pass needs; 121 frames at 24 fps is its 5 second default.
ltx25: { steps: 8, cfg: 1.0, sampler: 'euler_ancestral', scheduler: 'simple', width: 1280, height: 704, frames: 121, fps: 24 },
// Official templates video_minimax_h3_t2v / _i2v (Comfy-Org/workflow_templates,
// read 2026-10-01): res_multistep / simple, 20 steps, BasicGuider (no CFG),
// 1344x768 native canvas, 24 fps, 124 frames is the node's ~5 s default.
minimaxh3: { steps: 20, cfg: 1.0, sampler: 'res_multistep', scheduler: 'simple', width: 1344, height: 768, frames: 124, fps: 24 },
// C78: MiniMax H3 Image, official template image_minimax_h3_image_t2i (read
// 12.11.2026): KSampler 6 steps at CFG 1 on euler / simple. The template
// note says it works badly below about 4 MP, so 2048 x 2048.
minimaxh3image: { steps: 6, cfg: 1.0, sampler: 'euler', scheduler: 'simple', width: 2048, height: 2048, frames: 1, fps: 1 },
// GH #192: MOSS Image, the OpenMOSS defaults the reporter ran on ComfyUI
// 0.42.5: KSampler euler / simple, 50 steps, CFG 3; 512 px to 2K.
mossimage: { steps: 50, cfg: 3.0, sampler: 'euler', scheduler: 'simple', width: 1024, height: 1024, frames: 1, fps: 1 },
mochi: { steps: 30, cfg: 4.5, sampler: 'euler', scheduler: 'normal', width: 848, height: 480, frames: 84, fps: 24 },
cosmos: { steps: 35, cfg: 7.0, sampler: 'euler', scheduler: 'normal', width: 1024, height: 1024, frames: 121, fps: 24 },
cogvideo: { steps: 50, cfg: 6.0, sampler: 'euler_ancestral', scheduler: 'normal', width: 480, height: 480, frames: 49, fps: 8 },
svd: { steps: 20, cfg: 2.5, sampler: 'euler', scheduler: 'karras', width: 576, height: 1024, frames: 25, fps: 6 },
framepack: { steps: 25, cfg: 7.0, sampler: 'euler', scheduler: 'normal', width: 640, height: 480, frames: 49, fps: 24 },
pyramidflow: { steps: 20, cfg: 7.0, sampler: 'euler', scheduler: 'normal', width: 768, height: 1280, frames: 16, fps: 8 },
allegro: { steps: 100, cfg: 7.5, sampler: 'euler', scheduler: 'normal', width: 720, height: 1280, frames: 88, fps: 15 },
animatediff: { steps: 20, cfg: 7.5, sampler: 'euler_ancestral', scheduler: 'normal', width: 512, height: 512, frames: 16, fps: 8 },
// AnimateDiff Lightning override (4 steps only)
animatediff_lightning: { steps: 4, cfg: 1.0, sampler: 'euler', scheduler: 'sgm_uniform', width: 512, height: 512, frames: 16, fps: 8 },
// ERNIE-Image Turbo (Baidu 8B DiT)
ernie_image: { steps: 8, cfg: 1, sampler: 'euler', scheduler: 'simple', width: 1024, height: 1024, frames: 1, fps: 1 },
// ── 2.5.8 specialized local lanes (core-node defaults, July 2026) ──
// ACE-Step music: width/height are unused by the audio graph but keep the
// shared param scaffolding happy; track length lives in musicDuration.
ace: { steps: 50, cfg: 5.0, sampler: 'euler', scheduler: 'simple', width: 1024, height: 1024, frames: 1, fps: 1 },
// YuE2 (official template audio_yue2_text2music): KSampler 32 steps, cfg 1,
// dpm_2 on sgm_uniform. The audio graph reads none of it from the sliders but
// the scaffold wants the fields.
yue2: { steps: 32, cfg: 1.0, sampler: 'dpm_2', scheduler: 'sgm_uniform', width: 1024, height: 1024, frames: 1, fps: 1 },
// Wan 2.2 S2V — node defaults 832×480, length 77 @ 16 fps.
wans2v: { steps: 20, cfg: 6.0, sampler: 'euler', scheduler: 'simple', width: 832, height: 480, frames: 77, fps: 16 },
// Wan 2.2 Animate — node defaults 832×480, length 77 @ 16 fps.
wananimate: { steps: 20, cfg: 5.0, sampler: 'euler', scheduler: 'simple', width: 832, height: 480, frames: 77, fps: 16 },
// Wan 2.1 VACE — node defaults 832×480, length 81 @ 16 fps.
wanvace: { steps: 25, cfg: 5.0, sampler: 'euler', scheduler: 'simple', width: 832, height: 480, frames: 81, fps: 16 },
}
// ─── Component Requirements per model type ───
// K9 (GH #136): the registry used to be declared here AND, separately, in
// discover.ts, two copies of the same per-model-type data that both had to
// be remembered on every new architecture. Krea 2 only reached one of them.
// Canonical data now lives in component-registry.ts (Audit W-T2 pattern,
// same fix as pulling the bundle catalog into model-bundles.ts); both
// comfyui.ts and discover.ts import it and neither has to import the other.
export type { ComponentSpec, ComponentRequirements } from './component-registry'
export { COMPONENT_REGISTRY } from './component-registry'
// ─── Connection & Info ───
/** W32 follow-up: the limit of the check before a run and of the render
* heartbeat's check (the proxy's own default is five minutes). */
export const COMFY_PROBE_LIMIT_MS = 15_000
/** Does ComfyUI answer. `limitMs` bounds the wait (none: the proxy's default). */
export async function checkComfyConnection(limitMs?: number): Promise<boolean> {
try {
const res = await localFetch(comfyuiUrl('/system_stats'), limitMs ? { timeoutMs: limitMs } : undefined)
return res.ok
} catch {
return false
}
}
/**
* Force ComfyUI to re-scan model directories. Works on ComfyUI 2024+ with
* /api/refresh.
*
* Retries on transient failures because in production we hit two real-world
* race conditions:
* 1. ComfyUI is mid-startup and `/api/refresh` 404s briefly (Discord report
* from a user: logs show repeated localhost:8188 connect errors after a
* fresh download lands).
* 2. ComfyUI is busy executing a workflow and accepts the refresh but doesn't
* finish the directory scan before we query `/object_info`.
*
* For both cases a single attempt silently returned `false` and the caller
* never knew the cache stayed stale.
*/
export async function refreshComfyModels(maxAttempts = 3): Promise<boolean> {
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const res = await localFetch(comfyuiUrl('/api/refresh'), { method: 'POST', timeoutMs: COMFY_STATS_TIMEOUT_MS })
if (res.ok) return true
} catch { /* network blip — retry */ }
if (attempt < maxAttempts - 1) {
await new Promise(r => setTimeout(r, 1000 * (attempt + 1)))
}
}
return false // Older ComfyUI versions without /api/refresh — non-fatal
}
// ─── System VRAM Detection ───
let cachedVRAM: number | null = null
/**
* Is this /system_stats entry ComfyUI's CPU pseudo-device?
*
* When torch has no usable GPU backend ComfyUI still reports one device, and
* for that one `vram_total` is `psutil.virtual_memory().total`. It is system
* RAM wearing a VRAM field's name.
*/
function isCpuDevice(dev: unknown): boolean {
const d = (dev ?? {}) as { type?: unknown; name?: unknown }
const type = String(d.type ?? '').trim().toLowerCase()
const name = String(d.name ?? '').trim().toLowerCase()
return type === 'cpu' || name === 'cpu' || name.startsWith('cpu:') || name.startsWith('cpu ')
}
/**
* The largest real VRAM figure in a /system_stats payload, in bytes, or null.
*
* GitHub #123: the Model Manager fit check showed "62 GB GPU · 62 GB
* RAM" on a box with a 16 GB RX 9070 XT and 64 GB of RAM, the same number
* twice, while the Settings page a tab away had the correct 16 GB. This is
* where the 62 came from. ROCm was not detected, so his ComfyUI ran on the
* processor, so /system_stats carried exactly one device, the CPU one, whose
* `vram_total` is the machine's RAM. The old reader took `devices[0]` whatever
* it was, and DiscoverModels then kept the LARGER of that and the honest 16 GB
* from detect_gpus.
*
* Two rules, and the second matters as much as the first:
* - CPU entries are not a GPU and never contribute a size.
* - When nothing else is left the answer is null, which the UI renders as
* "unknown". A fit check that says nothing is a fit check a user can still
* trust; one that says 62 GB sends him to download a model that cannot run.
*
* Apple's `mps` device is NOT excluded. Unified memory really is the VRAM
* there, so the number is right for the machine it comes from.
*
* `unifiedMemory` is the same point one step further, and it is the reason
* macOS passes true. `detect_macos` reports no size at all, so /system_stats is
* the ONLY VRAM source on a Mac, and a ComfyUI started with --cpu reports a cpu
* device there. Dropping it would have turned the fit check on every such Mac
* into "GPU unknown" and taken the "Fits my PC" filter with it. On a machine
* where the graphics unit and the processor share one pool, the pool is the
* honest answer for both, which is exactly what makes the Windows case wrong:
* there the card has its own memory and the CPU figure is a different number
* about a different thing.
*
* Pure and exported so the case above can be a test instead of a screenshot.
*/
export function pickDeviceVramBytes(
devices: unknown,
opts: { unifiedMemory?: boolean } = {},
): number | null {
if (!Array.isArray(devices)) return null
let best = 0
for (const dev of devices) {
if (!opts.unifiedMemory && isCpuDevice(dev)) continue
const bytes = (dev as { vram_total?: unknown } | null)?.vram_total
if (typeof bytes === 'number' && Number.isFinite(bytes) && bytes > best) best = bytes
}
return best > 0 ? best : null
}
export async function getSystemVRAM(): Promise<number | null> {
if (cachedVRAM !== null) return cachedVRAM
try {
const res = await localFetch(comfyuiUrl('/system_stats'), { timeoutMs: COMFY_STATS_TIMEOUT_MS })
if (!res.ok) return null
const data = await res.json()
// ComfyUI returns top-level devices[].vram_total in bytes
const vramBytes = pickDeviceVramBytes(data?.devices, { unifiedMemory: isMacOS() })
if (vramBytes !== null) {
cachedVRAM = Math.round(vramBytes / (1024 * 1024 * 1024)) // bytes → GB
return cachedVRAM
}
} catch { /* ComfyUI not running */ }
return null
}
/**
* The running ComfyUI's own version string, or null if it does not say.
*
* /system_stats carries `system.comfyui_version` on every current build; very
* old ones simply have no such field, and that is an answer too (the caller
* maps it to the `unknown` placeholder). Used by the Create tab's cross-origin
* notice to tell "the same ComfyUI as when you dismissed this" from "a
* different one", see lib/comfy-cors-notice.ts. Not cached: a restart under
* LU's management, or a user update, is exactly the change worth noticing.
*/
export async function getComfyVersion(): Promise<string | null> {
try {
const res = await localFetch(comfyuiUrl('/system_stats'), { timeoutMs: COMFY_STATS_TIMEOUT_MS })
if (!res.ok) return null
const data = await res.json()
const v = data?.system?.comfyui_version
return typeof v === 'string' && v.trim() ? v.trim() : null
} catch {
return null
}
}
// Check if a specific node exists in ComfyUI (lightweight, single node check)
async function nodeExists(nodeName: string): Promise<boolean> {
try {
const res = await localFetch(comfyuiUrl(`/object_info/${nodeName}`), { timeoutMs: COMFY_LIST_TIMEOUT_MS })
if (!res.ok) return false
const data = await res.json()
return !!(data && data[nodeName])
} catch {
return false
}
}
/** Which of the video save nodes this ComfyUI has, as the sync check
* addVideoSave wants (A19). */
async function videoSaverPresence(): Promise<(classType: string) => boolean> {
const names = ['CreateVideo', 'SaveVideo', 'VHS_VideoCombine', 'SaveAnimatedWEBP']
const present = await Promise.all(names.map((name) => nodeExists(name)))
const have = new Set(names.filter((_, i) => present[i]))
return (classType) => have.has(classType)
}
/** One /object_info call for one node, read through the shared combo reader.
*
* `strict` is for the two loaders whose absence means ComfyUI itself is not
* answering: those still throw on an HTTP error so the caller can tell "no
* models installed" apart from "no engine". Everything else soft-fails to an
* empty list, because an optional pack that is not installed is not an error.
*
* Nothing here reads the spec by hand any more. The AnimateDiff node answers
* in the newer COMBO schema while the stock loaders answer in the legacy one
* (proven on the box, see comfyui-enum.ts), and one hand-read spec was enough
* to take the whole video discovery down. */
async function fetchNodeOptions(
node: string,
field: string,
opts: { strict?: boolean } = {},
): Promise<string[]> {
const res = await localFetch(comfyuiUrl(`/object_info/${node}`), { timeoutMs: COMFY_LIST_TIMEOUT_MS })
if (!res.ok) {
if (opts.strict) throw new Error(`ComfyUI /object_info/${node} failed (HTTP ${res.status})`)
return []
}
const data = await res.json()
return nodeComboOptions(data, node, field)
}
export async function getCheckpoints(): Promise<string[]> {
return fetchNodeOptions('CheckpointLoaderSimple', 'ckpt_name', { strict: true })
}
export async function getDiffusionModels(): Promise<string[]> {
return fetchNodeOptions('UNETLoader', 'unet_name', { strict: true })
}
/**
* One optional loader, with "the node is not registered here" told apart from
* "the node is registered and lists nothing".
*
* The difference decides whether a file may be called invisible. A loader that
* is simply absent (a ComfyUI older than the node, a distro that ships without
* it) has said nothing about the folder, and treating its silence as "ComfyUI
* cannot see your file" would send a perfectly installed bundle back to the
* download button. `null` is that silence; the folder is then left out of the
* lists below and nothing judges a file in it.
*/
async function nodeOptionsOrNull(node: string, field: string): Promise<string[] | null> {
try {
const res = await localFetch(comfyuiUrl(`/object_info/${node}`), { timeoutMs: COMFY_LIST_TIMEOUT_MS })
if (!res.ok) return null
const data = await res.json()
// ComfyUI answers 200 with `{}` for a class it does not know.
if (!data || typeof data !== 'object' || !(node in (data as Record<string, unknown>))) return null
return nodeComboOptions(data, node, field)
} catch (err) {
log.warn('comfyui.fetch_folder_failed', { node, err })
return null
}
}
/** The loader for one folder of COMFY_MODEL_FOLDERS, by subfolder. The node and
* field of a folder are spelled ONCE, in that table. */
async function folderOptions(subfolder: string): Promise<string[] | null> {
const entry = COMFY_MODEL_FOLDERS.find((f) => f.subfolder === subfolder)
return entry ? entry.read() : null
}
export async function getVAEModels(): Promise<string[]> {
return (await folderOptions('vae')) ?? []
}
export async function getCLIPModels(): Promise<string[]> {
return (await folderOptions('text_encoders')) ?? []
}
/**
* F2 (GH#4): list LoRA files ComfyUI knows about. Pulls the same
* enum LoraLoader's `lora_name` dropdown shows, which is anything the user
* dropped into `<comfyui>/models/loras/`.
*/
export async function getLoraModels(): Promise<string[]> {
return (await listedLoras()) ?? []
}
/** The same list, or null when ComfyUI could not be asked. Only a real list
* may prune the LoRA stack (GH #146). */
export async function listedLoras(): Promise<string[] | null> {
return folderOptions('loras')
}
/** The five folders the R5 re-measure (2026-08-30) found missing entirely.
*
* A dummy .safetensors was dropped into ten ComfyUI model folders. ComfyUI
* listed all ten at once; the app showed five of them and never mentioned the
* other five. Two real files were invisible with them, an 817 MB CLIP-Vision
* encoder and, once the partial filter below was fixed, a 2.4 GB text
* encoder. */
export async function getCLIPVisionModels(): Promise<string[]> {
return (await folderOptions('clip_vision')) ?? []
}
/** The audio encoders the Talking Character lane needs (Wav2Vec2). Our catalog
* has written into `models\audio_encoders` since the 2.5.8 lanes and nothing
* read it back, so the file could be neither confirmed after its download nor
* listed among the things taking up the disk. */
export async function getAudioEncoderModels(): Promise<string[]> {
return (await folderOptions('audio_encoders')) ?? []
}
export async function getControlNetModels(): Promise<string[]> {
return (await folderOptions('controlnet')) ?? []
}
export async function getUpscaleModels(): Promise<string[]> {
return (await folderOptions('upscale_models')) ?? []
}
export async function getStyleModels(): Promise<string[]> {
return (await folderOptions('style_models')) ?? []
}
/** Embeddings are the one folder no loader node enumerates: ComfyUI serves
* them from its own /embeddings route instead, and that route hands back
* BASE NAMES with the extension stripped. So this list alone cannot be shown
* as installed files, and resolveEmbeddingFiles below puts the extension
* back before anything reaches the inventory. */
export async function getEmbeddingNames(): Promise<string[]> {
try {
const res = await localFetch(comfyuiUrl('/embeddings'), { timeoutMs: COMFY_LIST_TIMEOUT_MS })
if (!res.ok) return []
const data = await res.json()
if (!Array.isArray(data)) return []
return data.filter((n): n is string => typeof n === 'string' && n.length > 0)
} catch (err) {
log.warn('comfyui.fetch_embeddings_failed', { err })
return []
}
}
export async function getSamplers(): Promise<string[]> {
try {
const list = await fetchNodeOptions('KSampler', 'sampler_name')
if (list.length === 0) throw new Error('KSampler listed no samplers')
return list
} catch {
return ['euler', 'euler_ancestral', 'dpmpp_2m', 'dpmpp_2m_sde', 'dpmpp_sde', 'uni_pc', 'ddim']
}
}
export async function getSchedulers(): Promise<string[]> {
try {
const list = await fetchNodeOptions('KSampler', 'scheduler')
if (list.length === 0) throw new Error('KSampler listed no schedulers')
return list
} catch {
return ['normal', 'karras', 'simple', 'exponential', 'sgm_uniform']
}
}
/** Motion modules the AnimateDiff-Evolved pack enumerates. These files do NOT
* live under ComfyUI\models: the pack keeps them in
* custom_nodes/ComfyUI-AnimateDiff-Evolved/models, which is why the four
* ComfyUI\models loaders cannot see them and why every surface that only read
* those four reported an installed AnimateDiff bundle as nothing at all.
*
* This is also the node that answers in the newer COMBO schema on a real box,
* so it is the one that used to hand a bare "COMBO" string to callers. */
export async function getAnimateDiffModels(): Promise<string[]> {
return (await folderOptions('custom_nodes/ComfyUI-AnimateDiff-Evolved/models')) ?? []
}
// ─── Partial Download Filter ───
// Filters out files that exist on disk but are incomplete (< 90% of expected size).
// Uses known bundle file sizes from model-bundles.ts. Unknown files pass through.
let _knownFileSizes: Map<string, { subfolder: string; expectedBytes: number }> | null = null
async function getKnownFileSizes(): Promise<Map<string, { subfolder: string; expectedBytes: number }>> {
if (_knownFileSizes) return _knownFileSizes
_knownFileSizes = new Map()
for (const bundle of [...getImageBundles(), ...getVideoBundles()]) {
for (const f of bundle.files) {
if (f.filename && f.sizeGB && f.subfolder) {
_knownFileSizes.set(f.filename, {
subfolder: f.subfolder,
expectedBytes: Math.round(f.sizeGB * 1_073_741_824),
})
}
}
}
return _knownFileSizes
}
/** Filter out partially downloaded files. Returns only filenames that are complete. */
export async function filterPartialFiles(filenames: string[]): Promise<Set<string>> {
const known = await getKnownFileSizes()
const filesToCheck = filenames
.filter(name => known.has(name))
.map(name => {
const info = known.get(name)!
return { subfolder: info.subfolder, filename: name, expectedBytes: info.expectedBytes }
})
if (filesToCheck.length === 0) return new Set(filenames) // nothing to check → all pass
try {
const { backendCall } = await import('./backend')
const results: Array<{ filename: string; exists?: boolean; complete: boolean }> =
await backendCall('check_model_sizes', { files: filesToCheck })
// Only hide a model when it is CONFIRMED partial: present on disk but too
// small (exists === true && !complete). A bare `!complete` also dropped
// files the size-checker simply couldn't locate (exists === false) — which
// happens whenever the checker looks at the wrong ComfyUI path (the dev
// server's hardcoded path guesses, a custom/remote comfy host, etc.). But
// these filenames came FROM ComfyUI's own /object_info enums, so ComfyUI
// can load them — never hide a model ComfyUI vouches for just because a
// secondary size probe missed it (a user 2026-06-07: "no image model"
// even though ComfyUI had Juggernaut/RealVis installed).
const incomplete = new Set(results.filter(r => r.exists === true && !r.complete).map(r => r.filename))
if (incomplete.size > 0) {
log.info('comfyui.filtered_partial_downloads', { count: incomplete.size, files: [...incomplete] })
}
return new Set(filenames.filter(name => !incomplete.has(name)))
} catch {
return new Set(filenames) // if check fails, show all (backward compat)
}
}
// ─── Classified Model Lists ───
/**
* The main-model folders (checkpoints\, diffusion_models\, and the GGUF unets
* beside them), classified and narrowed to one lane.
*
* `hidePartialDownloads` is the entire difference between the two kinds of
* caller, and it is the R7 re-measure (2026-08-30) written down as a switch:
*
* - A PICKER asks "what can I render with", so a file that is confirmed too
* small for the catalogue entry of the same name is worth hiding: picking it
* would only hand the user a broken graph.
* - The INVENTORY asks "what is lying on my disk", and for that question a
* catalogue size is meaningless. It is a claim about the file WE ship, never
* about the file the user has.
*
* On the box a 13 MB `diffusion_models\flux1-dev-fp8.safetensors` was invisible
* in the whole app while a byte-identical copy named
* `flux1-dev-fp8-r67.safetensors` in the SAME folder listed fine: the catalogue
* ships FLUX.1 [dev] FP8 under the first name at 16.1 GB, so the size probe
* called the file partial and getImageModels dropped it, and the inventory read
* getImageModels. The user had a file on the disk he could neither see, nor
* measure, nor delete. Same shape as the R5 re-measure that took the filter out
* of the addon lanes, one folder further in.
*
* The catalogue card keeps its own verdict (discover.ts filters there) and goes
* on saying honestly that the package is not fully downloaded.
*/
/** A main model file of the local 3D lane (TRELLIS.2). It runs only in the
* 3D graph (buildThreeDWorkflow), never as an image or video model. */
export function isThreeDModelFile(name: string): boolean {
const base = name.split(/[\\/]/).pop()!.toLowerCase()
return /(^|[^a-z0-9])trellis[._-]?2([^0-9]|$)/.test(base)
}
/** A VAE that landed in a main model folder (Discord 2026-09-26: a CivitAI
* download of minimax_h3_video_vae_fp16 showed up as an IMAGE model). It can
* never run as one, so the picker leaves it out. Deliberately narrow: only a
* name that ENDS in vae (plus a precision tag). */
export function isStrayAddonFile(name: string): boolean {
const base = name.split(/[\\/]/).pop()!.toLowerCase()
// "bakedvae", "realvisxl_v40_vae": checkpoints that carry their VAE.
if (base.includes('baked') || /v\d+[a-z0-9]*[._-]vae/.test(base)) return false
return /[._-]vae([._-](fp16|fp32|bf16|fp8[a-z0-9_]*))?\.(safetensors|sft|pt|pth|ckpt|bin|gguf)$/.test(base)
}
/** Header families that map straight onto a ModelType. */
const SNIFF_TYPES: Record<string, ModelType> = {
flux: 'flux', flux2: 'flux2', krea2: 'krea2', zimage: 'zimage', ernie_image: 'ernie_image',
qwenimage: 'qwenimage', qwenimage1: 'qwenimage1', chroma: 'chroma', hidream: 'hidream',
sd3: 'sd3', lumina2: 'lumina2', sdxl: 'sdxl', sd15: 'sd15', wan: 'wan', minimaxh3: 'minimaxh3',
minimaxh3image: 'minimaxh3image',
}
/** Name types the header may overrule: the image families and 'unknown'. A
* video or lane name keeps its name type, because Wan 2.1 and 2.2 (and S2V,
* Animate, VACE) share one tensor layout and only the name tells them apart. */
const SNIFF_OVERRULES = (t: ModelType) => isImageModelType(t) || t === 'minimaxh3'
/** C78: a name taken for H3 video may only be turned into H3 Image by its
* header. The other video families share layouts the header cannot tell apart. */
function headerMayRetype(from: ModelType, to: ModelType): boolean {
return from !== 'minimaxh3' || to === 'minimaxh3image'
}
/**
* Discord 2026-09-26..28: a CivitAI name
* says nothing reliable about the architecture, and every name LU could not
* place went to the checkpoint loader ("Node 1 (CheckpointLoaderSimple):
* Value not in list"). The file header does say it. Rewrites `type` in place
* from the header, drops files that are a bare VAE or text encoder, and
* records which parts an all-in-one file carries. Best effort: a ComfyUI on
* another machine, a GGUF, or a browser build keeps the name-based answer.
*/
export async function applyHeaderSniff(models: ClassifiedModel[]): Promise<void> {
const ask = models.filter((m) => SNIFF_OVERRULES(m.type) && !m.name.toLowerCase().endsWith('.gguf'))
if (ask.length === 0) return
let answers: Array<{ folder: string; name: string; arch?: string | null; hasTextEncoder?: boolean; hasVae?: boolean }>
try {
const { backendCall, isTauri } = await import('./backend')
if (!isTauri()) return
answers = await backendCall('sniff_model_files', {
files: ask.map((m) => ({ folder: m.source === 'checkpoint' ? 'checkpoints' : 'diffusion_models', name: m.name })),
})
} catch (err) {
log.warn('comfyui.header_sniff_failed', { err })
return
}
const byKey = new Map(answers.map((a) => [`${a.folder}|${a.name}`, a]))
const drop = new Set<ClassifiedModel>()
for (const m of ask) {
const a = byKey.get(`${m.source === 'checkpoint' ? 'checkpoints' : 'diffusion_models'}|${m.name}`)
if (!a?.arch) continue
if (a.arch === 'vae' || a.arch === 'text_encoder') { drop.add(m); continue }
const type = SNIFF_TYPES[a.arch]
if (type && type !== m.type && headerMayRetype(m.type, type)) {
log.info('comfyui.header_sniff_retyped', { name: m.name, from: m.type, to: type })
m.type = type
}
// An H3 video file keeps the answer it always had: no parts.
if (m.type === 'minimaxh3') continue
m.parts = { textEncoder: !!a.hasTextEncoder, vae: !!a.hasVae }
}
if (drop.size > 0) {
const kept = models.filter((m) => !drop.has(m))
models.splice(0, models.length, ...kept)
}
}
async function mainModelLane(
keep: (type: ModelType) => boolean,
hidePartialDownloads: boolean,
): Promise<ClassifiedModel[]> {
// GGUF quants are listed by ComfyUI-GGUF's own loader, NOT by UNETLoader
// (which only enumerates .safetensors/.sft). Leaving them out meant a user
// could install a GGUF bundle straight from our own Model Manager and then be
// told "No image model installed" by the image tool. Empty when the pack is
// absent, so this is free for everyone else.
const [checkpoints, diffModels, ggufModels] = await Promise.all([
getCheckpoints(),
getDiffusionModels(),
getGgufUnetModels(),
])
const unets = [...new Set([...diffModels, ...ggufModels])]
const complete = hidePartialDownloads
? await filterPartialFiles([...checkpoints, ...unets])
: null
const result: ClassifiedModel[] = []
const candidates: ClassifiedModel[] = []
for (const name of checkpoints) {
if (complete && !complete.has(name)) continue
if (isStrayAddonFile(name)) continue
candidates.push({ name, type: classifyModel(name), source: 'checkpoint' })
}
// The picker offers a name once (Discord #bug-reports 30.10.2026: Edit listed
// "krea2TurboOfficialComfy krea2TurboInt8" three times). A file that sits in
// checkpoints/ and in diffusion_models/ (two copies, or one folder that
// extra_model_paths.yaml names for both) came back from both loaders. Every
// run looks a name up with `find`, which takes the checkpoint entry, so
// that is the one kept. The inventory lanes (hidePartialDownloads false) are
// left as they were.
const listed = new Set(hidePartialDownloads ? candidates.map((m) => m.name) : [])
for (const name of unets) {
if (complete && !complete.has(name)) continue
if (isStrayAddonFile(name)) continue
if (listed.has(name)) continue
// The 3D model sits in diffusion_models and its name places it in no
// family, so it would come back 'unknown' and be offered as an image
// model. The pickers leave it out; the inventory (hidePartialDownloads
// false) keeps it, so it can still be seen and deleted.
if (hidePartialDownloads && isThreeDModelFile(name)) continue
candidates.push({ name, type: classifyModel(name), source: 'diffusion_model' })
}
await applyHeaderSniff(candidates)
// One predicate for both folders. isImageModelType lets 'unknown' through,
// so a file neither the name nor the header can place is still offered,
// while the video types (SVD) and the lane architectures (ACE audio, Wan
// S2V/Animate/VACE) stay in their own pickers. The old branch renamed
// anything unmatched to sdxl instead of skipping it, which put an ACE-Step
// music checkpoint at the top of the image picker on a real box.
for (const m of candidates) {
if (keep(m.type)) result.push(m)
}
return result
}
/** The Create image picker and model-pick: main models that are usable. */
export async function getImageModels(): Promise<ClassifiedModel[]> {
return mainModelLane(isImageModelType, true)
}
/** The Create video picker and detectVideoBackend: same deal one lane over.
* Our own catalogue ships Wan video models as GGUF quants, and UNETLoader does
* not list those, so downloading one from the Model Manager used to leave the
* video tool insisting nothing was installed. */
export async function getVideoModels(): Promise<ClassifiedModel[]> {
return mainModelLane(isVideoModelType, true)
}
/** The main image folders for the INVENTORY surfaces: everything on the disk,
* no catalogue-size verdict. See mainModelLane for why the switch exists. */
export async function getInstalledMainImageModels(): Promise<ClassifiedModel[]> {
return mainModelLane(isImageModelType, false)
}
/** What the video INVENTORY counts: every video architecture, including the
* three Wan lanes that isVideoModelType leaves out so the plain Video picker
* never offers them (S2V for Talking Character, Animate and VACE for Motion
* Control). The picker rule is the wrong rule for "what is on the disk".
*
* Discord, thread "I can't launch Wan2.2" (15.10.2026): the catalogue's
* Wan2.2-Animate-14B-Q4_K_M.gguf card said Installed and the Installed tab
* did not list it, because this inventory borrowed the picker rule. Renamed
* to Wan2.1.gguf it showed up (plain Wan class), and Create then ran an
* Animate model through the plain Wan graph. */
export function isInstalledVideoType(type: ModelType): boolean {
return isVideoModelType(type) || type === 'wans2v' || type === 'wananimate' || type === 'wanvace'
}
/** The main video folders for the INVENTORY surfaces. Video twin of
* getInstalledMainImageModels. */
export async function getInstalledMainVideoModels(): Promise<ClassifiedModel[]> {
return mainModelLane(isInstalledVideoType, false)
}
/** The AnimateDiff motion modules, as classified models. (getMotionModels,
* without the prefix, is the Wan Animate/VACE lane and a different thing.)
*
* Kept separate from getVideoModels on purpose: the Create video picker asks
* that one for a MAIN model, and a motion module is never that. It is half of
* a pair (SD checkpoint + motion module) that the animatediff strategy puts
* together itself via findAnimateDiffModel. */
export async function getAnimateDiffMotionModels(): Promise<ClassifiedModel[]> {
const names = await getAnimateDiffModels()
return names.map((name) => ({ name, type: 'animatediff' as ModelType, source: 'motion_module' as const }))
}
/** One lane of the inventory, read on its own. A lane that fails costs itself
* and one log line, never the lanes beside it.
*
* Counter-check on the Windows box, 2026-08-29: the AnimateDiff lane threw
* ("(intermediate value).map is not a function", because that node answers in
* the newer COMBO schema) and took the ENTIRE video discovery with it. The
* Models page then showed a Video tab with no number, Installed 0 and "No
* video models installed" while three cards correctly said Installed, and the
* whole thing was a warn line nobody saw. The reader below is fixed at the
* root, but a single lane must never again be able to empty the page. */
async function inventoryLane(
lane: string,
read: () => Promise<ClassifiedModel[]>,
): Promise<ClassifiedModel[]> {
try {
return await read()
} catch (err) {
log.warn('comfyui.inventory_lane_failed', { lane, err })
return []
}
}
/** Everything installed in the video lane, for the INVENTORY surfaces: the
* Models rail counter and the Installed tab.
*
* Counter-check on the Windows box, 2026-08-29: two AnimateDiff bundles
* installed cleanly, both cards read Installed, and the rail counter and the
* Installed list knew neither of them. The cards check their own files, the
* counter read the four ComfyUI\models loaders, and AnimateDiff keeps its
* motion modules under custom_nodes. Same bug shape as GH #113: card, counter
* and list answering from different readers.
*
* Two additions over getVideoModels, both of them things ComfyUI really can
* serve as video right now:
* - the motion modules themselves, wherever the pack keeps them
* - the SD checkpoints the catalogue's AnimateDiff bundles ship, but ONLY
* while motion modules exist, which is the same condition selectStrategy uses before it
* routes a video request onto the animatediff pipeline. That is the second
* file of both AnimateDiff bundles (Realistic Vision), which used to be
* counted under Image alone, so a video bundle showed up half in the wrong
* lane and half nowhere. It stays in the Image count too, because it is
* genuinely an image checkpoint as well.
*
* Not used by detectVideoBackend, the Create picker or model-pick: those ask
* for a main model and getVideoModels still answers exactly what it did. */
export async function getInstalledVideoModels(): Promise<ClassifiedModel[]> {
const [videoModels, motionModels] = await Promise.all([
inventoryLane('video', getInstalledMainVideoModels),
inventoryLane('animatediff', getAnimateDiffMotionModels),
])
const out: ClassifiedModel[] = [...videoModels, ...motionModels]
if (motionModels.length > 0) {
// Only the checkpoints a video bundle of the catalogue ships, which is
// what "the second file of both AnimateDiff bundles" always meant. This
// used to take EVERY image checkpoint once a motion module was on disk,
// so sd_turbo (an image model no motion module here can drive) stood in
// the Video list of the box on 03.10.2026.
const bundled = new Set(getVideoBundles().flatMap((b) => b.files)
.filter((f) => f.subfolder === 'checkpoints' && f.filename)
.map((f) => f.filename!.toLowerCase()))
const imageModels = await inventoryLane('image', getInstalledMainImageModels)
for (const m of imageModels) {
if (m.source !== 'checkpoint') continue
if (!bundled.has((m.name.split(/[\\/]/).pop() ?? m.name).toLowerCase())) continue
if (out.some((x) => x.name === m.name)) continue
out.push(m)
}
}
return out
}
/** Extensions a model file on the disk actually carries. Everything ComfyUI
* enumerates by filename ends in one of these. */
const MODEL_FILE_EXTENSIONS = [
'.safetensors', '.sft', '.ckpt', '.pt', '.pth', '.bin', '.gguf', '.onnx', '.pkl',
]
/**
* Is this enum entry a file on the disk at all.
*
* R5 re-measure, 2026-08-30: the Installed list under Image carried an entry
* called `pixel_space`, type safetensors, no size. A search over the whole C:
* drive found no such file, because there is none. `pixel_space` is ComfyUI's
* built-in pixel-space pseudo VAE, and VAELoader offers it in the same enum as
* the real files, exactly like the built-in taesd family beside it. The app
* read that enum as a list of installed files and invented a model the user
* neither downloaded nor can delete.
*
* The rule is the general one rather than a name list: an inventory entry
* claims a file occupies the disk, and a name with no file extension is not a
* file. That covers pixel_space, taesd, taesdxl, taesd3, taef1 and whatever
* ComfyUI builds in next, without this having to be told about it.
*/
export function isInstalledModelFile(name: string): boolean {
const lower = name.toLowerCase()
return MODEL_FILE_EXTENSIONS.some((ext) => lower.endsWith(ext))
}
/** One addon folder, as classified models. These files are not a model on
* their own, which is why no picker offers them and why every inventory
* surface used to skip them. They still occupy the disk and the user still
* has to be able to see and remove them.
*
* No partial filter here any more, and that is the second half of the R5
* re-measure (2026-08-30). `text_encoders\llava_llama3_fp8_scaled.safetensors`
* weighs 2.4 GB on the box and appeared nowhere, while its three folder
* neighbours appeared. The catalogue ships that name at 8.5 GB, the disk
* probe called 2.4 GB too small, and filterPartialFiles dropped it. But a
* catalogue size is a claim about the file WE ship, never about the file the
* user has, and this list answers one question only: what is lying on the
* disk. ComfyUI enumerates the file, so ComfyUI can load it; hiding it left
* 2.4 GB the user could not see and could not delete. The bundle cards and
* the Create pickers keep their partial filter, because "is this usable" is
* their question and it is a different one. */
async function addonLane(
read: () => Promise<string[]>,
source: AddonSource,
): Promise<ClassifiedModel[]> {
const names = await read()
return names
.filter(isInstalledModelFile)
.map((name) => ({ name, type: classifyModel(name), source }))
}
/**
* The embeddings folder, as real filenames.
*
* ComfyUI has no loader node over embeddings: they are served by the
* /embeddings route, which strips the extension off every name. A stripped
* name is not a file, so it fails isInstalledModelFile, cannot be measured and
* cannot be deleted. So the extension is put back by asking the disk which of
* the candidates exists, in ONE batched probe for the whole folder.
*
* Best effort: a probe that fails costs the embeddings lane and nothing else,
* which is the same deal every other lane gets.
*/
async function embeddingLane(): Promise<ClassifiedModel[]> {
const bases = await getEmbeddingNames()
if (bases.length === 0) return []
// A name that already carries an extension needs no guessing.
const ready = bases.filter(isInstalledModelFile)
const stripped = bases.filter((n) => !isInstalledModelFile(n))
const found = new Set<string>(ready)
if (stripped.length > 0) {
try {
const files = stripped.flatMap((base) =>
MODEL_FILE_EXTENSIONS.map((ext) => ({
subfolder: 'embeddings', filename: `${base}${ext}`, expectedBytes: 0,
})),
)
const results: Array<{ filename: string; exists?: boolean }> =
await backendCall('check_model_sizes', { files })
const onDisk = new Set(results.filter((r) => r.exists).map((r) => r.filename))
for (const base of stripped) {
const hit = MODEL_FILE_EXTENSIONS.map((ext) => `${base}${ext}`).find((f) => onDisk.has(f))
if (hit) found.add(hit)
}
} catch (err) {
log.warn('comfyui.embedding_filename_probe_failed', { err })
}
}
return [...found].map((name) => ({ name, type: classifyModel(name), source: 'embedding' as const }))
}
/**
* Which loader answers for which ComfyUI model folder. ONE table, because the
* folder list was spread over the readers that happened to need a folder, and
* a folder nobody happened to need was simply invisible: five of them at the
* R5 re-measure on 2026-08-30 (clip_vision, controlnet, upscale_models,
* embeddings, style_models), holding among other things an 817 MB CLIP-Vision
* encoder that no surface in the app had ever named.
*
* The main-model folders (checkpoints, diffusion_models, and the GGUF unets
* beside them) are not here: those are read by getImageModels, which the
* pickers share. Everything else a user drops into ComfyUI\models is.
*/
const INSTALLED_ADDON_LANES: Array<{ source: AddonSource; read: () => Promise<ClassifiedModel[]> }> = [
{ source: 'lora', read: () => addonLane(getLoraModels, 'lora') },
{ source: 'vae', read: () => addonLane(getVAEModels, 'vae') },
{ source: 'text_encoder', read: () => addonLane(getCLIPModels, 'text_encoder') },
{ source: 'clip_vision', read: () => addonLane(getCLIPVisionModels, 'clip_vision') },
{ source: 'controlnet', read: () => addonLane(getControlNetModels, 'controlnet') },
{ source: 'upscale_model', read: () => addonLane(getUpscaleModels, 'upscale_model') },
{ source: 'style_model', read: () => addonLane(getStyleModels, 'style_model') },
{ source: 'embedding', read: embeddingLane },
]
/** Every ComfyUI\models folder the inventory reads, by its subfolder name.
* Exported so a test can hold it against ComfyUI's own folder truth instead
* of against the list that happens to be here. */
export const INSTALLED_ADDON_SUBFOLDERS: string[] =
INSTALLED_ADDON_LANES.map((lane) => subfolderForSource(lane.source))
/** Where the AnimateDiff-Evolved pack keeps its motion modules. Not under
* ComfyUI\models at all, which is exactly why the counter and the Installed
* list used to miss a fully installed AnimateDiff bundle while its card said
* Installed (counter-check on the Windows box, 2026-08-29). */
export const ANIMATEDIFF_SUBFOLDER = 'custom_nodes/ComfyUI-AnimateDiff-Evolved/models'
/**
* THE table: every folder the Get button writes into, and the loader that
* lists it back.
*
* A user (Discord help-chat, 2026-09-02): FramePack F1 and Wan 2.1
* installed through the Get button and appeared in no picker. The folder half
* of that is fixed where a file is written (src-tauri/.../comfy_folders.rs,
* which asks the running ComfyUI instead of guessing). This is the other half:
* until now the folders the catalog WRITES to and the folders the app READS
* back were two hand-written lists in two files, and they had already drifted.
*
* Two Get targets were in no reader at all:
* * `clip_vision`, FramePack F1's 900 MB SigCLIP encoder.
* * `audio_encoders`, the Wav2Vec2 encoder both Talking Character bundles
* need, added with the 2.5.8 lanes and never read back anywhere.
* A file in either could not be confirmed after its download, and the bundle
* card's fallback could never call those bundles installed, because it looked
* up a folder nothing had filled.
*
* The guard against the next drift is a test, not a promise:
* `src/api/__tests__/get-target-is-a-folder-we-read.test.ts` walks every file
* of every bundle in the catalog and fails on a subfolder that is not in here.
*/
export const COMFY_MODEL_FOLDERS: Array<{
subfolder: string
/** The files ComfyUI lists in that folder, or `null` when the loader that
* lists it is not registered in this ComfyUI at all. See
* `nodeOptionsOrNull` for why the two are not the same answer. */
read: () => Promise<string[] | null>
}> = [
// The two main-model loaders are the strict ones: their absence does not mean
// an empty folder, it means ComfyUI is not answering, and every caller here
// already treats that as "no verdict about anything".
{ subfolder: 'checkpoints', read: getCheckpoints },
// Two loaders, one folder: UNETLoader enumerates .safetensors and .sft,
// ComfyUI-GGUF's own loader the .gguf quants beside them. Our own catalog
// ships video models both ways, and the pack being absent is normal.
{
subfolder: 'diffusion_models',
read: async () => {
const [unets, ggufs] = await Promise.all([
getDiffusionModels(),
nodeOptionsOrNull('UnetLoaderGGUF', 'unet_name'),
])
return [...unets, ...(ggufs ?? [])]
},
},
{ subfolder: 'vae', read: () => nodeOptionsOrNull('VAELoader', 'vae_name') },
{ subfolder: 'text_encoders', read: () => nodeOptionsOrNull('CLIPLoader', 'clip_name') },
{ subfolder: 'clip_vision', read: () => nodeOptionsOrNull('CLIPVisionLoader', 'clip_name') },
{ subfolder: 'audio_encoders', read: () => nodeOptionsOrNull('AudioEncoderLoader', 'audio_encoder_name') },
{ subfolder: 'loras', read: () => nodeOptionsOrNull('LoraLoader', 'lora_name') },
{ subfolder: 'controlnet', read: () => nodeOptionsOrNull('ControlNetLoader', 'control_net_name') },
{ subfolder: 'upscale_models', read: () => nodeOptionsOrNull('UpscaleModelLoader', 'model_name') },
// The x2 latent upscaler LTX 2.5's second pass needs (a different folder
// and a different loader from the image upscalers above).
{ subfolder: 'latent_upscale_models', read: () => nodeOptionsOrNull('LatentUpscaleModelLoader', 'model_name') },
{ subfolder: 'style_models', read: () => nodeOptionsOrNull('StyleModelLoader', 'style_model_name') },
// The cutout model of local 3D (BiRefNet). LoadBackgroundRemovalModel is a
// core node of ComfyUI v0.42.4 (comfy_extras/nodes_bg_removal.py) and lists
// models/background_removal under `bg_removal_name`.
{ subfolder: 'background_removal', read: () => nodeOptionsOrNull('LoadBackgroundRemovalModel', 'bg_removal_name') },
{ subfolder: ANIMATEDIFF_SUBFOLDER, read: () => nodeOptionsOrNull('ADE_LoadAnimateDiffModel', 'model_name') },
]
/** Subfolders whose contents ComfyUI enumerates, which is the same thing as
* "folders the visibility check can reason about". The table, as a set. */
export const ENUM_SUBFOLDERS = new Set(COMFY_MODEL_FOLDERS.map((f) => f.subfolder))
/** What each folder of the table holds right now, by subfolder. One round trip
* per folder, asked once and used by every caller that needs more than one.
*
* A folder whose loader is not registered here is LEFT OUT rather than
* reported empty. The keys are therefore also the answer to "which folders can
* be judged at all", which is what `judgeableFolders` hands to the callers
* that decide whether a file may be called invisible. */
export async function readComfyFolderLists(): Promise<Record<string, string[]>> {
const entries = await Promise.all(
COMFY_MODEL_FOLDERS.map(async (f) => [f.subfolder, await f.read()] as const),
)
return Object.fromEntries(entries.filter((e): e is readonly [string, string[]] => e[1] !== null))
}
/** Everything installed in the image lane, for the INVENTORY surfaces: the
* Models rail counter and the Installed tab. The image twin of
* getInstalledVideoModels, and the same bug shape one folder further out.
*
* Counter-check on the Windows box, 2026-08-29: the cards for Pixel Art XL
* (163 MB in loras\) and SDXL VAE fp16-fix (319 MB in vae\) both read
* Installed, and neither file was in any Installed list or any counter.
* Beside them sat two more LoRAs, four text encoders and five more VAEs that
* no surface in the app had ever mentioned. The counter and the list read
* checkpoints\ and diffusion_models\ and nothing else, so the user could
* neither see what those files cost him nor delete one from the list.
*
* Not used by the Create picker or model-pick: those ask for a main model
* and getImageModels still answers exactly what it did. A VAE is never a
* main model, and this function is the only place that says otherwise. */
export async function getInstalledImageModels(): Promise<ClassifiedModel[]> {
const [imageModels, ...addons] = await Promise.all([
inventoryLane('image', getInstalledMainImageModels),
...INSTALLED_ADDON_LANES.map((lane) => inventoryLane(lane.source, lane.read)),
])
const out: ClassifiedModel[] = []
const seen = new Set<string>()
// First lane wins. A name that two loaders both list (a checkpoint ComfyUI
// also offers as a VAE) is one file on the disk and belongs in the list
// once, or the Installed count starts inventing entries.
for (const m of [imageModels, ...addons].flat()) {
if (seen.has(m.name)) continue
seen.add(m.name)
out.push(m)
}
return out
}
/** What each listed file weighs on the disk, by filename.
*
* The inventory used to hand every ComfyUI file a size of 0, which the card
* renders as no size at all. That was tolerable while the list held nothing
* but big checkpoints the user had just picked himself; it is not once the
* list is supposed to answer "what is all this costing me". Best effort
* throughout: a probe that fails costs the sizes, never the list. */
export async function readModelDiskSizes(models: ClassifiedModel[]): Promise<Map<string, number>> {
const out = new Map<string, number>()
if (models.length === 0) return out
try {
// expectedBytes 0 on purpose: this asks how big the file IS, and the
// partial-download verdict is filterPartialFiles' job, not this one's.
const files = models.map((m) => ({
subfolder: subfolderForSource(m.source),
filename: m.name,
expectedBytes: 0,
}))
const results: Array<{ filename: string; exists?: boolean; actualBytes?: number }> =
await backendCall('check_model_sizes', { files })
for (const r of results) {
if (r.exists && typeof r.actualBytes === 'number' && r.actualBytes > 0) {
out.set(r.filename, r.actualBytes)
}
}
} catch (err) {
log.warn('comfyui.disk_sizes_failed', { err })
}
return out
}
// ── 2.5.8 specialized local-lane model lists ─────────────────────────────────
// Each lane owns its picker: an ACE checkpoint in the Image list (or a 14B S2V
// in the Video list) would build a graph that ComfyUI rejects, so these
// architectures are excluded from isImage/isVideo above and surfaced here.
/** GGUF-quantized UNets (city96 ComfyUI-GGUF pack). Empty when the pack is not
* installed — callers merge these into their lane list and the builder swaps
* UNETLoader for UnetLoaderGGUF by extension. */
export async function getGgufUnetModels(): Promise<string[]> {
try {
return await fetchNodeOptions('UnetLoaderGGUF', 'unet_name')
} catch (err) {
log.warn('comfyui.fetch_gguf_failed', { err })
return []
}
}
/** The architectures the music lane runs. Both ship as all in one checkpoints. */
export const isMusicModelType = (type: ModelType): boolean => type === 'ace' || type === 'yue2'
/** Music lane: ACE-Step and YuE2 all-in-one checkpoints (model + text encoder + VAE). */
export async function getAudioModels(): Promise<ClassifiedModel[]> {
const checkpoints = await getCheckpoints()
const complete = await filterPartialFiles(checkpoints)
return checkpoints
.filter((name) => complete.has(name) && isMusicModelType(classifyModel(name)))
.map((name) => ({ name, type: classifyModel(name), source: 'checkpoint' as const }))
}
/** Talking-character lane: Wan 2.2 S2V UNets (safetensors via UNETLoader,
* .gguf via the GGUF pack when installed). */
export async function getLipsyncModels(): Promise<ClassifiedModel[]> {
const [diffModels, ggufModels] = await Promise.all([getDiffusionModels(), getGgufUnetModels()])
const complete = await filterPartialFiles(diffModels)
const fromUnet = diffModels
.filter((name) => complete.has(name) && classifyModel(name) === 'wans2v')
.map((name) => ({ name, type: 'wans2v' as ModelType, source: 'diffusion_model' as const }))
const fromGguf = ggufModels
.filter((name) => classifyModel(name) === 'wans2v')
.map((name) => ({ name, type: 'wans2v' as ModelType, source: 'diffusion_model' as const }))
return [...fromUnet, ...fromGguf]
}
/** One rule for the specialized-lane picker AND submit: a pick that is not on
* the lane's list (stale cross-lane selection, deleted file) resolves to the
* list's first entry — the same guard the cloud op picker got after the
* take-01 wrong-trainer incident. */
export function resolveLocalOpPick(picked: string, list: ClassifiedModel[]): string {
return list.some((m) => m.name === picked) ? picked : (list[0]?.name ?? '')
}
/** Motion-control lane: Wan 2.2 Animate UNets + Wan VACE UNets. */
export async function getMotionModels(): Promise<ClassifiedModel[]> {
const [diffModels, ggufModels] = await Promise.all([getDiffusionModels(), getGgufUnetModels()])
const complete = await filterPartialFiles(diffModels)
const wanted = (t: ModelType) => t === 'wananimate' || t === 'wanvace'
const fromUnet = diffModels
.filter((name) => complete.has(name) && wanted(classifyModel(name)))
.map((name) => ({ name, type: classifyModel(name), source: 'diffusion_model' as const }))
const fromGguf = ggufModels
.filter((name) => wanted(classifyModel(name)))
.map((name) => ({ name, type: classifyModel(name), source: 'diffusion_model' as const }))
return [...fromUnet, ...fromGguf]
}
// ─── Detect Video Backend (checks individual nodes + models — no full object_info fetch) ───
export async function detectVideoBackend(): Promise<VideoBackend> {
try {
// Check Wan/Hunyuan: need specific nodes AND actual video models
const [hasWanLatent, hasUNET, hasCLIP, hasVAE, videoModels] = await Promise.all([
nodeExists('EmptyHunyuanLatentVideo'),
nodeExists('UNETLoader'),
nodeExists('CLIPLoader'),
nodeExists('VAELoader'),
getVideoModels(),
])
if (hasWanLatent && hasUNET && hasCLIP && hasVAE && videoModels.length > 0) {
return 'wan'
}
// Check AnimateDiff: need custom extension nodes
const [hasADELoad, hasADESampling] = await Promise.all([
nodeExists('ADE_LoadAnimateDiffModel'),
nodeExists('ADE_UseEvolvedSampling'),
])
if (hasADELoad && hasADESampling) return 'animatediff'
} catch (err) {
log.warn('comfyui.detect_video_backend_failed', { err })
}
return 'none'
}
// ─── Auto-find matching VAE/CLIP for a model ───
/** HunyuanVideo 1.5 VAE (32-channel). FramePack and every other 1.0-era
* model must never be handed one. Matches `hunyuanvideo15_vae_fp16` as well
* as spaced-out spellings like `hunyuan_video_1.5_vae`. */
function isHunyuan15Vae(name: string): boolean {
return /hunyuan[._-]?video[._-]?1[._-]?5/.test(name.toLowerCase())
}
/** Qwen-Image 2.1's own autoencoder (64 channels, RGBA, 16x compression).
* Krea 2's companion `qwen_image_vae.safetensors` is the older 16-channel
* one and shares the stem, so both resolvers have to tell them apart by the
* version tag. Same shape of mistake the Wan 2.1 / Wan 2.2 VAE branch below
* already guards against: the wrong file loads and the decode fails on the
* channel count. */
function isQwenImage21Vae(name: string): boolean {
return /qwen[._-]?image[._-]?2[._-]?1/.test(name.toLowerCase())
}
/** Qwen-Image 2.1's text encoder tier (Qwen3-VL 8B), official or with the
* refusals removed. Krea 2 uses the 4B sibling under a near-identical name,
* and the two have different embedding dimensions. */
function isQwen3vl8b(name: string): boolean {
return qwenEncoderFile(name) !== null
}
/** MiniMax H3's own encoder (qwen3vl_32b_minimax_h3_*). It is a Qwen3-VL file
* too, so every family that matches its encoder on a generic qwen / qwen3vl
* stem has to step around it, or a box holding both loads a 32B encoder
* into a 4B slot. */
function isMinimaxEncoder(name: string): boolean {
return name.toLowerCase().includes('minimax')
}
/** An empty ComfyUI list still names the file this family needs, so Create
* can offer it as a download instead of "a VAE for your model type". */
function nothingInstalled(kind: 'VAE' | 'text encoder', specs: (ComponentSpec | undefined)[]): Error {
const files = specs.filter((x): x is ComponentSpec => !!x).map((x) => `"${x.downloadFilename}"`)
if (files.length === 0) return new Error(`No ${kind} models found. Download a ${kind} for your model type from the Model Manager.`)
return new Error(`No ${kind} models found. Download ${files.join(' and ')} from the Model Manager.`)
}
export async function findMatchingVAE(modelType: ModelType): Promise<string> {
const vaes = await getVAEModels()
if (vaes.length === 0) throw nothingInstalled('VAE', [COMPONENT_REGISTRY[modelType]?.vae])
const lower = (s: string) => s.toLowerCase()
if (modelType === 'zimage') {
// Z-Image uses ae.safetensors (same as FLUX but prefer exact match)
const match = vaes.find(v => lower(v) === 'ae.safetensors')
|| vaes.find(v => lower(v).includes('ae'))
|| vaes.find(v => lower(v).includes('flux'))
if (match) return match
throw new Error(`No Z-Image VAE found. Download "ae.safetensors" from the Model Manager.`)
}
if (modelType === 'flux') {
// FLUX.1 uses the 16-channel ae.safetensors autoencoder, NOT the FLUX 2 VAE.
const match = vaes.find(v => lower(v) === 'ae.safetensors')
|| vaes.find(v => lower(v).includes('ae') && !lower(v).includes('flux2'))
|| vaes.find(v => lower(v).includes('flux') && !lower(v).includes('flux2'))
if (match) return match
throw new Error(`No FLUX.1 VAE found. Download "ae.safetensors" from the Model Manager.`)
}
if (modelType === 'flux2' || modelType === 'ernie_image') {
const match = vaes.find(v => lower(v).includes('flux2'))
|| vaes.find(v => lower(v).includes('flux'))
|| vaes.find(v => lower(v).includes('ae'))
if (match) return match
throw new Error(`No FLUX 2 VAE found. Download "flux2-vae.safetensors" from the Model Manager.`)
}
if (modelType === 'qwenimage') {
// Qwen-Image 2.1 ships its own autoencoder. Pinned by the version tag so a
// box that also carries Krea 2's older qwen_image_vae cannot hand that one
// over: it has 16 channels where this model wants 64.
const match = vaes.find(v => lower(v) === 'qwen_image_2.1_vae_bf16.safetensors')
|| vaes.find(v => isQwenImage21Vae(v))
if (match) return match
throw new Error(`No Qwen-Image 2.1 VAE found. Download "qwen_image_2.1_vae_bf16.safetensors" from the Model Manager.`)
}
if (modelType === 'krea2') {
// Krea 2's companion VAE is not standardized across CivitAI finetunes
// (GH #136 saw both qwen_image_vae and wan_2.1_vae). Try a Krea-named
// file first, then the two variants confirmed by the issue reporter.
// The qwen_image hit excludes the Qwen-Image 2.1 autoencoder: it carries
// the same stem, sorts next to the file this branch wants, and would
// decode a Krea 2 latent with the wrong channel count.
const match = vaes.find(v => lower(v).includes('krea'))
|| vaes.find(v => lower(v).includes('qwen_image') && !isQwenImage21Vae(v))
|| vaes.find(v => /wan[._]?2[._]?1/.test(lower(v)))
if (match) return match
throw new Error(`No Krea 2 VAE found. Download "qwen_image_vae.safetensors" (or "wan_2.1_vae.safetensors", depending on the checkpoint) from the Model Manager.`)
}
if (modelType === 'hunyuan') {
// HunyuanVideo has its own VAE — prefer it, fall back to Wan VAE
const match = vaes.find(v => lower(v).includes('hunyuanvideo'))
|| vaes.find(v => lower(v).includes('hunyuan'))
|| vaes.find(v => lower(v).includes('wan'))
if (match) return match
throw new Error(`No HunyuanVideo VAE found. Download "hunyuanvideo15_vae_fp16.safetensors" from the Model Manager.`)
}
if (modelType === 'wan') {
// Wan 2.1 latents are 16-channel; the Wan 2.2 VAE is 48-channel — decoding
// 2.1 output with it fails ("expected input to have 48 channels, but got
// 16"). Live regression 2026-06-11: right after the Wan 2.2 bundle install,
// wan2.2_vae sorted BEFORE wan_2.1_vae in the enum and the first
// .includes('wan') hit broke every Wan 2.1 generation. Prefer the 2.1 file
// explicitly and never fall into a 2.2 one.
const isWan22Vae = (v: string) => /wan[._]?2[._]?2/.test(lower(v))
// Same reason the HunyuanVideo 1.5 VAE is excluded here: it is 32-channel,
// so the last-resort hunyuan fallback would trade a missing-file message
// for the tensor crash FramePack was dying with (D#104).
const match = vaes.find(v => /wan[._]?2[._]?1/.test(lower(v)))
|| vaes.find(v => lower(v).includes('wan') && !isWan22Vae(v))
|| vaes.find(v => lower(v).includes('hunyuan') && !isHunyuan15Vae(v))
if (match) return match
throw new Error(`No Wan VAE found. Download "wan_2.1_vae.safetensors" from the Model Manager.`)
}
if (modelType === 'wan22') {
// Defense in depth — the wan22 builder pins its VAE by name, but if this
// resolver is ever hit, ONLY the 2.2 VAE is valid (48-channel latents).
const match = vaes.find(v => /wan[._]?2[._]?2/.test(lower(v)))
if (match) return match
throw new Error(`No Wan 2.2 VAE found. Download "wan2.2_vae.safetensors" from the Model Manager.`)
}
if (modelType === 'ltx') {
const match = vaes.find(v => lower(v).includes('ltx') && !isLtx25File(v))
|| vaes.find(v => lower(v).includes('ltx'))
if (match) return match
return vaes[0]
}
if (modelType === 'ltx25') {
// The VIDEO autoencoder. The audio one is a second file (findLtx25AudioVAE)
// and the "-conv" video variant is an alternative the template does not use.
const match = vaes.find(v => /ltx[._-]?2[._-]?5[._-]video[._-]vae/.test(lower(v)) && !lower(v).includes('conv'))
if (match) return match
throw new Error(`No LTX 2.5 video VAE found. Download "ltx-2.5-video-vae-bf16.safetensors" from the Model Manager.`)
}
if (modelType === 'minimaxh3') {
// The VIDEO autoencoder; the audio one is a second file of its own
// (findMiniMaxAudioVAE), and the two are not interchangeable.
const match = vaes.find(v => lower(v).includes('minimax_h3_video_vae'))
|| vaes.find(v => lower(v).includes('minimax') && lower(v).includes('video'))
if (match) return match
throw new Error(`No MiniMax H3 video VAE found. Download "minimax_h3_video_vae_int8_convrot.safetensors" from the Model Manager.`)
}
if (modelType === 'mochi') {
const match = vaes.find(v => lower(v).includes('mochi'))
if (match) return match
throw new Error(`No Mochi VAE found. Download "mochi_vae.safetensors" from the Model Manager.`)
}
if (modelType === 'cosmos') {
const match = vaes.find(v => lower(v).includes('cosmos'))
if (match) return match
throw new Error(`No Cosmos VAE found. Download "cosmos_cv8x8x8_1.0.safetensors" from the Model Manager.`)
}
if (modelType === 'cogvideo') {
const match = vaes.find(v => lower(v).includes('cogvideox') || lower(v).includes('cogvideo'))
if (match) return match
throw new Error(`No CogVideoX VAE found. Download "cogvideox_vae_bf16.safetensors" from the Model Manager.`)
}
if (modelType === 'framepack') {
// 16-channel latents (HunyuanVideo 1.0). The 1.5 VAE is 32-channel and
// crashes the sampler, so it is excluded rather than merely deprioritised:
// on a disk holding both, first-hit order decided which one a run got.
const match = vaes.find(v => lower(v).includes('hunyuan') && !isHunyuan15Vae(v))
|| vaes.find(v => lower(v).includes('wan'))
if (match) return match
throw new Error(`No FramePack VAE found. Download "hunyuan_video_vae_bf16.safetensors" from the Model Manager.`)
}
if (modelType === 'pyramidflow') {
const match = vaes.find(v => lower(v).includes('pyramid'))
if (match) return match
throw new Error(`No Pyramid Flow VAE found. Download from the Model Manager.`)
}
// SVD / Allegro use checkpoint-embedded VAE, SDXL/SD1.5 too — any VAE works as fallback
return vaes[0]
}
/**
* Resolve the FLUX v1 text-encoder PAIR for DualCLIPLoader (C2, a user
* follow-up): modern ComfyUI removed 'flux' from the single CLIPLoader's type
* enum, so FLUX v1 conditioning must come from DualCLIPLoader, which needs
* BOTH encoders — clip_name1 = T5-XXL, clip_name2 = CLIP-L. Throws the same
* actionable "download <file> from the Model Manager" errors as
* findMatchingCLIP so buildDynamicWorkflow surfaces a fix path per missing
* encoder instead of a raw ComfyUI rejection.
*/
export async function findFluxCLIPPair(): Promise<{ t5: string; clipL: string }> {
const clips = await getCLIPModels()
if (clips.length === 0) throw nothingInstalled('text encoder', [COMPONENT_REGISTRY.flux?.clip, COMPONENT_REGISTRY.flux?.clipSecondary])
const lower = (s: string) => s.toLowerCase()
const t5 = clips.find(c => lower(c).includes('t5') && !lower(c).includes('umt5') && !lower(c).includes('oldt5'))
const clipL = clips.find(c => lower(c).includes('clip_l'))
if (!t5) throw new Error(`No FLUX text encoder (T5) found. Download "t5xxl_fp8_e4m3fn.safetensors" from the Model Manager.`)
if (!clipL) throw new Error(`No FLUX CLIP-L text encoder found. Download "clip_l.safetensors" from the Model Manager.`)
return { t5, clipL }
}
/**
* K2 (review-create.md nachbessert, Punkt 2): FramePack's DualCLIPLoader
* (type "hunyuan_video") wrote `clip_l.safetensors` and
* `llava_llama3_fp8_scaled.safetensors` straight into the node, same
* hardcoded-literal failure class the rest of K2 already fixed for VAE/CLIP/
* audio_encoder/clip_vision in the other builders. Resolved now against the
* live CLIP enum, same shape as findFluxCLIPPair above, with the same
* actionable "download <file>" errors on a miss.
*/
export async function findFramePackCLIPPair(): Promise<{ clipL: string; llavaLlama3: string }> {
const clips = await getCLIPModels()
if (clips.length === 0) throw nothingInstalled('text encoder', [COMPONENT_REGISTRY.framepack?.clip, COMPONENT_REGISTRY.framepack?.clipSecondary])
const lower = (s: string) => s.toLowerCase()
const clipL = clips.find(c => lower(c).includes('clip_l'))
const llavaLlama3 = clips.find(c => lower(c).includes('llava'))
if (!clipL) throw new Error(`No FramePack CLIP-L text encoder found. Download "clip_l.safetensors" from the Model Manager.`)
if (!llavaLlama3) throw new Error(`No FramePack llava_llama3 text encoder found. Download "llava_llama3_fp8_scaled.safetensors" from the Model Manager.`)
return { clipL, llavaLlama3 }
}
/** A file that says it is an LTX 2.5 one (ltx-2.5-..., gemma4-...-ltx-2.5-...). */
export function isLtx25File(name: string): boolean {
return /ltx[._\- ]?2[._\- ]?5/.test(name.toLowerCase())
}
/** The sound autoencoder LTX 2.5 decodes its audio with. A second file next to
* the video VAE, and the two are not interchangeable. */
export async function findLtx25AudioVAE(): Promise<string> {
const vaes = await getVAEModels()
const match = vaes.find(v => isLtx25File(v) && v.toLowerCase().includes('audio'))
if (match) return match
throw new Error(`No LTX 2.5 audio VAE found. Download "ltx-2.5-audio-vae-bf16.safetensors" from the Model Manager.`)
}
/** MiniMax H3's audio autoencoder. The model writes picture and sound into
* one latent and decodes the sound half with this file. */
export async function findMiniMaxAudioVAE(): Promise<string> {
const vaes = await getVAEModels()
const match = vaes.find(v => v.toLowerCase().includes('minimax_h3_audio_vae'))
|| vaes.find(v => v.toLowerCase().includes('minimax') && v.toLowerCase().includes('audio'))
if (match) return match
throw new Error(`No MiniMax H3 audio VAE found. Download "minimax_h3_audio_vae_fp32.safetensors" from the Model Manager.`)
}
/**
* Pick the right text encoder for a model.
*
* @param modelType — ModelType from `classifyModel`.
* @param activeModelName — optional filename of the UNet/checkpoint the
* user selected. Enables quantisation-aware pairing: e.g. fp4 FLUX 2
* models get the fp4-matched Qwen encoder, fp8/bf16 FLUX 2 models get
* the full-precision Qwen encoder. When omitted (legacy callers), we
* fall back to the full-precision variant, which is what most users
* want.
* @param qwenTextEncoder Qwen-Image 2.1 only: the edition the user picked in
* the advanced settings. Omitted, the official one goes first.
*/
export async function findMatchingCLIP(modelType: ModelType, activeModelName?: string, qwenTextEncoder?: QwenEncoderChoice): Promise<string> {
// The Qwen-Image 2.1 prompt enhancers sit in the same folder and carry
// "qwen" in their names, but they are text models, not encoders. Without
// this they answer the loose "qwen" searches below (HunyuanVideo, FramePack,
// FLUX 2) before the real encoder does.
const clips = (await getCLIPModels()).filter((c) => !isQwenEnhancerFile(c))
if (clips.length === 0) throw nothingInstalled('text encoder', [COMPONENT_REGISTRY[modelType]?.clip])
const lower = (s: string) => s.toLowerCase()
const modelLc = activeModelName ? lower(activeModelName) : ''
const modelIsFp4 = /fp4|nf4/.test(modelLc)
if (modelType === 'zimage') {
// Z-Image uses qwen_3_4b.safetensors (NOT the fp4_flux2 variant — different embedding dimensions!)
const match = clips.find(c => lower(c) === 'qwen_3_4b.safetensors')
|| clips.find(c => lower(c).includes('qwen_3_4b') && !lower(c).includes('fp4') && !lower(c).includes('flux2'))
|| clips.find(c => lower(c).includes('qwen3') && !lower(c).includes('fp4'))
if (match) return match
throw new Error(`No Z-Image text encoder found. Download "qwen_3_4b.safetensors" from the Model Manager.`)
}
if (modelType === 'flux2') {
// FLUX 2 uses Qwen 3 4B (NOT T5). The encoder file comes in two
// quantisation tiers that ARE NOT interchangeable:
// - `qwen_3_4b.safetensors` → normal / bf16 / fp8 models
// - `qwen_3_4b_fp4_flux2.safetensors` → fp4 / nf4 quantised models
// Using the wrong one can work (same embedding dim) but noticeably
// degrades prompt adherence, so we pair them by inspecting the
// filename of the active UNet (see `modelIsFp4` above). Fallback
// order ensures we never hard-fail when the "ideal" encoder isn't
// installed: we try the paired one first, then the other.
const qwenFp4 = clips.find(c => lower(c).includes('qwen') && (lower(c).includes('fp4') || lower(c).includes('nf4')) && !lower(c).includes('qwen_2.5_vl') && !isMinimaxEncoder(c))
const qwenFull = clips.find(c => lower(c).includes('qwen_3_4b') && !lower(c).includes('fp4') && !lower(c).includes('nf4') && !lower(c).includes('vl'))
const qwenAny = clips.find(c => lower(c).includes('qwen') && !lower(c).includes('qwen_2.5_vl') && !isMinimaxEncoder(c))
const mistral = clips.find(c => lower(c).includes('mistral'))
const match = modelIsFp4
? (qwenFp4 || qwenFull || qwenAny || mistral)
: (qwenFull || qwenAny || qwenFp4 || mistral)
if (match) return match
const wanted = modelIsFp4 ? 'qwen_3_4b_fp4_flux2.safetensors (fp4 FLUX 2)' : 'qwen_3_4b.safetensors (fp8/bf16 FLUX 2)'
throw new Error(`No FLUX 2 text encoder found. Download "${wanted}" from the Model Manager.`)
}
if (modelType === 'ernie_image') {
// ERNIE-Image uses its own prompt enhancer text encoder
const match = clips.find(c => lower(c).includes('ernie-image-prompt-enhancer') || lower(c).includes('ernie'))
if (match) return match
throw new Error(`No ERNIE-Image text encoder found. Download "ernie-image-prompt-enhancer.safetensors" from the Model Manager.`)
}
if (modelType === 'qwenimage') {
// Qwen-Image 2.1 uses Qwen3-VL 8B (2.0 and older used Qwen2.5-VL). Pinned
// to the 8B tier with no fallback: Krea 2's 4B sibling sits in the same
// folder under a near-identical name and has different embedding
// dimensions, so a fallback would load silently and encode nonsense.
// Two editions can sit side by side, the official one and the one
// without refusals; the advanced settings say which one reads the prompt.
const match = pickQwenEncoder(clips, qwenTextEncoder)
if (match) return match.file
throw new Error(`No Qwen-Image 2.1 text encoder found. Download "qwen3vl_8b_int8_convrot.safetensors" from the Model Manager.`)
}
if (modelType === 'krea2') {
// Krea 2 uses Qwen3-VL 4B, shipped under different quant-tier filenames
// by different finetune authors (GH #136: qwen3vl_4b_int8_convrot vs
// qwen3vl_4b_fp8_scaled), so match on the qwen3vl family, not one filename.
// The 8B file is excluded throughout: it belongs to Qwen-Image 2.1, and
// since that bundle landed in the Model Manager a box can hold both.
const match = clips.find(c => /qwen3[._-]?vl[._-]?4b/.test(lower(c)))
|| clips.find(c => (lower(c).includes('qwen3vl') || lower(c).includes('qwen3_vl')) && !isQwen3vl8b(c) && !isMinimaxEncoder(c))
|| clips.find(c => lower(c).includes('qwen') && lower(c).includes('vl') && !isQwen3vl8b(c) && !isMinimaxEncoder(c))
if (match) return match
throw new Error(`No Krea 2 text encoder found. Download "qwen3vl_4b_fp8_scaled.safetensors" from the Model Manager.`)
}
if (modelType === 'flux') {
const match = clips.find(c => lower(c).includes('t5') && !lower(c).includes('umt5'))
|| clips.find(c => lower(c).includes('clip_l'))
if (match) return match
throw new Error(`No FLUX text encoder (T5) found. Download "t5xxl_fp8_e4m3fn.safetensors" from the Model Manager.`)
}
if (modelType === 'hunyuan') {
// HunyuanVideo 1.5 uses Qwen 2.5 VL, older versions use llava_llama3
const match = clips.find(c => lower(c).includes('qwen') && !isMinimaxEncoder(c))
|| clips.find(c => lower(c).includes('llava'))
|| clips.find(c => lower(c).includes('umt5'))
if (match) return match
throw new Error(`No HunyuanVideo text encoder found. Download "qwen_2.5_vl_7b_fp8_scaled.safetensors" from the Model Manager.`)
}
if (modelType === 'wan') {
const match = clips.find(c => lower(c).includes('umt5') || lower(c).includes('wan'))
|| clips.find(c => lower(c).includes('t5'))
if (match) return match
throw new Error(`No Wan text encoder found. Download "umt5_xxl_fp8_e4m3fn_scaled.safetensors" from the Model Manager.`)
}
if (modelType === 'ltx') {
// LTX 2.3 reads Gemma 3. The Gemma 4 encoders belong to LTX 2.5 and would
// be refused by a 2.3 graph.
const match = clips.find(c => lower(c).includes('gemma') && !lower(c).includes('gemma4'))
if (match) return match
throw new Error(`No LTX Video text encoder found. Download "gemma_3_12B_it_fp8_scaled.safetensors" from the Model Manager.`)
}
if (modelType === 'ltx25') {
// Lightricks' own Gemma 4 12B with the projection LTX 2.5 needs. A plain
// Gemma 4 file (no "ltx") is a different encoder and is not accepted.
const match = clips.find(c => lower(c).includes('gemma4') && isLtx25File(c))
if (match) return match
throw new Error(`No LTX 2.5 text encoder found. Download "gemma4-12b-with-proj-ltx-2.5-comfy-int8-convrot.safetensors" from the Model Manager.`)
}
if (modelType === 'minimaxh3') {
// Qwen3-VL 32B, tuned for H3 and shipped only under H3's own names. The
// nvfp4 tier is the one the official templates load (15.7 GB).
const match = clips.find(c => isMinimaxEncoder(c) && lower(c).includes('nvfp4'))
|| clips.find(c => isMinimaxEncoder(c))
if (match) return match
throw new Error(`No MiniMax H3 text encoder found. Download "qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors" from the Model Manager.`)
}
if (modelType === 'mochi') {
const match = clips.find(c => lower(c).includes('t5') && !lower(c).includes('umt5') && !lower(c).includes('oldt5'))
if (match) return match
throw new Error(`No Mochi text encoder found. Download "t5xxl_fp16.safetensors" from the Model Manager.`)
}
if (modelType === 'cosmos') {
// Cosmos uses oldt5, NOT regular t5xxl
const match = clips.find(c => lower(c).includes('oldt5'))
if (match) return match
throw new Error(`No Cosmos text encoder found. Download "oldt5_xxl_fp8_e4m3fn_scaled.safetensors" from the Model Manager.`)
}
if (modelType === 'cogvideo') {
const match = clips.find(c => lower(c).includes('t5') && !lower(c).includes('umt5') && !lower(c).includes('oldt5'))
if (match) return match
throw new Error(`No CogVideoX text encoder found. Download "t5xxl_fp16.safetensors" from the Model Manager.`)
}
if (modelType === 'framepack') {
const match = clips.find(c => lower(c).includes('llava') || (lower(c).includes('qwen') && !isMinimaxEncoder(c)))
|| clips.find(c => lower(c).includes('umt5'))
if (match) return match
throw new Error(`No FramePack text encoder found. Download "llava_llama3_fp8_scaled.safetensors" from the Model Manager.`)
}
// SDXL/SD1.5/SVD/Allegro/PyramidFlow checkpoints include CLIP — any works
return clips[0]
}
/**
* K2 (a user, Discord "HELP WITH MODELS"/help-18,
* 2026-09-15/17): the Talking Character (lipsync) and Motion (animate)
* builders hardcoded `audio_encoder_name: 'wav2vec2_large_english_fp16.
* safetensors'` straight into AudioEncoderLoader, never checked against
* ComfyUI's live enum. A box that doesn't have that exact file (a different
* quant, a subfolder, or simply nothing installed) submitted it verbatim and
* ComfyUI's /prompt validator rejected the node with "Value not in list",
* the same failure mode Bug C already fixed for CLIPLoader, just not carried
* over to the newer local lanes. Same no-silent-fallback rule as
* findMatchingVAE/findMatchingCLIP: resolve against the live list, throw an
* actionable "download <file>" message on a miss.
*/
export async function findMatchingAudioEncoder(): Promise<string> {
const encoders = await getAudioEncoderModels()
if (encoders.length === 0) {
throw new Error('No audio encoder models found. Download "wav2vec2_large_english_fp16.safetensors" from the Model Manager.')
}
const match = encoders.find((e) => e.toLowerCase().includes('wav2vec2'))
return match ?? encoders[0]
}
/**
* Same fix as findMatchingAudioEncoder, for CLIPVisionLoader. FramePack
* hardcoded `clip_name: 'sigclip_vision_patch14_384.safetensors'` unchecked;
* resolve against the live list instead.
*/
export async function findMatchingClipVision(): Promise<string> {
const models = await getCLIPVisionModels()
if (models.length === 0) {
throw new Error('No CLIP-Vision models found. Download "sigclip_vision_patch14_384.safetensors" from the Model Manager.')
}
const match = models.find((m) => m.toLowerCase().includes('sigclip'))
return match ?? models[0]
}
async function findAnimateDiffModel(): Promise<string> {
const models = await getAnimateDiffModels()
if (models.length === 0) throw new Error('No AnimateDiff motion models found. Install them via ComfyUI Manager.')
return models[0]
}
// ─── Workflow Submission ───
export async function submitWorkflow(
workflow: ComfyApiGraph,
clientId?: string,
opts: { previewMethod?: 'auto' | 'latent2rgb' | 'taesd' } = {},
): Promise<string> {
// 3.1.0 (C56): with "One model across two cards" on and a ComfyUI that
// sees both cards, the text encoders and the VAE go to the second card.
// Off, or anything missing: the workflow goes out unchanged.
const { withComfySplit } = await import('./comfy-split')
const placed = await withComfySplit(workflow)
// Every run its own output names (comfyui-graph tagOutputPrefixes).
const payload: Record<string, unknown> = { prompt: tagOutputPrefixes(placed, newRunTag()) }
if (clientId) payload.client_id = clientId
// B28: live previews for this prompt only. ComfyUI starts with previews off
// (--preview-method none) and takes a per-prompt override in extra_data
// since PR 11261 (2025-12-15, execution.py set_preview_method); an older
// one ignores the key and renders as before, without pictures.
if (opts.previewMethod) payload.extra_data = { preview_method: opts.previewMethod }
// Use localFetch (Rust proxy in Tauri, direct fetch in dev). The previous
// direct-only fetch broke for any ComfyUI not started by LU itself —
// `--enable-cors-header` is the LU spawn flag, but a user-run ComfyUI
// Portable / cu126 / AMD build doesn't pass it, so the browser blocks the
// POST during preflight and the only thing the user sees is the JS error
// "Failed to fetch". The proxy bypasses the SOP entirely (it's a Rust HTTP
// call, not a browser one). Bug: GH disc #35, Discord.
const url = comfyuiUrl('/prompt')
const res = await localFetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
// /prompt only validates + enqueues and returns the prompt_id immediately —
// it does NOT block on the render. Cap it so a wedged submit can't strand the
// VRAM hand-off (text model stays unloaded) for the 5-min proxy default.
timeoutMs: COMFY_SUBMIT_TIMEOUT_MS,
})
if (!res.ok) {
const rawText = await res.text().catch(() => '')
let errMsg = `HTTP ${res.status}`
try {
errMsg = describeComfyRejection(JSON.parse(rawText)) ?? errMsg
} catch {
if (rawText) errMsg = rawText.slice(0, 500)
}
log.error('comfyui.workflow_rejected', { errMsg, workflow: JSON.stringify(placed).slice(0, 2000) })
throw new Error(`ComfyUI rejected workflow: ${errMsg}`)
}
const data: unknown = await res.json()
const promptId = isRecord(data) ? asString(data.prompt_id) : undefined
// ComfyUI queues a prompt as soon as ONE output node passes validation and
// lists the failed ones in node_errors of a 200 answer (execution.py
// validate_prompt, server.py post_prompt). The run then ends without the
// video or image LU waits for, and all the user saw was "no output was
// produced" (GitHub #196). Such a half prompt is taken out of the queue
// and reported like a full rejection.
const nodeErrors = isRecord(data) ? data.node_errors : undefined
if (isRecord(nodeErrors) && Object.keys(nodeErrors).length > 0) {
if (promptId) await abandonPrompt(promptId)
const errMsg = describeComfyRejection(data) ?? 'some output nodes failed validation'
log.error('comfyui.workflow_rejected', { errMsg, partial: true, workflow: JSON.stringify(placed).slice(0, 2000) })
throw new Error(`ComfyUI rejected workflow: ${errMsg}`)
}
if (!promptId) throw new Error('ComfyUI accepted the workflow but returned no prompt_id.')
return promptId
}
/**
* ComfyUI's verdict on a prompt as one line, or null when it names nothing.
* Foreign JSON: `error` is a string on some versions and an `{ message }` on
* others, and `node_errors` is only present for a validation failure, so
* every read is narrowed.
*/
function describeComfyRejection(errData: unknown): string | null {
const parts: string[] = []
const rawErr = isRecord(errData) ? errData.error : undefined
const topLevel = asString(rawErr) ?? (isRecord(rawErr) ? asString(rawErr.message) : undefined)
if (topLevel) parts.push(topLevel)
const nodeErrors = isRecord(errData) ? errData.node_errors : undefined
if (isRecord(nodeErrors)) {
for (const [nodeId, data] of Object.entries(nodeErrors)) {
const errs = asRecordArray(isRecord(data) ? data.errors : undefined)
// "Value not in list" alone names no value; the details say which
// one ("ckpt_name: 'x.safetensors' not in [...]"). The list itself
// can be hundreds of file names, so it is cut off.
.map((e) => {
const message = asString(e.message) ?? ''
const details = asString(e.details)?.split(' not in [')[0].slice(0, 200)
return details && message ? `${message} (${details})` : message || details || ''
})
.filter(Boolean)
.join(', ') || 'unknown'
const cls = (isRecord(data) ? asString(data.class_type) : undefined) ?? '?'
parts.push(`Node ${nodeId} (${cls}): ${errs}`)
}
}
return parts.length > 0 ? parts.join(' | ') : null
}
export async function cancelGeneration(): Promise<void> {
try {
await localFetch(comfyuiUrl('/interrupt'), { method: 'POST', timeoutMs: COMFY_STATS_TIMEOUT_MS })
} catch { /* best effort */ }
}
/**
* Clear ComfyUI's PENDING queue (2026-06-16). /interrupt only stops the
* job that is currently executing; anything still queued (e.g. a duplicate that
* slipped in, or a second gen the model emitted) would start the instant the
* running one ends. On a user "Stop" we want EVERYTHING gone, so we clear the
* queue too. Best-effort — a failure here must never block the cancel path.
*/
export async function clearComfyQueue(): Promise<void> {
try {
await localFetch(comfyuiUrl('/queue'), {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clear: true }),
timeoutMs: COMFY_STATS_TIMEOUT_MS,
})
} catch { /* best effort */ }
}
/**
* Abandon ONE prompt without touching anyone else's work (G19-1). A blanket
* /interrupt kills whatever is CURRENTLY executing, which is the wrong job
* whenever ours still sits in the pending queue (R32: our render was number 4
* in line). So: delete ours from pending first, then interrupt only if ours is
* the one running. Best-effort on every leg.
*/
export async function abandonPrompt(promptId: string): Promise<void> {
try {
await localFetch(comfyuiUrl('/queue'), {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ delete: [promptId] }),
timeoutMs: COMFY_STATS_TIMEOUT_MS,
})
} catch { /* best effort */ }
try {
const res = await localFetch(comfyuiUrl('/queue'), { timeoutMs: COMFY_STATS_TIMEOUT_MS })
if (!res.ok) return
const q = await res.json()
const running = Array.isArray(q.queue_running)
&& q.queue_running.some((e: unknown) => Array.isArray(e) && e[1] === promptId)
if (running) await cancelGeneration()
} catch { /* best effort */ }
}
/**
* Clean up jobs a DEAD LU session left in ComfyUI (G19-3): a killed app cannot
* cancel its render, so the job keeps burning the GPU with no owner and every
* new generation queues behind it (R32 sat at queue position 4). Every LU
* submission carries an `lu-` client id; anything wearing that prefix under a
* DIFFERENT id than ours belongs to a session that no longer exists. Pending
* orphans are deleted, a running orphan is interrupted. Foreign clients (a
* user's own ComfyUI tab) never carry the prefix and are never touched.
* Returns how many jobs were cleaned, 0 on any error (best effort).
*/
export async function sweepOrphanedLuJobs(currentClientId: string): Promise<number> {
try {
const res = await localFetch(comfyuiUrl('/queue'), { timeoutMs: COMFY_STATS_TIMEOUT_MS })
if (!res.ok) return 0
const q = await res.json()
// Queue entries are [number, prompt_id, prompt, extra_data, ...] tuples.
const staleId = (e: unknown): string | null => {
if (!Array.isArray(e) || typeof e[1] !== 'string') return null
const owner = (e[3] as Record<string, unknown> | undefined)?.client_id
return typeof owner === 'string' && owner.startsWith(LU_CLIENT_PREFIX) && owner !== currentClientId
? e[1]
: null
}
const pending = (Array.isArray(q.queue_pending) ? q.queue_pending : [])
.map(staleId)
.filter((id: string | null): id is string => id !== null)
if (pending.length > 0) {
await localFetch(comfyuiUrl('/queue'), {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ delete: pending }),
timeoutMs: COMFY_STATS_TIMEOUT_MS,
})
}
const runningStale = (Array.isArray(q.queue_running) ? q.queue_running : []).some((e: unknown) => staleId(e) !== null)
if (runningStale) await cancelGeneration()
const cleaned = pending.length + (runningStale ? 1 : 0)
if (cleaned > 0) log.info('comfyui.orphan_sweep', { cleaned, pending: pending.length, runningStale })
return cleaned
} catch {
return 0
}
}
export async function freeMemory(): Promise<void> {
try {
await localFetch(comfyuiUrl('/free'), {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ unload_models: true, free_memory: true }),
// Bounded: this runs in the hand-off's `finally` right before reloading the
// text model. A wedged /free must not delay that reload by 5 min.
timeoutMs: COMFY_FREE_TIMEOUT_MS,
})
} catch { /* best effort */ }
}
export async function getHistory(promptId: string): Promise<ComfyHistoryEntry | null> {
try {
// localFetch routes through Rust proxy in Tauri to dodge CORS — same
// reason as submitWorkflow above. Without this, a user-run ComfyUI
// Portable would accept the /prompt POST but the polling /history GETs
// would silently 0-out and the UI hangs in "generating…" forever.
const res = await localFetch(comfyuiUrl(`/history/${promptId}`), { timeoutMs: COMFY_POLL_TIMEOUT_MS })
if (!res.ok) return null
const data: unknown = await res.json()
const entry = isRecord(data) ? data[promptId] : undefined
return isRecord(entry) ? entry : null
} catch {
return null
}
}
/** Is this prompt still alive inside ComfyUI (running or pending)? Used by
* the generation watchdog: a slow render that is still queued is progress,
* not a stall — only silence from BOTH the socket and the queue aborts.
* Queue entries are `[number, prompt_id, ...]` tuples. */
export async function isPromptQueued(promptId: string): Promise<boolean> {
return (await promptQueueState(promptId)) === 'queued'
}
/** Like isPromptQueued, but says when ComfyUI gave no answer. A busy ComfyUI
* can leave HTTP unanswered for minutes (I1, 12 GB box: a Z-Image VAE decode
* through shared memory, 22 min), and "no answer" is not "gone": only
* 'gone' lets the Create watchdog call a render stalled. */
export async function promptQueueState(promptId: string): Promise<'queued' | 'gone' | 'unknown'> {
try {
const res = await localFetch(comfyuiUrl('/queue'), { timeoutMs: COMFY_POLL_TIMEOUT_MS })
if (!res.ok) return 'unknown'
const q = await res.json()
const inList = (list: unknown) => Array.isArray(list)
&& list.some((e) => Array.isArray(e) && e[1] === promptId)
return inList(q.queue_running) || inList(q.queue_pending) ? 'queued' : 'gone'
} catch {
return 'unknown'
}
}
// ─── Upload image to ComfyUI (for I2V models like SVD, FramePack) ───
export async function uploadImage(file: File): Promise<string> {
// Guard: ComfyUI's /upload/image answers an opaque HTTP 400 for an empty or
// unreadable file. Catch the empty-blob case up front with a clear message
// (a user 2026-06-14: "Video generation failed: Failed to upload image: HTTP 400").
if (!file || file.size === 0) {
throw new Error('Failed to upload image: the source image is empty (0 bytes), it could not be read from ComfyUI.')
}
// ComfyUI saves the file under the multipart filename and opens it with PIL by
// extension, so it 400s on a missing/extension-less/odd name. Send an explicit,
// sanitised filename with a real image extension rather than trusting file.name
// (a Blob-derived File can carry "" or an extension-less name).
const safeName = ensureImageFilename(file.name, file.type)
// Tauri (packaged): post the multipart from Rust. The raw browser fetch()
// below was the ONLY non-proxy fetch left in the app, and it 400'd on some
// WebView2 builds (multipart/boundary/CORS-preflight quirks;
// 2026-06-14 "Failed to upload image: HTTP 400"). reqwest's multipart is
// machine-independent and removes WebView2 as a variable — matching the
// "everything via the Rust proxy" pattern (WebView2-149 finding). Dev/browser
// keeps the direct fetch (Vite proxy / CORS-enabled ComfyUI).
if (isTauri()) {
const bytes = Array.from(new Uint8Array(await file.arrayBuffer()))
let body: string
try {
body = await backendCall<string>('comfy_upload_image', {
url: comfyuiUrl('/upload/image'),
filename: safeName,
contentType: file.type || 'image/png',
fileBytes: bytes,
})
} catch (e) {
// The Rust side rejects with "HTTP <s>: <body>" — surface ComfyUI's
// actual reason so the dropzone error is self-explanatory.
throw new Error(`Failed to upload image: ${e instanceof Error ? e.message : String(e)}`)
}
const data = JSON.parse(body)
return data.name // ComfyUI returns { name, subfolder, type }
}
const formData = new FormData()
formData.append('image', file, safeName)
formData.append('overwrite', 'true')
// Direct fetch — localFetch only supports string body, not FormData.
// FormData needs multipart/form-data which fetch() sets automatically. A 400
// here means the request reached ComfyUI and it rejected the content, so the
// proxy/CORS is not at fault — surface ComfyUI's actual reason instead of a
// bare status so the next failure is self-explanatory.
const res = await fetch(comfyuiUrl('/upload/image'), {
method: 'POST',
body: formData,
})
if (!res.ok) {
let detail = ''
try { detail = (await res.text()).trim() } catch { /* body empty / already consumed */ }
throw new Error(`Failed to upload image: HTTP ${res.status}${detail ? `, ${detail.slice(0, 300)}` : ''}`)
}
const data = await res.json()
return data.name // ComfyUI returns { name, subfolder, type }
}
/** Ensure a ComfyUI-friendly image filename: a sane base plus a real image
* extension inferred from the MIME type when the name lacks one. ComfyUI's
* /upload/image needs a recognisable extension to open the file with PIL. */
export function ensureImageFilename(name: string | undefined, mime: string | undefined): string {
const base = (name || '').replace(/^.*[\\/]/, '').trim()
if (base && /\.(png|jpe?g|webp|gif|bmp|tiff?)$/i.test(base)) return base
const ext = ((m) => {
switch ((m || '').toLowerCase()) {
case 'image/jpeg': return 'jpg'
case 'image/webp': return 'webp'
case 'image/gif': return 'gif'
case 'image/bmp': return 'bmp'
case 'image/tiff': return 'tiff'
default: return 'png'
}
})(mime)
const stem = (base ? base.replace(/\.[^.]*$/, '') : 'lu_input') || 'lu_input'
const safeStem = stem.replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 64) || 'lu_input'
return `${safeStem}.${ext}`
}
/** Upload a NON-image media file (speech audio, driving video) into ComfyUI's
* input dir. Same /upload/image endpoint — it stores any file; LoadAudio /
* LoadVideo then list it by extension. The image uploader forces an image
* extension (PIL constraint), which would break these, so this variant keeps
* the file's own extension and only sanitizes the stem. */
export async function uploadMediaFile(blob: Blob, name: string): Promise<string> {
if (!blob || blob.size === 0) {
throw new Error('Failed to upload media: the file is empty (0 bytes).')
}
const base = (name || '').replace(/^.*[\\/]/, '').trim() || 'lu_media'
const dot = base.lastIndexOf('.')
const stem = (dot > 0 ? base.slice(0, dot) : base).replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 64) || 'lu_media'
const ext = (dot > 0 ? base.slice(dot + 1) : '').replace(/[^A-Za-z0-9]+/g, '').toLowerCase() || 'bin'
const safeName = `${stem}.${ext}`
if (isTauri()) {
const bytes = Array.from(new Uint8Array(await blob.arrayBuffer()))
let body: string
try {
body = await backendCall<string>('comfy_upload_image', {
url: comfyuiUrl('/upload/image'),
filename: safeName,
contentType: blob.type || 'application/octet-stream',
fileBytes: bytes,
})
} catch (e) {
throw new Error(`Failed to upload media: ${e instanceof Error ? e.message : String(e)}`)
}
const data = JSON.parse(body)
return data.name
}
const formData = new FormData()
formData.append('image', blob, safeName)
formData.append('overwrite', 'true')
const res = await fetch(comfyuiUrl('/upload/image'), { method: 'POST', body: formData })
if (!res.ok) throw new Error(`Failed to upload media: HTTP ${res.status}`)
const data = await res.json()
return data.name
}
export function getImageUrl(filename: string, subfolder: string = '', type: string = 'output', cacheBust?: string | number): string {
const path = `/view?filename=${encodeURIComponent(filename)}&subfolder=${encodeURIComponent(subfolder)}&type=${type}`
// A cache-buster is appended ONLY when an explicit, STABLE token is supplied
// (e.g. a gallery item's immutable `createdAt`). We must never mint a fresh
// `Date.now()` per call: that returned a different URL on every React
// re-render, forcing the <img>/<video> to refetch mid-render — which is
// exactly what made the media viewer flicker while zooming/panning/loading.
// ComfyUI output filenames are unique per generation, so a per-item token is
// sufficient to defeat any rare filename-reuse cache collision.
return comfyuiUrl(cacheBust != null ? `${path}&t=${cacheBust}` : path)
}
/**
* Fetch a ComfyUI /view image URL and return it base64-encoded (no data: prefix)
* so it can be handed to a vision-capable chat model as an `images` attachment.
* Used by the chat-agent vision feedback loop: after image_generate, the model
* SEES the picture it made and can comment on it.
*/
export async function fetchComfyImageBase64(url: string): Promise<string> {
// Not every generated image is a ComfyUI /view URL any more. The macOS MLX
// lane hands the chat agent a `blob:` URL (an in-memory PNG, no server), and
// the localhost proxy below cannot fetch one — it threw, the caller swallowed
// it, and the vision-feedback step silently gave up. The model then described
// the picture it had just made from the prompt alone, i.e. hallucinated it:
// exactly the failure the provider-aware fix cured on Windows.
if (url.startsWith('blob:') || url.startsWith('data:')) {
const buf = await (await blobFromUrl(url)).arrayBuffer()
return bytesToBase64(new Uint8Array(buf))
}
return bytesToBase64(await fetchLocalhostBytes(url))
}
function bytesToBase64(bytes: Uint8Array): string {
let binary = ''
const CHUNK = 0x8000 // avoid arg-count limits on String.fromCharCode
for (let i = 0; i < bytes.length; i += CHUNK) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK) as unknown as number[])
}
return btoa(binary)
}
// ─── Validate params ───
//
// LEGACY static bounds (steps 1-200 / frames 1-256). The chat-agent path
// (vram-handoff → buildDynamicWorkflow) now validates against REAL per-model
// limits via getModelCapabilities() in comfyui-nodes.ts and rejects-and-reports
// over-limit requests (decision 2). These hard bounds remain only for the legacy
// static workflow builders below (buildSDXLImgWorkflow / buildFluxImgWorkflow /
// buildWanVideoWorkflow); new validation must use getModelCapabilities.
function validateParams(params: GenerateParams) {
if (!params.prompt.trim()) throw new Error('Prompt is empty')
if (!params.model) throw new Error('No model selected')
if (params.width < 64 || params.width > 4096) throw new Error('Width must be 64-4096')
if (params.height < 64 || params.height > 4096) throw new Error('Height must be 64-4096')
if (params.steps < 1 || params.steps > 200) throw new Error('Steps must be 1-200')
}
function validateVideoParams(params: VideoParams) {
validateParams(params)
if (params.frames < 1 || params.frames > 256) throw new Error('Frames must be 1-256')
if (params.fps < 1 || params.fps > 60) throw new Error('FPS must be 1-60')
// Wan requires width/height to be multiples of 16
if (params.width % 16 !== 0) throw new Error(`Width must be a multiple of 16 (current: ${params.width})`)
if (params.height % 16 !== 0) throw new Error(`Height must be a multiple of 16 (current: ${params.height})`)
}
function getSeed(seed: number): number {
return resolveRunSeed(seed)
}
// ─── Snap video dimensions to valid values ───
export function snapToVideoGrid(width: number, height: number): { width: number; height: number } {
return {
width: Math.round(width / 16) * 16,
height: Math.round(height / 16) * 16,
}
}
// ─── Image Workflow: SDXL/SD (CheckpointLoaderSimple) ───
export function buildSDXLImgWorkflow(params: GenerateParams): ComfyApiGraph {
validateParams(params)
const seed = getSeed(params.seed)
return {
'1': { class_type: 'CheckpointLoaderSimple', inputs: { ckpt_name: params.model } },
'2': { class_type: 'CLIPTextEncode', inputs: { text: params.prompt, clip: ['1', 1] } },
'3': { class_type: 'CLIPTextEncode', inputs: { text: params.negativePrompt || '', clip: ['1', 1] } },
'4': { class_type: 'EmptyLatentImage', inputs: { width: params.width, height: params.height, batch_size: params.batchSize } },
'5': {
class_type: 'KSampler',
inputs: {
model: ['1', 0], positive: ['2', 0], negative: ['3', 0], latent_image: ['4', 0],
seed, steps: params.steps, cfg: params.cfgScale,
sampler_name: params.sampler, scheduler: params.scheduler, denoise: 1.0,
},
},
'6': { class_type: 'VAEDecode', inputs: { samples: ['5', 0], vae: ['1', 2] } },
'7': { class_type: 'SaveImage', inputs: { images: ['6', 0], filename_prefix: 'locally_uncensored' } },
}
}
// ─── Image Workflow: FLUX (UNETLoader + CLIPLoader + VAELoader) ───
/** UNET loader that understands GGUF quants. Core `UNETLoader` only enumerates
* safetensors, so handing it a .gguf gets the workflow rejected with "Value
* not in list" (stasicby-max, D#93 — the catalog offers uncensored Wan quants
* as GGUF). The city96 pack's `UnetLoaderGGUF` reads them. Same rule as the
* dynamic builder's addUnetLoader; this legacy path still carries the VRAM
* handoff and the agent's video tool. */
async function unetLoaderNode(model: string): Promise<ComfyApiNode> {
if (!model.toLowerCase().endsWith('.gguf')) {
return { class_type: 'UNETLoader', inputs: { unet_name: model, weight_dtype: 'default' } }
}
if (!(await nodeExists('UnetLoaderGGUF'))) {
throw new Error(
'This model is a GGUF quant, which needs the ComfyUI-GGUF node pack. Install it from the model card, or pick the safetensors variant.',
)
}
return { class_type: 'UnetLoaderGGUF', inputs: { unet_name: model } }
}
export async function buildFluxImgWorkflow(params: GenerateParams): Promise<ComfyApiGraph> {
validateParams(params)
const seed = getSeed(params.seed)
const modelType = classifyModel(params.model)
const vae = await findMatchingVAE(modelType)
const clip = await findMatchingCLIP(modelType)
const clipType = modelType === 'flux2' ? 'flux2' : 'flux'
const latentNode = modelType === 'flux2' ? 'EmptyFlux2LatentImage' : 'EmptySD3LatentImage'
return {
'1': await unetLoaderNode(params.model),
'2': { class_type: 'CLIPLoader', inputs: { clip_name: clip, type: clipType, device: 'default' } },
'3': { class_type: 'VAELoader', inputs: { vae_name: vae } },
'4': { class_type: 'CLIPTextEncode', inputs: { text: params.prompt, clip: ['2', 0] } },
'5': { class_type: 'CLIPTextEncode', inputs: { text: '', clip: ['2', 0] } },
'6': { class_type: latentNode, inputs: { width: params.width, height: params.height, batch_size: params.batchSize } },
'7': {
class_type: 'KSampler',
inputs: {
model: ['1', 0], positive: ['4', 0], negative: ['5', 0], latent_image: ['6', 0],
seed, steps: params.steps, cfg: params.cfgScale,
sampler_name: params.sampler, scheduler: params.scheduler, denoise: 1.0,
},
},
'8': { class_type: 'VAEDecode', inputs: { samples: ['7', 0], vae: ['3', 0] } },
'9': { class_type: 'SaveImage', inputs: { images: ['8', 0], filename_prefix: 'locally_uncensored' } },
}
}
// ─── Auto-select Image Workflow ───
/** The fixed graphs below know four image families and two video ones. Any
* other family handed to them becomes a checkpoint or Wan 2.1 graph that
* ComfyUI refuses with "Value not in list" (Discord 2026-10-01, Qwen-Image
* 2.1 and MiniMax H3), so the caller keeps the builder's own error instead. */
export function legacyBuilderFits(modelType: ModelType, video: boolean): boolean {
if (video) return modelType === 'wan' || modelType === 'animatediff' || modelType === 'sd15'
return modelType === 'sd15' || modelType === 'sdxl' || modelType === 'flux' || modelType === 'flux2' || modelType === 'unknown'
}
export async function buildTxt2ImgWorkflow(params: GenerateParams, modelType: ModelType): Promise<ComfyApiGraph> {
if (modelType === 'flux' || modelType === 'flux2') return buildFluxImgWorkflow(params)
return buildSDXLImgWorkflow(params)
}
// ─── Video Workflow: Wan 2.1/2.2 (Hunyuan latent space) ───
export async function buildWanVideoWorkflow(params: VideoParams): Promise<ComfyApiGraph> {
validateVideoParams(params)
const seed = getSeed(params.seed)
// Pre-check required nodes
const hasLatent = await nodeExists('EmptyHunyuanLatentVideo')
if (!hasLatent) throw new Error('EmptyHunyuanLatentVideo node not found. Update ComfyUI to latest version.')
const hasSaver = await videoSaverPresence()
const vae = await findMatchingVAE('wan')
const clip = await findMatchingCLIP('wan')
const hasTiledDecode = await nodeExists('VAEDecodeTiled')
const workflow: ComfyApiGraph = {
'1': { class_type: 'CLIPLoader', inputs: { clip_name: clip, type: 'wan', device: 'default' } },
'2': await unetLoaderNode(params.model),
'3': { class_type: 'VAELoader', inputs: { vae_name: vae } },
'4': { class_type: 'CLIPTextEncode', inputs: { text: params.prompt, clip: ['1', 0] } },
'5': { class_type: 'CLIPTextEncode', inputs: { text: params.negativePrompt || 'static, blurred, low quality, worst quality, deformed', clip: ['1', 0] } },
'6': { class_type: 'EmptyHunyuanLatentVideo', inputs: { width: params.width, height: params.height, length: params.frames, batch_size: 1 } },
'7': {
class_type: 'KSampler',
inputs: {
model: ['2', 0], positive: ['4', 0], negative: ['5', 0], latent_image: ['6', 0],
seed, steps: params.steps, cfg: params.cfgScale,
sampler_name: params.sampler, scheduler: params.scheduler, denoise: 1.0,
},
},
'8': videoDecodeNode(['7', 0], ['3', 0], hasTiledDecode),
}
// An mp4 the chat player and the gallery can play (A19): this path wrote a
// fixed SaveAnimatedWEBP, so Wan 2.1 in the chat came back as an animated
// picture without controls. Prompt-based prefix (2026-06-11) — the dynamic
// builder got this in c40d13f, this legacy T2V path still wrote
// locally_uncensored_vid.
addVideoSave(workflow, 9, ['8', 0], params.fps, promptFilenamePrefix(params.prompt, true), hasSaver)
return workflow
}
// ─── Video Workflow: AnimateDiff ───
export async function buildAnimateDiffWorkflow(params: VideoParams): Promise<ComfyApiGraph> {
validateVideoParams(params)
const seed = getSeed(params.seed)
const motionModel = await findAnimateDiffModel()
// AnimateDiff: batch_size=1, motion model handles temporal dimension
const hasSaver = await videoSaverPresence()
const hasTiledDecode = await nodeExists('VAEDecodeTiled')
const workflow: ComfyApiGraph = {
'1': { class_type: 'CheckpointLoaderSimple', inputs: { ckpt_name: params.model } },
'2': { class_type: 'ADE_LoadAnimateDiffModel', inputs: { model_name: motionModel } },
'3': { class_type: 'ADE_ApplyAnimateDiffModelSimple', inputs: { motion_model: ['2', 0] } },
'4': { class_type: 'ADE_UseEvolvedSampling', inputs: { model: ['1', 0], m_models: ['3', 0], beta_schedule: 'autoselect' } },
'5': { class_type: 'CLIPTextEncode', inputs: { text: params.prompt, clip: ['1', 1] } },
'6': { class_type: 'CLIPTextEncode', inputs: { text: params.negativePrompt || 'low quality, blurry, static', clip: ['1', 1] } },
'7': { class_type: 'EmptyLatentImage', inputs: { width: params.width, height: params.height, batch_size: params.frames } },
'8': {
class_type: 'KSampler',
inputs: {
model: ['4', 0], positive: ['5', 0], negative: ['6', 0], latent_image: ['7', 0],
seed, steps: params.steps, cfg: params.cfgScale,
sampler_name: params.sampler, scheduler: params.scheduler, denoise: 1.0,
},
},
'9': videoDecodeNode(['8', 0], ['1', 2], hasTiledDecode),
}
// Core SaveVideo or VHS (both MP4), otherwise SaveAnimatedWEBP, otherwise SaveImage (A19)
addVideoSave(workflow, 10, ['9', 0], params.fps, 'locally_uncensored_vid', hasSaver)
return workflow
}
// ─── Auto-select Video Workflow ───
export async function buildTxt2VidWorkflow(params: VideoParams, backend: VideoBackend): Promise<ComfyApiGraph> {
switch (backend) {
case 'wan': return buildWanVideoWorkflow(params)
case 'animatediff': return buildAnimateDiffWorkflow(params)
default: throw new Error('No video backend available. Install Wan 2.1 models or AnimateDiff nodes in ComfyUI.')
}
}