Skip to content

armgit / kokon

Public Imported from GitHub
0

Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.

New image from reference images, Prompt+ menu, longer Prompt+ prompts

Gabriele Lozupone149c29985ff2
diff --git a/crates/qls-core/src/config.rs b/crates/qls-core/src/config.rs
index 81fcb7a..a5c3146 100644
--- a/crates/qls-core/src/config.rs
+++ b/crates/qls-core/src/config.rs
@@ -335,10 +335,12 @@ pub struct AppConfig {
/// Plan as if the GPU had this much VRAM (MiB); 0 = use the detected size. For testing
/// smaller cards on a larger one, together with a VRAM ballast (scripts/dev).
pub vram_override_mib: u64,
- /// System prompts of the prompt enhancer for text-to-image and for edits; "" = the
- /// built-in ones (`enhancer::T2I_SYSTEM_PROMPT`, `enhancer::EDIT_SYSTEM_PROMPT`).
+ /// System prompts of the prompt enhancer for text-to-image, edits and new images from
+ /// references; "" = the built-in ones (`enhancer::T2I_SYSTEM_PROMPT`, `EDIT_SYSTEM_PROMPT`,
+ /// `COMPOSE_SYSTEM_PROMPT`).
pub enhancer_t2i_prompt: String,
pub enhancer_edit_prompt: String,
+ pub enhancer_compose_prompt: String,
/// The user's LoRAs (Settings → LoRA), each a copy in `lora_dir`. Changed only through the
/// LoRA endpoints: a whole-config save keeps the current list (`Engine::set_config`).
pub loras: Vec<LoraEntry>,
@@ -379,6 +381,7 @@ impl Default for AppConfig {
vram_override_mib: 0,
enhancer_t2i_prompt: String::new(),
enhancer_edit_prompt: String::new(),
+ enhancer_compose_prompt: String::new(),
loras: vec![],
ui: serde_json::json!({}),
}
@@ -595,7 +598,11 @@ impl AppConfig {
/// other profile is the user's, and the active profile exists.
pub fn normalize(&mut self) {
// A prompt equal to the built-in one is saved as "" so it follows future defaults.
- for (custom, default) in [(&mut self.enhancer_t2i_prompt, crate::enhancer::T2I_SYSTEM_PROMPT), (&mut self.enhancer_edit_prompt, crate::enhancer::EDIT_SYSTEM_PROMPT)] {
+ for (custom, default) in [
+ (&mut self.enhancer_t2i_prompt, crate::enhancer::T2I_SYSTEM_PROMPT),
+ (&mut self.enhancer_edit_prompt, crate::enhancer::EDIT_SYSTEM_PROMPT),
+ (&mut self.enhancer_compose_prompt, crate::enhancer::COMPOSE_SYSTEM_PROMPT),
+ ] {
if custom.trim().is_empty() || custom.trim() == default {
custom.clear();
}
@@ -834,7 +841,7 @@ impl AppConfig {
return Err(AppError::new(ErrorCode::InvalidConfig, "Simulated VRAM must be between 4096 and 196608 MiB (or 0 to detect it)."));
}
let max = crate::enhancer::MAX_SYSTEM_PROMPT_CHARS;
- if self.enhancer_t2i_prompt.chars().count() > max || self.enhancer_edit_prompt.chars().count() > max {
+ if [&self.enhancer_t2i_prompt, &self.enhancer_edit_prompt, &self.enhancer_compose_prompt].iter().any(|p| p.chars().count() > max) {
return Err(AppError::new(ErrorCode::InvalidConfig, format!("Prompt enhancer instructions can be at most {max} characters.")));
}
Ok(())
@@ -875,7 +882,7 @@ mod tests {
assert!(c.enhancer_t2i_prompt.is_empty() && c.enhancer_edit_prompt.is_empty(), "built-in by default");
// Older settings files have no such keys.
let old: AppConfig = serde_json::from_str(r#"{"schemaVersion":9}"#).unwrap();
- assert!(old.enhancer_edit_prompt.is_empty());
+ assert!(old.enhancer_edit_prompt.is_empty() && old.enhancer_compose_prompt.is_empty());
// A restored default is saved blank, so it follows future defaults; a custom one stays.
c.enhancer_t2i_prompt = format!("{}\n", crate::enhancer::T2I_SYSTEM_PROMPT);
c.enhancer_edit_prompt = "Retouch jewelry only.".into();
@@ -884,8 +891,14 @@ mod tests {
let v = serde_json::to_value(&c).unwrap();
assert_eq!(v["enhancerEditPrompt"], "Retouch jewelry only.");
assert!(c.validate().is_ok());
+ c.enhancer_compose_prompt = format!(" {} ", crate::enhancer::COMPOSE_SYSTEM_PROMPT);
+ c.normalize();
+ assert!(c.enhancer_compose_prompt.is_empty());
c.enhancer_edit_prompt = "x".repeat(crate::enhancer::MAX_SYSTEM_PROMPT_CHARS + 1);
assert!(c.validate().is_err());
+ c.enhancer_edit_prompt.clear();
+ c.enhancer_compose_prompt = "x".repeat(crate::enhancer::MAX_SYSTEM_PROMPT_CHARS + 1);
+ assert!(c.validate().is_err());
}
#[test]
diff --git a/crates/qls-core/src/engine.rs b/crates/qls-core/src/engine.rs
index c083cf2..d84dcd7 100644
--- a/crates/qls-core/src/engine.rs
+++ b/crates/qls-core/src/engine.rs
@@ -971,6 +971,19 @@ impl Engine {
sd_req.prompt = pipeline::enhanced_prompt(&request.prompt, text);
}
}
+ // Prompt+ review: the prompt is the result; the user's next job makes the image.
+ if request.enhance_only {
+ if enhanced.is_none() {
+ let why = self.job(id).map(|j| j.notes.join(" ")).unwrap_or_default();
+ return Err(AppError::new(ErrorCode::GenerationFailed, "Prompt+ could not write a prompt; yours is unchanged.").detail(why));
+ }
+ self.update(id, |j| {
+ j.view.status = JobStatus::Done;
+ j.view.finished_at = Some(now_rfc3339());
+ j.view.stage = None;
+ });
+ return Ok(());
+ }
// 4c. The user's LoRAs, trigger words in front of the final prompt.
loras = self.job_loras(id, &cfg, &request, &caps);
@@ -1168,8 +1181,28 @@ impl Engine {
j.view.stage = None;
j.view.enhanced_prompt = Some(String::new());
});
- let req = enhancer::request(cfg, mode, prompt, images.to_vec(), seed);
let started = Instant::now();
+ // A new image from references: each reference is labelled alone first, then the scene is
+ // written from the labels without the images (see `enhancer::COMPOSE_SYSTEM_PROMPT`).
+ let req = if mode == ResolvedMode::Compose {
+ let mut labels = Vec::with_capacity(images.len());
+ for img in images {
+ let r = client.text_gen(&enhancer::label_request(img.clone(), prompt, seed), Duration::from_secs(120), |_| {}, || self.is_cancelled(id)).await;
+ match r {
+ Ok(done) => labels.push(enhancer::clean_label(&done.text)),
+ Err(e) if e.code == ErrorCode::Cancelled => return Err(e),
+ // A missing label leaves the image model to see that reference by itself.
+ Err(e) => {
+ tracing::warn!("prompt enhancer: labelling a reference failed: {} {:?}", e.message, e.detail);
+ labels.push("the subject of this reference".into());
+ }
+ }
+ }
+ tracing::info!("prompt enhancer: {} reference labels in {:.1} s: {:?}", labels.len(), started.elapsed().as_secs_f32(), labels);
+ enhancer::compose_request(cfg, &labels, prompt, seed)
+ } else {
+ enhancer::request(cfg, mode, prompt, images.to_vec(), seed)
+ };
let mut text = String::new();
let mut last_emit = Instant::now();
let on_delta = |d: &str| {
@@ -1424,6 +1457,7 @@ impl Engine {
ResolvedMode::Inpaint => "inpaint",
ResolvedMode::Outpaint => "outpaint",
ResolvedMode::MultiReference => "multi_reference",
+ ResolvedMode::Compose => "compose",
ResolvedMode::Upscale => "upscale",
};
let mut rec = GenerationRecord {
@@ -1431,7 +1465,8 @@ impl Engine {
created_at: now_rfc3339(),
mode: mode.into(),
// An enhanced job records the prompt the image was made from, and the user's.
- original_prompt: enhanced_prompt.is_some().then(|| req.prompt.clone()),
+ // A reviewed prompt (written by Prompt+, then sent by the user) keeps the user's words too.
+ original_prompt: enhanced_prompt.is_some().then(|| req.prompt.clone()).or_else(|| req.enhanced_from.clone().filter(|p| !p.trim().is_empty())),
prompt: enhanced_prompt.unwrap_or_else(|| req.prompt.clone()),
loras,
negative_prompt: plan.negative_prompt.clone(),
@@ -1875,6 +1910,97 @@ mod tests {
assert_eq!(err.code, ErrorCode::Cancelled);
}
+ /// A text_gen endpoint that answers each request in turn with the next of `answers` (SSE),
+ /// and reports the bodies it got.
+ async fn fake_text_server(answers: Vec<&'static str>) -> (u16, Arc<Mutex<Vec<serde_json::Value>>>) {
+ use tokio::io::{AsyncReadExt, AsyncWriteExt};
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let port = listener.local_addr().unwrap().port();
+ let seen = Arc::new(Mutex::new(Vec::new()));
+ let log = seen.clone();
+ tokio::spawn(async move {
+ for answer in answers {
+ let Ok((mut sock, _)) = listener.accept().await else { return };
+ let mut req = Vec::new();
+ let mut buf = [0u8; 65536];
+ let body = loop {
+ let n = sock.read(&mut buf).await.unwrap();
+ req.extend_from_slice(&buf[..n]);
+ let text = String::from_utf8_lossy(&req).to_string();
+ if let Some(end) = text.find("\r\n\r\n") {
+ let len = text.lines().find_map(|l| l.to_ascii_lowercase().strip_prefix("content-length:").map(|v| v.trim().parse::<usize>().unwrap())).unwrap_or(0);
+ if req.len() >= end + 4 + len {
+ break req[end + 4..end + 4 + len].to_vec();
+ }
+ }
+ };
+ log.lock().unwrap().push(serde_json::from_slice(&body).unwrap());
+ let _ = sock.write_all(b"HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\nConnection: close\r\n\r\n").await;
+ for c in crate::sdcpp::sse_answer(&[answer], "stop") {
+ let _ = sock.write_all(c.as_bytes()).await;
+ }
+ }
+ });
+ (port, seen)
+ }
+
+ #[tokio::test]
+ async fn compose_labels_each_reference_then_writes_the_scene_without_images() {
+ let dir = tempfile::tempdir().unwrap();
+ // SAFETY: test-only env override, single-threaded setup.
+ unsafe { std::env::set_var("QLS_CONFIG_DIR", dir.path().join("cfg")) };
+ let mut cfg = AppConfig::default();
+ cfg.sdcpp_dir = dir.path().join("sdcpp");
+ cfg.normalize();
+ std::fs::create_dir_all(cfg.engine_dir()).unwrap();
+ std::fs::write(cfg.server_exe(), b"").unwrap();
+ for (_, p, _) in cfg.profile().files() {
+ std::fs::create_dir_all(p.parent().unwrap()).unwrap();
+ std::fs::write(p, b"").unwrap();
+ }
+ let e = Engine::new(cfg.clone(), dir.path()).unwrap();
+ let caps = Capabilities { text_generation: true, ..Default::default() };
+ let id = e.submit(GenerationRequest { prompt: "lei sul divano con il gatto".into(), enhance: true, ..Default::default() }, None).unwrap().id;
+ let (port, seen) = fake_text_server(vec!["person, female, long brown hair.\n", "cat, orange tabby", "A photograph of the woman from <image1> on a sofa."]).await;
+ let images = vec!["PNG1".to_string(), "PNG2".to_string()];
+ let out = e.enhance_prompt(&id, &SdcppClient::new(port), &caps, &cfg, ResolvedMode::Compose, "lei sul divano con il gatto", &images, 9).await.unwrap();
+ assert_eq!(out.as_deref(), Some("A photograph of the woman from <image1> on a sofa."));
+ let seen = seen.lock().unwrap();
+ assert_eq!(seen.len(), 3);
+ for (i, img) in ["PNG1", "PNG2"].iter().enumerate() {
+ assert_eq!((seen[i]["images"][0].as_str(), seen[i]["system_prompt"].as_str()), (Some(*img), Some(enhancer::COMPOSE_LABEL_PROMPT)), "one reference per label");
+ }
+ assert!(seen[2].get("images").is_none(), "the scene is written without the images");
+ assert_eq!(seen[2]["system_prompt"], enhancer::COMPOSE_SYSTEM_PROMPT);
+ assert_eq!(seen[2]["prompt"], "References:\n<image1>: person, female, long brown hair\n<image2>: cat, orange tabby\n\nRequest: lei sul divano con il gatto");
+ }
+
+ #[test]
+ fn reviewed_prompts_keep_the_users_words() {
+ let dir = tempfile::tempdir().unwrap();
+ // SAFETY: test-only env override, single-threaded setup.
+ unsafe { std::env::set_var("QLS_CONFIG_DIR", dir.path().join("cfg")) };
+ let cfg = AppConfig { output_dir: dir.path().join("out"), ..AppConfig::default() };
+ let e = Engine::new(cfg, dir.path()).unwrap();
+ let img = image::RgbaImage::from_pixel(64, 64, image::Rgba([40, 90, 160, 255]));
+ let inputs = crate::planner::PlanInputs { vram_total_mib: Some(16303), ..Default::default() };
+ let save = |req: &GenerationRequest, enhanced: Option<String>| {
+ let plan = crate::planner::plan(req, &inputs, &crate::config::RecommendedSettings::default()).unwrap();
+ e.save_result(&img, req, &plan, 1, &[], None, None, 10, None, 0, None, None, enhanced, Vec::new()).unwrap()
+ };
+ // Prompt+ review: the user sends the text Prompt+ wrote (maybe changed), with their words.
+ let long = "A ginger cat asleep on a sunlit windowsill, soft morning light from the left.";
+ let reviewed = GenerationRequest { prompt: long.into(), enhanced_from: Some("un gatto rosso".into()), ..Default::default() };
+ let rec = save(&reviewed, None);
+ assert_eq!((rec.prompt.as_str(), rec.original_prompt.as_deref()), (long, Some("un gatto rosso")));
+ // Written in the same job: as before.
+ let rec = save(&GenerationRequest { prompt: "un gatto rosso".into(), enhance: true, ..Default::default() }, Some(long.into()));
+ assert_eq!((rec.prompt.as_str(), rec.original_prompt.as_deref()), (long, Some("un gatto rosso")));
+ // The user's own prompt.
+ let rec = save(&GenerationRequest { prompt: "un gatto".into(), enhanced_from: Some(" ".into()), ..Default::default() }, None);
+ assert_eq!((rec.prompt.as_str(), rec.original_prompt), ("un gatto", None));
+ }
+
#[test]
fn private_results_stay_out_of_the_gallery() {
let dir = tempfile::tempdir().unwrap();
diff --git a/crates/qls-core/src/enhancer.rs b/crates/qls-core/src/enhancer.rs
index b947bc1..e377d8f 100644
--- a/crates/qls-core/src/enhancer.rs
+++ b/crates/qls-core/src/enhancer.rs
@@ -21,7 +21,7 @@ pub const T2I_SYSTEM_PROMPT: &str = r#"You write prompts for an image generation
- People: only what is visible (life stage, expression, pose, hair, clothing). No brand names unless the user gave them.
- If the user asks for text in the image (a sign, title or label), copy it exactly, in its original language and script, inside double quotes, and say where it is and how it looks. Otherwise write nothing about text.
- Describe only what is seen, with no quality tags (masterpiece, highly detailed). When the user says what the image is for, keep what that means for the look and write it as visible choices (how dark, how much empty space, how bold), not as the name of the device or use.
-- Write in English whatever language the user writes in, about 80 to 150 words, in the present tense, as a description of the image, not as instructions.
+- Write in English whatever language the user writes in, about 80 to 150 words, in the present tense, as a description of the image, not as instructions. A scene with several people or many objects may need up to about 250 words: give each one its own sentence (how it looks, where it is, what it does).
Output only the prompt."#;
/// Built-in system prompt for image-grounded edits and combines.
@@ -34,33 +34,72 @@ pub const EDIT_SYSTEM_PROMPT: &str = r#"You write prompts for an image editing m
- Text in the image: write the exact new text in double quotes, in the language the user gave, and keep the existing lettering style and position unless the user asks otherwise.
- For a style or mood change (painting, season, night, ...), apply it fully to the whole image and end with "Keep the composition and the subjects unchanged." instead.
- With several input images, refer to them as <image1>, <image2>, ...: start with Place or Combine, say what is taken from each image and where it goes in the result.
-- Write in English whatever language the user writes in, as one paragraph of about 20 to 60 words, with no resolution or aspect ratio.
+- Write in English whatever language the user writes in, as one paragraph with no resolution or aspect ratio: about 20 to 60 words for one change; when the user asks for several changes, one sentence for each, up to about 150 words.
Output only the instruction."#;
+/// Built-in system prompt for a new image made with reference images (people, products, a
+/// place, a style), step 2 of 2: written from the request and one label per reference
+/// ([`COMPOSE_LABEL_PROMPT`]), without the images. Shown the images, the 8B described the
+/// references (their places, poses, what people held) instead of the requested scene, with any
+/// system prompt (2026-10-22, bench sysprompt-v3-compose: "her on the sofa with the cat" came
+/// back as the forest and the windowsill of the references); from labels it follows the request.
+/// The image model still gets the references themselves, so identities come from them.
+pub const COMPOSE_SYSTEM_PROMPT: &str = r#"You write prompts for an image generation model. The model also receives the user's reference images, numbered <image1>, <image2>, ...; you do not see them, only a short label for each. Turn the user's request into one English paragraph describing the finished new image.
+- Start with what the image shows, in one sentence that contains everything the user asked for (the objects, the scene, the action, the kind of image).
+- Refer to each reference the request uses as "the X from <imageN>", with X taken from its label, and describe it with the label's details so it stays recognizable. A person, animal or object appears as it is, in the new scene, doing what the user asks. A label that starts with "style" is a style for the whole image, not a thing to show.
+- If the user asks for something new (a new product, a collaboration, a mix, a redesign), the new thing is the main subject: invent one concrete, surprising idea and describe its form and materials and which colours, logos, lettering and shapes it takes from each reference's label. When it joins several brands, every brand's logo and name is clearly visible on it.
+- Then describe the setting and background with their colours and materials, where each subject is and how large, the camera view, and the light (source, direction, quality), with real shadows and reflections.
+- Add nothing the user did not ask for. Keep everything the user specified and never contradict it; counts are exact. Write new text in the image only if the user gives it or asks for a name, title or slogan, copied exactly inside double quotes; never turn the words of the request into signs.
+- Name the medium early: the user's, a style label's, else a photograph. Translate the meaning, not word by word. Present tense, only visible things, no quality tags, no resolution or aspect ratio.
+- Write in English whatever language the user writes in: about 80 to 180 words, up to about 280 when the scene has several people or many objects, with a sentence for each.
+Output only the prompt."#;
+
+/// Step 1 of a composition: each reference seen alone, with the user's request, and labelled by
+/// what the request takes from it (a list of features, which the 8B keeps free of the photo's
+/// context better than a sentence). With the request it labels the bowl a person holds, or a
+/// photo's style, rather than the photo's main subject (A/B 2026-10-22: both lost without it).
+pub const COMPOSE_LABEL_PROMPT: &str = r#"You label one reference image for a new picture the user asked for. Decide what the user's request takes from this image: a person, an animal, an object or product (also a small one inside the photo), a place, or only its style. Reply with a comma-separated list of that thing's own visible features, at most 25 words. Nothing else.
+Fill in the pattern for its kind, replacing each <...> with what you see and leaving out any part you cannot see:
+- person, <apparent gender and age>, <hair colour, length and style>, <skin tone>, <each clothing item with its colour>
+- <animal kind>, <breed if clear>, <colours>, <fur>
+- <object kind>, <brand>, <shape>, <colours>, <material>, <main printed words in quotes>
+- <kind of place>, <main features>
+- style, <medium>, <colour palette>, <kind of light>, <texture>
+Describe the thing alone: never its action, pose, who holds it, what it rests on, its surroundings or background (except as the place or style when that is what the request takes)."#;
+
+/// Longest label kept (a model that rambles is cut, the label is only a hint).
+pub const LABEL_MAX_TOKENS: u32 = 96;
+
/// Longest custom system prompt accepted in Settings (characters).
pub const MAX_SYSTEM_PROMPT_CHARS: usize = 20_000;
-/// The built-in prompts ask for ≤ 150 words (~200 tokens); the cap only stops a model that
-/// does not end its turn.
-pub const MAX_TOKENS: u32 = 512;
+/// The built-in prompts ask for up to ~300 words for crowded scenes (~400 tokens); the cap only
+/// stops a model that does not end its turn. 512 cut long scene descriptions mid-sentence
+/// (2026-10-22); 1024 tokens take ~8 s at the measured ~127 tok/s.
+pub const MAX_TOKENS: u32 = 1024;
/// Qwen's recommended sampling for Qwen3-VL (vision-language), used for both prompts.
pub const SAMPLING: TextSampling = TextSampling { temperature: 0.7, top_p: 0.8, top_k: 20, presence_penalty: 1.5, seed: -1 };
-/// Text-to-image, edits and combines get the enhancer. Inpaint and outpaint wrap the prompt
-/// in their own instructions, and upscales have no prompt.
+/// Text-to-image, new images from references, edits and combines get the enhancer. Inpaint
+/// and outpaint wrap the prompt in their own instructions, and upscales have no prompt.
pub fn applies(mode: ResolvedMode) -> bool {
- matches!(mode, ResolvedMode::Generate | ResolvedMode::Edit | ResolvedMode::MultiReference)
+ matches!(mode, ResolvedMode::Generate | ResolvedMode::Compose | ResolvedMode::Edit | ResolvedMode::MultiReference)
}
/// The system prompt for `mode`: the one saved in Settings, or the built-in one.
pub fn system_prompt(cfg: &AppConfig, mode: ResolvedMode) -> String {
- let (custom, default) = if mode == ResolvedMode::Generate { (&cfg.enhancer_t2i_prompt, T2I_SYSTEM_PROMPT) } else { (&cfg.enhancer_edit_prompt, EDIT_SYSTEM_PROMPT) };
+ let (custom, default) = match mode {
+ ResolvedMode::Generate => (&cfg.enhancer_t2i_prompt, T2I_SYSTEM_PROMPT),
+ ResolvedMode::Compose => (&cfg.enhancer_compose_prompt, COMPOSE_SYSTEM_PROMPT),
+ _ => (&cfg.enhancer_edit_prompt, EDIT_SYSTEM_PROMPT),
+ };
if custom.trim().is_empty() { default.to_string() } else { custom.trim().to_string() }
}
/// The `text_gen` request for a job: its seed (so the same seed writes the same prompt, and
-/// Regenerate writes a new one) and, for edits, the references as the image model gets them.
+/// Regenerate writes a new one) and, for edits and compositions, the references as the image
+/// model gets them.
pub fn request(cfg: &AppConfig, mode: ResolvedMode, prompt: &str, images: Vec<String>, seed: i64) -> TextGenRequest {
TextGenRequest {
prompt: prompt.trim().to_string(),
@@ -72,6 +111,38 @@ pub fn request(cfg: &AppConfig, mode: ResolvedMode, prompt: &str, images: Vec<St
}
}
+/// Step 1 of a composition: the label request for one reference (as the image model gets it),
+/// with the user's request.
+pub fn label_request(image: String, request: &str, seed: i64) -> TextGenRequest {
+ TextGenRequest {
+ prompt: format!("The user's request for the new picture: {}\nLabel what it takes from this image.", request.trim()),
+ system_prompt: COMPOSE_LABEL_PROMPT.into(),
+ images: vec![image],
+ max_tokens: LABEL_MAX_TOKENS,
+ sampling: TextSampling { seed, ..SAMPLING },
+ stream: true,
+ }
+}
+
+/// A label as the model wrote it, on one line and without a closing full stop.
+pub fn clean_label(text: &str) -> String {
+ let one_line = text.split_whitespace().collect::<Vec<_>>().join(" ");
+ one_line.trim().trim_end_matches('.').trim().chars().take(400).collect()
+}
+
+/// Step 2 of a composition: the request with the references' labels, without the images.
+pub fn compose_request(cfg: &AppConfig, labels: &[String], prompt: &str, seed: i64) -> TextGenRequest {
+ let refs: Vec<String> = labels.iter().enumerate().map(|(i, l)| format!("<image{}>: {l}", i + 1)).collect();
+ TextGenRequest {
+ prompt: format!("References:\n{}\n\nRequest: {}", refs.join("\n"), prompt.trim()),
+ system_prompt: system_prompt(cfg, ResolvedMode::Compose),
+ images: Vec::new(),
+ max_tokens: MAX_TOKENS,
+ sampling: TextSampling { seed, ..SAMPLING },
+ stream: true,
+ }
+}
+
/// The model's answer as a prompt: trimmed, without a "Prompt:" label or quotes around the
/// whole text. None when nothing usable is left.
pub fn clean(text: &str) -> Option<String> {
@@ -94,16 +165,20 @@ mod tests {
#[test]
fn modes_and_prompts() {
- assert!(applies(ResolvedMode::Generate) && applies(ResolvedMode::Edit) && applies(ResolvedMode::MultiReference));
+ assert!(applies(ResolvedMode::Generate) && applies(ResolvedMode::Edit) && applies(ResolvedMode::MultiReference) && applies(ResolvedMode::Compose));
assert!(!applies(ResolvedMode::Inpaint) && !applies(ResolvedMode::Outpaint) && !applies(ResolvedMode::Upscale));
let mut cfg = AppConfig::default();
assert_eq!(system_prompt(&cfg, ResolvedMode::Generate), T2I_SYSTEM_PROMPT);
assert_eq!(system_prompt(&cfg, ResolvedMode::Edit), EDIT_SYSTEM_PROMPT);
assert_eq!(system_prompt(&cfg, ResolvedMode::MultiReference), EDIT_SYSTEM_PROMPT);
+ assert_eq!(system_prompt(&cfg, ResolvedMode::Compose), COMPOSE_SYSTEM_PROMPT);
cfg.enhancer_edit_prompt = " Jewelry retouch rules.\n".into();
cfg.enhancer_t2i_prompt = " \n ".into();
assert_eq!(system_prompt(&cfg, ResolvedMode::Edit), "Jewelry retouch rules.");
assert_eq!(system_prompt(&cfg, ResolvedMode::Generate), T2I_SYSTEM_PROMPT, "blank = built-in");
+ assert_eq!(system_prompt(&cfg, ResolvedMode::Compose), COMPOSE_SYSTEM_PROMPT, "an edit prompt does not change compose");
+ cfg.enhancer_compose_prompt = "Product shots only.".into();
+ assert_eq!(system_prompt(&cfg, ResolvedMode::Compose), "Product shots only.");
assert!(T2I_SYSTEM_PROMPT.ends_with("Output only the prompt.") && EDIT_SYSTEM_PROMPT.contains("<image1>, <image2>"));
}
@@ -111,7 +186,7 @@ mod tests {
fn builtin_prompts_have_nothing_the_model_copies() {
// Seen in real outputs (bench sysprompt-v2-20261019-155557): example colours ended up in
// almost every prompt, and the text rule became "No text appears in the image."
- for p in [T2I_SYSTEM_PROMPT, EDIT_SYSTEM_PROMPT] {
+ for p in [T2I_SYSTEM_PROMPT, EDIT_SYSTEM_PROMPT, COMPOSE_SYSTEM_PROMPT, COMPOSE_LABEL_PROMPT] {
for leak in ["deep navy", "pale cream", "copper", "No text"] {
assert!(!p.contains(leak), "{leak:?} in a built-in prompt");
}
@@ -128,6 +203,26 @@ mod tests {
assert!(r.stream);
let r = request(&cfg, ResolvedMode::Generate, "un gatto", vec!["PNG".into()], 1);
assert!(r.images.is_empty() && r.system_prompt == T2I_SYSTEM_PROMPT);
+ // Compose: each reference labelled alone, then the scene from the labels, without images.
+ let l = label_request("A".into(), " la ciotola su un tavolo ", 5);
+ assert_eq!((l.images.len(), l.system_prompt.as_str(), l.sampling.seed, l.max_tokens), (1, COMPOSE_LABEL_PROMPT, 5, LABEL_MAX_TOKENS));
+ assert!(l.prompt.contains("la ciotola su un tavolo\n"), "the label knows what the request takes");
+ let labels = vec!["person, female, dark hair; style: photo".to_string(), "cat, orange tabby; style: photo".to_string()];
+ let r = compose_request(&cfg, &labels, " lei sul divano con il gatto ", 5);
+ assert!(r.images.is_empty() && r.system_prompt == COMPOSE_SYSTEM_PROMPT && r.sampling.seed == 5);
+ assert_eq!(r.prompt, "References:\n<image1>: person, female, dark hair; style: photo\n<image2>: cat, orange tabby; style: photo\n\nRequest: lei sul divano con il gatto");
+ assert_eq!(clean_label(" cat,\n orange tabby.\n"), "cat, orange tabby");
+ }
+
+ #[test]
+ fn compose_prompt_makes_a_new_picture() {
+ // "Keep everything else unchanged" turns a composition into an edit of image 1.
+ assert!(!COMPOSE_SYSTEM_PROMPT.contains("unchanged"));
+ assert!(COMPOSE_SYSTEM_PROMPT.contains("<image1>, <image2>") && COMPOSE_SYSTEM_PROMPT.contains("new image"));
+ assert!(!COMPOSE_LABEL_PROMPT.contains("unchanged"));
+ // Long scenes are allowed for, within the token cap (~1.4 tokens a word at most).
+ assert!(COMPOSE_SYSTEM_PROMPT.contains("280") && T2I_SYSTEM_PROMPT.contains("250"));
+ assert!(300.0 * 1.4 < MAX_TOKENS as f64);
}
#[test]
diff --git a/crates/qls-core/src/pipeline.rs b/crates/qls-core/src/pipeline.rs
index 69a3e97..c8f7294 100644
--- a/crates/qls-core/src/pipeline.rs
+++ b/crates/qls-core/src/pipeline.rs
@@ -157,7 +157,7 @@ pub fn effective_prompt(plan: &Plan, prompt: &str) -> String {
}
}
-/// The prompt sent for an enhanced job (text-to-image, edit, combine): the enhancer's text,
+/// The prompt sent for an enhanced job (text-to-image, compose, edit, combine): the enhancer's text,
/// wrapped for transparency when the user's own words asked for it (not the rewrite's, which
/// may mention "transparent glass").
pub fn enhanced_prompt(original: &str, enhanced: &str) -> String {
@@ -211,7 +211,7 @@ pub fn prepare(plan: &Plan, prompt: &str, seed: i64, images: &[LoadedImage], mas
match plan.mode {
ResolvedMode::Generate => {}
- ResolvedMode::Edit | ResolvedMode::MultiReference => {
+ ResolvedMode::Edit | ResolvedMode::MultiReference | ResolvedMode::Compose => {
need_images(plan.references.len())?;
for r in &plan.references {
let img = &images[r.index].pixels;
diff --git a/crates/qls-core/src/planner.rs b/crates/qls-core/src/planner.rs
index a8554d7..6243aaa 100644
--- a/crates/qls-core/src/planner.rs
+++ b/crates/qls-core/src/planner.rs
@@ -28,6 +28,9 @@ pub enum Mode {
Inpaint,
Outpaint,
MultiReference,
+ /// A new image that uses the input images as references (people, products, a style):
+ /// sized like text-to-image, not like image 1.
+ Compose,
Upscale,
}
@@ -39,6 +42,7 @@ pub enum ResolvedMode {
Inpaint,
Outpaint,
MultiReference,
+ Compose,
Upscale,
}
@@ -50,6 +54,7 @@ impl ResolvedMode {
Self::Inpaint => "Inpainting",
Self::Outpaint => "Outpainting",
Self::MultiReference => "Multi-reference",
+ Self::Compose => "New image from references",
Self::Upscale => "Upscale",
}
}
@@ -245,7 +250,8 @@ pub struct GenerationRequest {
pub quality: Quality,
#[serde(default)]
pub resolution: ResolutionMode,
- /// "auto", "1:1", "16:9", ... (text-to-image, edit, multi-reference; image 1's shape when unset).
+ /// "auto", "1:1", "16:9", ... (text-to-image, compose, edit, multi-reference). Unset: image 1's
+ /// shape for edits and combines; from the prompt, else square, for new images.
#[serde(default)]
pub aspect_ratio: Option<String>,
#[serde(default)]
@@ -272,9 +278,17 @@ pub struct GenerationRequest {
#[serde(default)]
pub private: bool,
/// Prompt enhancer: the text encoder's LLM rewrites `prompt` into a full prompt before
- /// generating (text-to-image, edits, combines; engines with text generation only).
+ /// generating (text-to-image, compositions, edits, combines; engines with text generation only).
#[serde(default)]
pub enhance: bool,
+ /// Prompt+ review: with `enhance`, only write the prompt. The job ends with it in
+ /// `JobView::enhanced_prompt` and no image, so the user can read and change it first.
+ #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+ pub enhance_only: bool,
+ /// The user's own words when `prompt` was written by Prompt+ in a review (and maybe changed
+ /// by the user since): kept as the record's original prompt.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub enhanced_from: Option<String>,
/// The user's LoRAs to use, by id or name (Settings → LoRA); sent by the app only, None =
/// no LoRA (MCP and the HTTP API don't use LoRAs for now). Not used by upscales.
#[serde(default, skip_serializing_if = "Option::is_none")]
@@ -822,6 +836,9 @@ fn detect_mode(req: &GenerationRequest, inputs: &PlanInputs) -> Result<(Resolved
need(n >= 1, "Add at least one reference image.")?;
explicit(ResolvedMode::MultiReference, "Selected")
}
+ Mode::Compose => {
+ if n == 0 { explicit(ResolvedMode::Generate, "Selected (no reference images)") } else { explicit(ResolvedMode::Compose, "Selected") }
+ }
Mode::Inpaint => {
need(n >= 1, "Add an image to inpaint.")?;
need(has_mask, "Paint the area to change first.")?;
@@ -879,6 +896,9 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSetti
return Err(AppError::invalid(format!("Use at most {} reference images.", rec.max_references)));
}
let (mode, auto_mode, mode_reason) = detect_mode(req, inputs)?;
+ if req.enhance_only && !(req.enhance && crate::enhancer::applies(mode)) {
+ return Err(AppError::invalid("Prompt+ writes prompts for new images, edits and combines only."));
+ }
let inpaint_action = (mode == ResolvedMode::Inpaint).then(|| req.inpaint_action.resolve(&req.prompt));
// Upscales and removals need no description.
let prompt_optional = mode == ResolvedMode::Upscale || inpaint_action == Some(InpaintAction::Remove);
@@ -941,7 +961,18 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSetti
let working: WorkingCanvas;
match mode {
- ResolvedMode::Generate => {
+ ResolvedMode::Generate | ResolvedMode::Compose => {
+ // A new image: sized from the chosen size, ratio or prompt, never from the
+ // references, which share the token budget with it (as in edits).
+ let refs: &[Size] = if mode == ResolvedMode::Compose { &inputs.image_sizes } else { &[] };
+ let mut cap = |wanted: u64, notes: &mut Vec<String>| {
+ if refs.is_empty() {
+ return cap_for_refs(wanted, 0.0, notes);
+ }
+ let a = cap_for_sources(wanted, refs, notes);
+ sources_reduced |= a < wanted;
+ a
+ };
let explicit_dims = match (req.width, req.height) {
(Some(w), Some(h)) => Some((w, h)),
_ => match req.aspect_ratio.as_deref().and_then(parse_aspect) {
@@ -958,7 +989,7 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSetti
}
let src = Size::new(w, h);
// Above the VRAM budget: render smaller, then enlarge to the exact size.
- let area = cap_for_refs(src.area(), 0.0, &mut notes);
+ let area = cap(src.area(), &mut notes);
working = plan_working_canvas(src, &CanvasLimits { min_side: 64, ..limits(area, rec) });
output = src;
} else {
@@ -972,11 +1003,16 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSetti
})
.unwrap_or((1.0, "1:1".into()));
let wanted = tier_area.unwrap_or(rec.area_balanced);
- let area = cap_for_refs(wanted, 0.0, &mut notes);
+ let area = cap(wanted, &mut notes);
let size = size_for_aspect(aspect, area, rec);
working = plan_working_canvas(size, &limits(size.area(), rec));
output = size;
}
+ // Each reference at most the reference cap and never larger than the output.
+ let ref_area = ref_cap.min(working.canvas.area());
+ for (i, s) in refs.iter().enumerate() {
+ references.push(RefPlan { index: i, source: *s, canvas: ref_canvas(*s, ref_area, rec) });
+ }
}
ResolvedMode::Edit | ResolvedMode::MultiReference => {
let first = inputs.image_sizes[0];
@@ -1127,7 +1163,7 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSetti
let large_gpu = !inputs.unified_memory && inputs.vram_total_mib.map(|m| m as f64 / 1024.0 >= 15.0).unwrap_or(false);
let vae_tile = (vae_tiling && large_gpu && !quick_upscale && total_area > LARGE_GPU_VAE_TILE_AREA)
.then(|| vae_decode_tile(working.canvas, LARGE_GPU_VAE_TILE_AREA));
- if (working.content.area() as f64) < output.area() as f64 * 0.98 && matches!(mode, ResolvedMode::Generate | ResolvedMode::Edit | ResolvedMode::MultiReference) {
+ if (working.content.area() as f64) < output.area() as f64 * 0.98 && matches!(mode, ResolvedMode::Generate | ResolvedMode::Edit | ResolvedMode::MultiReference | ResolvedMode::Compose) {
notes.push(format!(
"Rendered at {}×{}, then enlarged to {}×{} with {}.",
working.content.width,
@@ -1188,7 +1224,7 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSetti
upscale,
custom_sigmas: if quick_upscale { Vec::new() } else { TURBO_SIGMAS.to_vec() },
vae_tile,
- reference_detail: matches!(mode, ResolvedMode::Edit | ResolvedMode::MultiReference | ResolvedMode::Inpaint).then(|| adv.reference_detail.unwrap_or_default()),
+ reference_detail: matches!(mode, ResolvedMode::Edit | ResolvedMode::MultiReference | ResolvedMode::Compose | ResolvedMode::Inpaint).then(|| adv.reference_detail.unwrap_or_default()),
})
}
@@ -1697,6 +1733,67 @@ mod tests {
}
}
+ #[test]
+ fn compose_is_sized_like_a_new_image_not_like_its_references() {
+ let budget = (planning_token_budget(Some(16303), false) * PIXELS_PER_TOKEN) as f64 * 1.05;
+ let mut r = req("the woman from image 1 drinking the coffee from image 2 in a bar");
+ r.mode = Mode::Compose;
+ // A small portrait and a product shot: Balanced, square (no ratio chosen or in the prompt).
+ let sizes = [(480, 720), (1200, 1200)];
+ let p = plan(&r, &inputs(&sizes), &rec()).unwrap();
+ assert_eq!((p.mode, p.auto_mode), (ResolvedMode::Compose, false));
+ assert_eq!(p.output, Size::new(1536, 1536), "the preset's size, not image 1's");
+ let idx: Vec<usize> = p.references.iter().map(|r| r.index).collect();
+ assert_eq!(idx, vec![0, 1]);
+ for x in &p.references {
+ assert!(x.canvas.canvas.area() <= STANDARD_REFERENCE_AREA && x.canvas.canvas.is_aligned(32));
+ }
+ assert!((p.working.area() + p.references.iter().map(|r| r.canvas.canvas.area()).sum::<u64>()) as f64 <= budget);
+ assert_eq!(p.reference_detail, Some(ReferenceDetail::Standard));
+ assert_eq!(p.strength, None);
+ // The chosen ratio, a ratio in the prompt and an exact size all apply, as in text-to-image.
+ r.aspect_ratio = Some("16:9".into());
+ let p = plan(&r, &inputs(&sizes), &rec()).unwrap();
+ assert!((p.output.width as f64 / p.output.height as f64 / (16.0 / 9.0) - 1.0).abs() < 0.02, "{:?}", p.output);
+ r.aspect_ratio = None;
+ r.prompt = "poster 9:16 of the person from image 1".into();
+ assert!(plan(&r, &inputs(&sizes), &rec()).unwrap().output.height > plan(&r, &inputs(&sizes), &rec()).unwrap().output.width);
+ r.resolution = ResolutionMode::Custom;
+ (r.width, r.height) = (Some(1200), Some(800));
+ assert_eq!(plan(&r, &inputs(&sizes), &rec()).unwrap().output, Size::new(1200, 800));
+ // Quality on 16 GB: native 2K shares the budget with the references.
+ let mut r = req("both of them on a beach");
+ (r.mode, r.quality) = (Mode::Compose, Quality::Quality);
+ let p = plan(&r, &inputs(&[(4000, 3000), (4000, 3000), (3000, 4000)]), &rec()).unwrap();
+ assert!((p.working.area() + p.references.iter().map(|r| r.canvas.canvas.area()).sum::<u64>()) as f64 <= budget);
+ assert!(p.references.iter().all(|x| x.canvas.canvas.area() <= p.working.area()));
+ // Full detail: references up to the output's area.
+ r.advanced.reference_detail = Some(ReferenceDetail::Full);
+ r.quality = Quality::Fast;
+ let p = plan(&r, &inputs(&[(4000, 3000)]), &rec()).unwrap();
+ assert!(p.references[0].canvas.canvas.area() <= p.working.area() && p.references[0].canvas.canvas.area() > STANDARD_REFERENCE_AREA / 2);
+ // Without images it is text-to-image.
+ let p = plan(&r, &inputs(&[]), &rec()).unwrap();
+ assert!(p.mode == ResolvedMode::Generate && p.references.is_empty());
+ }
+
+ #[test]
+ fn prompt_review_needs_the_enhancer_and_a_prompt_it_writes() {
+ let mut r = req("un gatto");
+ r.enhance_only = true;
+ assert!(plan(&r, &inputs(&[]), &rec()).is_err(), "review without Prompt+");
+ r.enhance = true;
+ assert!(plan(&r, &inputs(&[]), &rec()).is_ok());
+ r.mode = Mode::Compose;
+ assert_eq!(plan(&r, &inputs(&[(800, 800)]), &rec()).unwrap().mode, ResolvedMode::Compose);
+ r.mode = Mode::Outpaint;
+ r.outpaint = Some(OutpaintSpec { left: 0.2, right: 0.0, top: 0.0, bottom: 0.0, units: Default::default() });
+ assert!(plan(&r, &inputs(&[(800, 800)]), &rec()).is_err(), "expansions wrap the prompt themselves");
+ // The fields stay out of saved requests unless used.
+ let v = serde_json::to_value(req("x")).unwrap();
+ assert!(v.get("enhance_only").is_none() && v.get("enhanced_from").is_none());
+ }
+
#[test]
fn too_many_references() {
let sizes: Vec<(u32, u32)> = (0..11).map(|_| (512, 512)).collect();
diff --git a/crates/qls-service/src/api.rs b/crates/qls-service/src/api.rs
index c776d88..7890ea9 100644
--- a/crates/qls-service/src/api.rs
+++ b/crates/qls-service/src/api.rs
@@ -476,7 +476,7 @@ async fn get_config(State(s): St) -> Json<AppConfig> {
/// The prompt enhancer's built-in system prompts (Settings shows them for "" and restores them).
async fn enhancer_defaults() -> Json<Value> {
use qls_core::enhancer;
- Json(json!({ "t2i": enhancer::T2I_SYSTEM_PROMPT, "edit": enhancer::EDIT_SYSTEM_PROMPT, "max_chars": enhancer::MAX_SYSTEM_PROMPT_CHARS }))
+ Json(json!({ "t2i": enhancer::T2I_SYSTEM_PROMPT, "edit": enhancer::EDIT_SYSTEM_PROMPT, "compose": enhancer::COMPOSE_SYSTEM_PROMPT, "max_chars": enhancer::MAX_SYSTEM_PROMPT_CHARS }))
}
async fn put_config(State(s): St, Json(cfg): Json<AppConfig>) -> ApiResult<Json<Value>> {
@@ -738,8 +738,11 @@ async fn run_simple(s: Arc<AppState>, mode: Mode, op: SimpleOp, wait: bool) -> A
Ok(Json(wait_for(&s, &j.id, Duration::from_secs(3600)).await?))
}
+/// A new image; with `images`, a new image that uses them as references (sized like
+/// text-to-image, not like image 1).
async fn op_generate(State(s): St, Query(q): Query<OpQ>, Json(op): Json<SimpleOp>) -> ApiResult<Json<JobView>> {
- run_simple(s, Mode::Generate, op, q.wait.unwrap_or(true)).await
+ let mode = if op.images.is_empty() && op.image.is_none() { Mode::Generate } else { Mode::Compose };
+ run_simple(s, mode, op, q.wait.unwrap_or(true)).await
}
async fn op_edit(State(s): St, Query(q): Query<OpQ>, Json(op): Json<SimpleOp>) -> ApiResult<Json<JobView>> {
let mode = if op.images.len() + op.image.is_some() as usize > 1 { Mode::MultiReference } else { Mode::Edit };
diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md
index cc5dd99..41c9306 100644
--- a/docs/engineering-notes.md
+++ b/docs/engineering-notes.md
@@ -269,6 +269,30 @@ edits) before the image is made, so there is no second model in memory.
- **Sampling:** Qwen3-VL's values (temperature 0.7, top-p 0.8, top-k 20, presence penalty 1.5 counted
on generated tokens only), seeded with a portable RNG, so the same seed gives the same text on every
platform. Regenerate makes a new prompt and a new seed; greedy is the engine default and test mode.
+- **Length:** the prompts ask for a length that fits the request (t2i ~80-150 words, up to ~250 for
+ crowded scenes; edits 20-60, up to ~150 for several changes; compose 100-200, up to ~300). The token
+ cap is 1024 (was 512, which cut crowded scenes mid-sentence; ~8 s at ~127 tok/s). sd.cpp's Qwen-Image
+ conditioning does not truncate the prompt.
+- **Three system prompts:** text-to-image, edit (edits and combines, where image 1 is changed) and
+ compose (a new image that uses the images as references, `mode: compose`). Compose runs in two
+ steps: each reference is labelled alone (a short list of its own features, never its place, pose or
+ what it holds), then the scene is written from the request and the labels, without the images. Shown
+ the images, the 8B described the references instead of the requested scene with every system prompt
+ tried; from labels it follows the request. The image model still gets the references, so identities
+ come from them. No "keep … unchanged" sentence (it turns a composition into an edit of image 1).
+ Cost: ~0.3 s per reference plus the scene. Still to be A/B-tested on composition cases.
+- **Review first:** `enhance_only` runs a job that stops after the prompt (no image, nothing saved); the
+ app streams it into the prompt box. The next job sends the text with `enhanced_from` (the user's
+ words), so the record keeps both and nothing is rewritten twice.
+
+### New image from references (compose)
+
+`mode: compose` is a new image whose size follows text-to-image (chosen size, ratio, a ratio in the
+prompt, else square, at the quality preset), never image 1's: an edit's output takes image 1's shape
+and, in Auto, at most its area, so a small reference gave a small result. The references share the
+token budget with the output as in edits (`cap_for_sources`), each at most the reference cap
+(Standard 1 MP) and never larger than the output. In the app, **New image** with images added sends
+compose; **Edit image** keeps today's edit/combine.
## HDR
diff --git a/docs/http-api.md b/docs/http-api.md
index 26cf170..86a26e4 100644
--- a/docs/http-api.md
+++ b/docs/http-api.md
@@ -72,7 +72,12 @@ Simple-operation fields: `prompt`, `image` / `images[]`, `mask`, `action`
(`edit|remove|replace|add`, inpainting), `width`, `height`, `aspect_ratio`, `quality`
(`fast|balanced|quality`), `seed`, `output_path`, `preserve_dimensions`, `private`,
`left/right/top/bottom` + `units` (`pixels|percent`) for outpainting, `scale` for upscaling.
-Full requests (`/jobs`) also accept `"mode": "upscale"` with `"upscale": {"scale" | "width"/"height"}`.
+`/generate` with `images[]` makes a new image that uses them as references (people, products, a
+style), sized like any new image; `/edit` with several images edits image 1 with the others.
+Full requests (`/jobs`) also accept `"mode": "upscale"` with `"upscale": {"scale" | "width"/"height"}`,
+`"mode": "compose"` (the references case of `/generate`), and with `"enhance": true` (Prompt+)
+`"enhance_only": true`: the job only writes the prompt (`enhanced_prompt` in the job, no image), so it
+can be read and changed; send it back as `prompt` with `"enhanced_from"` set to your original words.
## Input images
diff --git a/docs/prompting.md b/docs/prompting.md
index 22b33b9..8e52d75 100644
--- a/docs/prompting.md
+++ b/docs/prompting.md
@@ -168,9 +168,10 @@ Brush over the part you want to change, pick an action, and write only about tha
Paint a bit larger than the object, including its shadow. Everything outside the brush stays
exactly as it was.
-### Combine images
+### Combine images (Edit image)
-Add several images and call them **image 1, image 2…** in the order they appear:
+With **Edit image**, image 1 is the photo being changed and the others bring something into it.
+Call them **image 1, image 2…** in the order they appear:
> Place the white sneaker from image 2 on the rug in image 1, in front of the armchair, with
> natural shadows matching the room light. Keep the room from image 1 unchanged.
@@ -178,6 +179,18 @@ Add several images and call them **image 1, image 2…** in the order they appea
The result takes the shape of image 1. Say which image gives what (the person, the place, the
light, the style).
+### A new image from references (New image)
+
+With **New image**, the images you add are references: a person, a product, a pet, a style. The
+result is a new picture with its own scene, framing and light, sized by the quality and aspect
+ratio you choose (not by image 1). Describe the whole scene and say what to take from each image:
+
+> A photo of the woman from image 1 sitting at a café table by a sunny window, holding the
+> coffee cup from image 2 near her face, looking at the camera.
+
+A reference's background stays out unless you ask for it. Prompt+ looks at the references and
+writes the details that make them recognizable.
+
### Expand a photo
Choose how much to extend on each side; the prompt is optional. Describe what should continue
diff --git a/mcp/README.md b/mcp/README.md
index f789d13..0a65e67 100644
--- a/mcp/README.md
+++ b/mcp/README.md
@@ -40,11 +40,14 @@ clutter from screenshot.png"*. The first call takes about a minute while the mod
## Tools
+Prompts are used exactly as your assistant writes them: Kokon's own prompt writer (Prompt+) does not
+run for MCP, so the assistant writes the full description. The tool descriptions tell it how.
+
| Tool | What it does |
| --- | --- |
-| `generate_image` | Text to image. Size chosen automatically, or set width/height or aspect ratio. |
+| `generate_image` | Text to image, optionally with up to 10 reference images (a person, a product, a style) in a new scene. Size chosen automatically, or set width/height or aspect ratio. |
| `edit_image` | Edit an image with an instruction. Keeps its size; never overwrites the input. |
-| `edit_images` | Create an image from up to 10 reference images ("image 1", "image 2"...). |
+| `edit_images` | Edit image 1 with the help of up to 9 more images ("image 1", "image 2"...). |
| `inpaint_image` | Change only a masked area: edit, remove, replace or add something. |
| `outpaint_image` | Extend an image beyond its borders. |
| `upscale_image` | Enlarge an image (default 2x, up to 8192 px). |
diff --git a/mcp/src/index.ts b/mcp/src/index.ts
index d93593b..009e916 100644
--- a/mcp/src/index.ts
+++ b/mcp/src/index.ts
@@ -16,7 +16,7 @@ const DESCRIPTIONS: Record<keyof typeof schemas, { title: string; description: s
generate_image: {
title: "Generate image",
description:
- "Generate an image from a text prompt with the local Qwen-Image 2.1 model. Dimensions are chosen automatically (aspect ratio can be inferred from the prompt, e.g. '16:9 hero image') unless width/height or aspect_ratio are given. Returns the absolute path of the saved PNG. Runs fully offline; typically 45 s–4 min.",
+ "Generate an image from a text prompt with the local Qwen-Image 2.1 model, optionally using reference images (a person, a product, a style) in a new scene. Write the full, detailed prompt yourself (see the prompt field): it is used as is. Dimensions are chosen automatically (aspect ratio can be inferred from the prompt, e.g. '16:9 hero image') unless width/height or aspect_ratio are given. Returns the absolute path of the saved PNG. Runs fully offline; typically 45 s–4 min.",
},
edit_image: {
title: "Edit image",
@@ -26,7 +26,7 @@ const DESCRIPTIONS: Record<keyof typeof schemas, { title: string; description: s
edit_images: {
title: "Edit with multiple references",
description:
- "Create an image from several reference images (up to 10) and an instruction. Order matters: refer to them as image 1, image 2, ... in the prompt. The output follows image 1's aspect ratio unless width/height or aspect_ratio are given.",
+ "Edit image 1 with the help of other images (up to 10 in all) and an instruction, e.g. put the product from image 2 in the hand of the person in image 1. Order matters: refer to them as image 1, image 2, ... in the prompt. The output follows image 1's aspect ratio unless width/height or aspect_ratio are given. For a new scene that only uses the images as references, use generate_image with reference_images.",
},
outpaint_image: {
title: "Expand image (outpaint)",
diff --git a/mcp/src/tools.ts b/mcp/src/tools.ts
index bb1f31e..12e465a 100644
--- a/mcp/src/tools.ts
+++ b/mcp/src/tools.ts
@@ -23,7 +23,14 @@ const preview = z.boolean().describe("Also return a small JPEG preview in the to
export const schemas = {
generate_image: {
- prompt: prompt.describe("What to generate, in natural language"),
+ prompt: prompt.describe(
+ "The final prompt, written by you in English and used as is (Kokon does not rewrite it): one paragraph of about 60-200 words describing the finished image: medium and style first, the subject and what it does, the setting and background, composition and camera view, and the light. Copy any text to show exactly, in double quotes. No quality tags or sizes. With reference_images: refer to them as image 1, image 2..., say what to take from each (a person's face and look, a product with its shape, colours and logo, a style) and describe the new scene around them; never ask to keep a reference unchanged.",
+ ),
+ reference_images: z
+ .array(z.string().min(1))
+ .max(10)
+ .optional()
+ .describe("Optional images the new image uses (a person, a product, a place, a style), in order; refer to them as image 1, image 2, ... in the prompt. The output is sized like any new image, not like the references. To change an image instead, use edit_image or edit_images."),
width: dim.optional().describe("Output width in pixels (needs height too). Omit to choose automatically."),
height: dim.optional().describe("Output height in pixels (needs width too)."),
aspect_ratio: aspect.optional(),
@@ -34,7 +41,9 @@ export const schemas = {
},
edit_image: {
image_path: z.string().min(1).describe("Image to edit (absolute, or relative to the project)"),
- prompt: prompt.describe("The change to make, e.g. 'make the background nighttime, keep the foreground unchanged'"),
+ prompt: prompt.describe(
+ "The edit instruction, written by you in English and used as is (Kokon does not rewrite it): start with the operation (Change, Replace, Remove, Add, Turn...), say exactly what changes, where, and what it becomes, in 20-60 words; describe only what changes and end with 'Keep everything else in the image unchanged.' For a whole-image style or mood change, end with 'Keep the composition and the subjects unchanged.' instead.",
+ ),
output_path: outputPath.optional(),
quality: quality.optional(),
preserve_dimensions: z.boolean().optional().describe("Keep the input's exact width/height (default true)"),
@@ -43,7 +52,9 @@ export const schemas = {
},
edit_images: {
image_paths: z.array(z.string().min(1)).min(1).max(10).describe("Reference images in order; refer to them as image 1, image 2, ... in the prompt"),
- prompt: prompt.describe("e.g. 'Use the person from image 1, the clothing from image 2 and the lighting of image 3'"),
+ prompt: prompt.describe(
+ "The edit instruction, written by you in English and used as is (Kokon does not rewrite it): image 1 is the image being changed; start with Place or Combine, say what is taken from each image (image 2, image 3...) and exactly where it goes in image 1, with matching light and shadows, and end with 'Keep everything else in image 1 unchanged.'",
+ ),
width: dim.optional(),
height: dim.optional(),
aspect_ratio: aspect.optional(),
@@ -162,7 +173,8 @@ export function label(j: JobView): string {
}
async function runJob(ctx: ToolContext, body: Record<string, unknown>, includePreview: boolean): Promise<ToolResult> {
- const job = await ctx.client.call<JobView>("POST", "/jobs", { ...body, workspace: ctx.cwd, client: "mcp" });
+ // The calling model writes the prompt: Kokon's own prompt writer (Prompt+) never runs for MCP.
+ const job = await ctx.client.call<JobView>("POST", "/jobs", { ...body, enhance: false, workspace: ctx.cwd, client: "mcp" });
let last = "";
let cancelled = false;
const onAbort = () => {
@@ -245,13 +257,15 @@ function validateDims(w?: number, h?: number) {
export const handlers = {
async generate_image(a: Args<"generate_image">, ctx: ToolContext) {
validateDims(a.width, a.height);
- const out = a.output_path ? checkOutput(a.output_path, ctx.cwd, await roots(ctx)) : undefined;
+ const r = await roots(ctx);
+ const refs = (a.reference_images ?? []).map((x) => checkInput(x, ctx.cwd, r));
+ const out = a.output_path ? checkOutput(a.output_path, ctx.cwd, r) : undefined;
return runJob(
ctx,
{
prompt: a.prompt,
- mode: "generate",
- images: [],
+ mode: refs.length ? "compose" : "generate",
+ images: refs,
width: a.width,
height: a.height,
resolution: a.width ? "custom" : "auto",
diff --git a/mcp/test/tools.test.ts b/mcp/test/tools.test.ts
index 9b9f4fe..b2f34e7 100644
--- a/mcp/test/tools.test.ts
+++ b/mcp/test/tools.test.ts
@@ -18,6 +18,8 @@ describe("input validation", () => {
expect(obj("generate_image").safeParse({ prompt: "x", quality: "ultra" }).success).toBe(false);
expect(obj("generate_image").safeParse({ prompt: "x", quality: "max" }).success).toBe(false);
expect(obj("generate_image").safeParse({ prompt: "x", seed: -2 }).success).toBe(false);
+ expect(obj("generate_image").safeParse({ prompt: "x", reference_images: ["a.png", "b.png"] }).data?.reference_images).toEqual(["a.png", "b.png"]);
+ expect(obj("generate_image").safeParse({ prompt: "x", reference_images: Array(11).fill("a.png") }).success).toBe(false);
});
it("edit_images limits and order", () => {
expect(obj("edit_images").safeParse({ prompt: "x", image_paths: [] }).success).toBe(false);
@@ -28,6 +30,22 @@ describe("input validation", () => {
const r = obj("outpaint_image").parse({ image_path: "a.png", prompt: "x", left: 256 });
expect(r).toMatchObject({ left: 256, right: 0, top: 0, bottom: 0, units: "pixels" });
});
+ it("sends the caller's prompt as written: Kokon's Prompt+ never runs for MCP", async () => {
+ const sent: Record<string, unknown>[] = [];
+ const client = {
+ call: async (method: string, _path: string, body?: Record<string, unknown>) => {
+ if (method === "POST" && body) sent.push(body);
+ return { id: "j", status: "failed", error: { code: "x", message: "stop here" }, results: [], notes: [], queue_position: 0, plan: null, stage: null, step: null };
+ },
+ };
+ const ctx = { client: client as never, cwd: process.cwd(), progress: () => {} };
+ await handlers.generate_image({ prompt: "A watercolour fox in snow." } as never, ctx);
+ await handlers.generate_image({ prompt: "x", enhance: true } as never, ctx);
+ expect(sent.map((b) => [b.prompt, b.enhance, b.mode])).toEqual([
+ ["A watercolour fox in snow.", false, "generate"],
+ ["x", false, "generate"],
+ ]);
+ });
it("width without height is rejected before any service call", async () => {
const ctx = { client: {} as never, cwd: process.cwd(), progress: () => {} };
const res = await handlers.generate_image({ prompt: "x", width: 512 } as never, ctx).catch(toErrorResult);
diff --git a/src/components/Composer.tsx b/src/components/Composer.tsx
index 88c4134..ada82c9 100644
--- a/src/components/Composer.tsx
+++ b/src/components/Composer.tsx
@@ -1,10 +1,10 @@
-import { ArrowUp, Brush, Check, ChevronDown, Expand, FolderOpen, Gauge, ImagePlus, Layers, Lightbulb, Maximize, Pencil, Settings2, SlidersHorizontal, Sparkles, WandSparkles, X } from "lucide-react";
+import { ArrowUp, Brush, Check, ChevronDown, Expand, Eye, FolderOpen, Gauge, ImagePlus, Layers, Lightbulb, Maximize, Pencil, Settings2, SlidersHorizontal, Sparkles, Square, Undo2, WandSparkles, X } from "lucide-react";
import { useEffect, useMemo, useRef, useState } from "react";
import { api, urls } from "../lib/api";
-import { activeLoras, activeOverrides, aspectLabel, buildRequest, enhancerApplies, expansionPixels, formatDuration, hasOutpaint, imageName, MAX_LORAS, moveRef, needsPrompt, parseRatio, toggleLora, type Ref } from "../lib/logic";
+import { activeLoras, activeOverrides, aspectLabel, buildRequest, composing, editing, enhancerApplies, expansionPixels, formatDuration, hasOutpaint, imageName, MAX_LORAS, moveRef, needsPrompt, parseRatio, toggleLora, wantsPromptReview, type Ref } from "../lib/logic";
import { native } from "../lib/native";
import {
- addAsReference, addInputs, editShownImage, enhancerAvailable, getState, itemSource, openSettings, selectedItem, sessionLabels, setProjectLoras, setState, startNewImage, submitComposer, toastError, updateComposer, useStore, type SessionItem,
+ addAsReference, addInputs, cancelPromptReview, editShownImage, enhancerAvailable, getState, itemSource, openSettings, selectedItem, sessionLabels, setProjectLoras, setState, startNewImage, submitComposer, toastError, undoEnhancedPrompt, updateComposer, useStore, type SessionItem,
} from "../lib/store";
import type { InpaintAction, Plan, Quality } from "../lib/types";
import { AdvancedPanel } from "./Advanced";
@@ -122,18 +122,26 @@ function RefStrip() {
);
}
-/** Edit image | New image: whether the prompt changes an image or makes a new one. */
+/** Edit image | New image: whether the prompt changes an image or makes a new one (with the
+ * images in the prompt as references). */
function ModeSwitch({ editing }: { editing: boolean }) {
const sel = useStore(selectedItem);
const session = useStore((s) => s.session);
const img = sel && (sel.gen || sel.input) ? sel : [...session].reverse().find((i) => i.gen || i.input);
- const name = img ? imageName(sessionLabels(session)[img.key]).toLowerCase() : "";
+ const refs = useStore((s) => s.composer.refs);
+ const name = refs.length ? "image 1 of the prompt" : img ? `${imageName(sessionLabels(session)[img.key]).toLowerCase()}, the image shown` : "";
return (
<div className="mode-switch" role="radiogroup" aria-label="What the prompt does">
- <button className={editing ? "" : "on"} role="radio" aria-checked={!editing} onClick={() => editing && startNewImage()} title="Make a new image from the prompt alone; your images stay in the timeline">
+ <button
+ className={editing ? "" : "on"}
+ role="radio"
+ aria-checked={!editing}
+ onClick={() => startNewImage()}
+ title="Make a new image. Images you add are references (a person, a product, a style) for it, not edited; your images stay in the timeline"
+ >
<Sparkles size={14} /> <span className="lbl">New image</span>
</button>
- <button className={editing ? "on" : ""} role="radio" aria-checked={editing} onClick={() => !editing && editShownImage()} title={editing ? "The prompt edits this image" : `Edit ${name}, the image shown`}>
+ <button className={editing ? "on" : ""} role="radio" aria-checked={editing} onClick={() => !editing && editShownImage()} title={editing ? "The prompt edits this image" : `Edit ${name}`}>
<Pencil size={14} /> <span className="lbl">Edit image</span>
</button>
</div>
@@ -153,7 +161,21 @@ function TargetBar() {
<ModeSwitch editing={false} />
<span className="target-text">
<span className="what">New image</span>
- <span className="sub">Made from the prompt alone</span>
+ <span className="sub">From the prompt; images you add are references</span>
+ </span>
+ </div>
+ );
+ }
+
+ if (composing(c)) {
+ const n = c.refs.length;
+ return (
+ <div className="target create">
+ <ModeSwitch editing={false} />
+ <RefStrip />
+ <span className="target-text">
+ <span className="what">New image with {n === 1 ? "1 reference" : `${n} references`}</span>
+ <span className="sub">{n > 1 ? "Refer to them as image 1, image 2… in the prompt" : "Say what to take from it: the person, the product, the style…"}</span>
</span>
</div>
);
@@ -208,6 +230,7 @@ function TargetBar() {
function AddImage() {
const session = useStore((s) => s.session);
const refs = useStore((s) => s.composer.refs);
+ const create = useStore((s) => s.composer.create);
const labels = useMemo(() => sessionLabels(session), [session]);
const used = new Set(refs.map((r) => r.source));
const candidates = session.filter((i) => {
@@ -215,7 +238,9 @@ function AddImage() {
return s && !used.has(s);
});
const browse = async () => importPaths(await native.pickImages());
- const title = refs.length ? "Add a reference image" : "Add an image to edit";
+ // In a project, images added while not editing are references for a new image.
+ const asReference = refs.length > 0 || create || session.length > 0;
+ const title = asReference ? "Add a reference image" : "Add an image to edit";
if (!candidates.length) {
return (
@@ -235,7 +260,7 @@ function AddImage() {
>
{(close) => (
<div className="add-menu">
- <div className="label">{refs.length ? "Add an image as reference" : "Edit an image"}</div>
+ <div className="label">{asReference ? (refs.length && !create ? "Add an image as reference" : "Add a reference for the new image") : "Edit an image"}</div>
<div className="add-grid">
{candidates.map((it: SessionItem) => (
<button key={it.key} title={it.gen?.prompt ?? imageName(labels[it.key])} onClick={() => (addAsReference(it), close())}>
@@ -355,6 +380,63 @@ function LoraBadge() {
);
}
+/** Prompt+: off; on (writes the prompt, then the image is made); or on with the prompt written
+ * into the box first, to read and change before pressing Enter again. */
+function PromptPlus() {
+ const c = useStore((s) => s.composer);
+ const mode = !c.enhance ? "off" : c.enhanceReview ? "review" : "write";
+ const title =
+ mode === "off"
+ ? "Prompt+: let the model rewrite a short prompt, in any language, as a detailed English description before making the image. Adds a few seconds."
+ : mode === "write"
+ ? "Prompt+ on: before making the image, the model rewrites your prompt as a detailed English description (looking at your images). You see it being written; the result keeps both."
+ : "Prompt+ on, review first: the model writes the detailed prompt into the box; change it if you like, then press Enter to make the image.";
+ const pick = (m: "off" | "write" | "review") => updateComposer({ enhance: m !== "off", enhanceReview: m === "off" ? c.enhanceReview : m === "review" });
+ return (
+ <Popover
+ className="prompt-plus"
+ trigger={(open, toggle) => (
+ <button className={`pill toggle ${c.enhance || open ? "on" : ""}`} onClick={toggle} title={title} aria-label={`Prompt+: ${mode === "off" ? "off" : mode === "write" ? "on" : "on, review first"}`}>
+ <WandSparkles size={15} />
+ <span className="lbl">Prompt+</span>
+ {mode === "review" && <Eye size={13} aria-hidden />}
+ <ChevronDown size={13} className="chev" />
+ </button>
+ )}
+ >
+ {(close) => (
+ <>
+ <div className="label">Prompt+</div>
+ <Option selected={mode === "off"} label="Off" onClick={() => (pick("off"), close())} />
+ <Option selected={mode === "write"} label="On" sub="writes, then makes" onClick={() => (pick("write"), close())} />
+ <Option selected={mode === "review"} label="Review first" sub="you edit it first" onClick={() => (pick("review"), close())} />
+ <button className="opt" onClick={() => (close(), openSettings("general"))}>
+ <span className="check">
+ <Settings2 size={15} />
+ </span>
+ <span>Prompt+ instructions…</span>
+ </button>
+ </>
+ )}
+ </Popover>
+ );
+}
+
+/** Under the prompt: the prompt in the box was written by Prompt+ from the user's words. */
+function EnhancedFrom({ words }: { words: string }) {
+ return (
+ <div className="enhanced-from">
+ <WandSparkles size={12} aria-hidden />
+ <span className="text" title={words}>
+ Written by Prompt+ from “{words}”. Change it if you like; Enter makes the image.
+ </span>
+ <button className="link" onClick={undoEnhancedPrompt} title="Back to your own words">
+ <Undo2 size={12} /> Undo
+ </button>
+ </div>
+ );
+}
+
export function Composer() {
const c = useStore((s) => s.composer);
const hasProject = useStore((s) => s.session.length > 0);
@@ -363,6 +445,11 @@ export function Composer() {
const hasImages = c.refs.length > 0;
const overrides = activeOverrides(c.advanced);
const canEnhance = useStore(enhancerAvailable) && enhancerApplies(c);
+ const newImage = !editing(c);
+ // Prompt+ review: the prompt it is writing streams into the box, which is read-only meanwhile.
+ const review = useStore((s) => s.review);
+ const reviewJob = useStore((s) => (s.review ? s.jobs[s.review.jobId] : undefined));
+ const reviewing = !!review;
useEffect(() => {
const ta = taRef.current;
@@ -383,14 +470,24 @@ export function Composer() {
});
ro.observe(ta);
return () => ro.disconnect();
- }, [c.prompt]);
+ }, [c.prompt, reviewJob?.enhanced_prompt]);
const outPx = hasOutpaint(c.outpaint) && c.refs[0] ? expansionPixels(c.outpaint!, c.refs[0].width, c.refs[0].height) : null;
- const placeholder = !hasImages
+ const placeholder = reviewing
+ ? reviewJob?.status === "starting_backend" || reviewJob?.status === "queued"
+ ? "Prompt+ is getting ready…"
+ : hasImages
+ ? "Prompt+ is looking at your images…"
+ : "Prompt+ is reading your idea…"
+ : !hasImages
? hasProject
? "Describe a new image: subject, what it's doing, setting…"
: "Describe an image (subject, action, setting) or drop one in to edit…"
+ : composing(c)
+ ? c.refs.length > 1
+ ? "Describe the new image: who or what from image 1, image 2… and the scene…"
+ : "Describe the new image with the reference: the scene, what it's doing…"
: c.refs.length > 1
? "Describe how to combine image 1, image 2…"
: c.mask
@@ -429,11 +526,13 @@ export function Composer() {
<textarea
id="prompt"
ref={taRef}
- className="prompt"
+ className={`prompt ${reviewing ? "writing" : ""}`}
rows={1}
- value={c.prompt}
+ value={reviewing ? (reviewJob?.enhanced_prompt ?? "") : c.prompt}
+ readOnly={reviewing}
placeholder={placeholder}
- onChange={(e) => updateComposer({ prompt: e.target.value })}
+ // Emptying a prompt Prompt+ wrote starts over with the user's own words.
+ onChange={(e) => updateComposer({ prompt: e.target.value, ...(e.target.value.trim() ? {} : { enhancedFrom: null }) })}
onKeyDown={(e) => {
if (e.key === "Enter" && !e.shiftKey && !e.nativeEvent.isComposing) {
e.preventDefault();
@@ -448,6 +547,7 @@ export function Composer() {
}}
spellCheck
/>
+ {c.enhancedFrom && !reviewing && <EnhancedFrom words={c.enhancedFrom} />}
<div className="controls">
<AddImage />
@@ -466,7 +566,7 @@ export function Composer() {
</button>
)}
>
- {(close) => <AspectGrid value={custom ? aspectLabel(c.customWidth, c.customHeight) : c.aspect} onPick={(r) => (pickAspect(r), close())} auto={{ sub: hasImages ? "Same as image 1" : "From the prompt, else square" }} />}
+ {(close) => <AspectGrid value={custom ? aspectLabel(c.customWidth, c.customHeight) : c.aspect} onPick={(r) => (pickAspect(r), close())} auto={{ sub: newImage ? "From the prompt, else square" : "Same as image 1" }} />}
</Popover>
)}
@@ -497,22 +597,7 @@ export function Composer() {
}
</Popover>
- {canEnhance && (
- <button
- className={`pill toggle ${c.enhance ? "on" : ""}`}
- role="switch"
- aria-checked={c.enhance}
- onClick={() => updateComposer({ enhance: !c.enhance })}
- title={
- c.enhance
- ? "Prompt+ on: before making the image, the model rewrites your prompt as a detailed English description (looking at your image for edits). You see it being written; the result keeps both. Click to turn off."
- : "Prompt+: let the model rewrite a short prompt, in any language, as a detailed English description before making the image. Adds a few seconds."
- }
- >
- <WandSparkles size={15} />
- <span className="lbl">Prompt+</span>
- </button>
- )}
+ {canEnhance && <PromptPlus />}
<LoraBadge />
@@ -543,9 +628,21 @@ export function Composer() {
<span className="plan-hint" title={hintTitle}>
{hint}
</span>
- <button className="send" title={hasImages ? "Apply (Enter)" : "Create (Enter)"} aria-label="Generate" disabled={!c.prompt.trim() && needsPrompt(c)} onClick={() => submitComposer()}>
- <ArrowUp size={18} strokeWidth={2.4} />
- </button>
+ {reviewing ? (
+ <button className="send" title="Stop Prompt+ (your prompt stays)" aria-label="Stop Prompt+" onClick={() => cancelPromptReview()}>
+ <Square size={14} strokeWidth={2.4} />
+ </button>
+ ) : (
+ <button
+ className="send"
+ title={wantsPromptReview(c) ? "Write the prompt with Prompt+ (Enter)" : newImage ? "Create (Enter)" : "Apply (Enter)"}
+ aria-label={wantsPromptReview(c) ? "Write the prompt" : "Generate"}
+ disabled={!c.prompt.trim() && needsPrompt(c)}
+ onClick={() => submitComposer()}
+ >
+ {wantsPromptReview(c) ? <WandSparkles size={17} strokeWidth={2.2} /> : <ArrowUp size={18} strokeWidth={2.4} />}
+ </button>
+ )}
</div>
</div>
</div>
diff --git a/src/components/Settings.tsx b/src/components/Settings.tsx
index 26df292..b0a9440 100644
--- a/src/components/Settings.tsx
+++ b/src/components/Settings.tsx
@@ -182,7 +182,7 @@ export function Settings() {
const [legacy, setLegacy] = useState<{ files: string[]; bytes: number } | null>(null);
const [dirty, setDirty] = useState(false);
const [theme, setTheme] = useState(themeChoice);
- const [enhancerDefaults, setEnhancerDefaults] = useState<{ t2i: string; edit: string; max_chars: number } | null>(null);
+ const [enhancerDefaults, setEnhancerDefaults] = useState<{ t2i: string; edit: string; compose?: string; max_chars: number } | null>(null);
const textGeneration = useStore((s) => s.status?.server.text_generation);
useEffect(() => {
@@ -373,11 +373,11 @@ export function Settings() {
</button>
</div>
- <h4 style={{ margin: "14px 0 0", fontSize: 14, fontWeight: 600 }}>Prompt enhancer</h4>
+ <h4 style={{ margin: "14px 0 0", fontSize: 14, fontWeight: 600 }}>Prompt+</h4>
<span className="muted" style={{ marginTop: -8 }}>
- With Enhance on (next to the prompt), the model's own language model rewrites your prompt before making the image, following these instructions. It
- always writes in English.
- {textGeneration === false && " The inference engine in use cannot write prompts: Enhance appears with an engine that can."}
+ With Prompt+ on (next to the prompt), the model's own language model rewrites your prompt before making the image, following these instructions. It
+ always writes in English. Its menu also lets you read and change the prompt before the image is made.
+ {textGeneration === false && " The inference engine in use cannot write prompts: Prompt+ appears with an engine that can."}
</span>
<div className="setting-card" style={{ alignItems: "flex-start" }}>
<span className="muted">
@@ -401,6 +401,14 @@ export function Settings() {
max={enhancerDefaults?.max_chars ?? 20000}
onChange={(v) => set({ enhancerEditPrompt: v })}
/>
+ <EnhancerPrompt
+ label="New images from references"
+ help="Used for a new image that uses your images as references (New image with images added). Each image is first labelled on its own; these instructions then write the scene from the labels."
+ value={cfg.enhancerComposePrompt ?? ""}
+ builtin={enhancerDefaults?.compose ?? null}
+ max={enhancerDefaults?.max_chars ?? 20000}
+ onChange={(v) => set({ enhancerComposePrompt: v })}
+ />
</>
)}
diff --git a/src/components/Stage.tsx b/src/components/Stage.tsx
index cbe98a7..e676419 100644
--- a/src/components/Stage.tsx
+++ b/src/components/Stage.tsx
@@ -25,6 +25,7 @@ export const MODE_ICON: Record<Mode | "lut", React.ReactNode> = {
generate: <Wand2 size={11} />,
edit: <Pencil size={11} />,
multi_reference: <Combine size={11} />,
+ compose: <Wand2 size={11} />,
inpaint: <Brush size={11} />,
outpaint: <Expand size={11} />,
upscale: <ImageUpscale size={11} />,
@@ -36,6 +37,7 @@ const MODE_DOING: Record<Mode, string> = {
generate: "Creating",
edit: "Editing",
multi_reference: "Combining images",
+ compose: "Creating from references",
inpaint: "Inpainting",
outpaint: "Expanding",
upscale: "Upscaling",
@@ -71,11 +73,12 @@ function Pending({ job, item, labels }: { job: JobView; item: SessionItem; label
const o = job.plan?.output;
const { ref, box } = useFit(o ? o.width / o.height : 1);
const session = useStore((s) => s.session);
- const src = item.request?.mode === "generate" ? undefined : item.request?.images?.[0];
+ // A new image (also one from references) has no source to grow from.
+ const src = item.request?.mode === "generate" || item.request?.mode === "compose" ? undefined : item.request?.images?.[0];
const from = src ? session.find((i) => itemSource(i) === src) : undefined;
const mode = job.plan?.mode;
// "v3 · Editing v2", "v1 · Creating"
- const title = [imageName(labels[item.key]), mode && `${MODE_DOING[mode]}${from && mode !== "multi_reference" ? ` ${imageName(labels[from.key]).toLowerCase()}` : ""}`].filter(Boolean).join(" · ");
+ const title = [imageName(labels[item.key]), mode && `${MODE_DOING[mode]}${from && mode !== "multi_reference" && mode !== "compose" ? ` ${imageName(labels[from.key]).toLowerCase()}` : ""}`].filter(Boolean).join(" · ");
// The source keeps its own shape inside an expansion; elsewhere it fills the frame.
const outpaint = item.request?.outpaint;
const { pct, clock } = useJobPercent(job, item.request, true);
@@ -90,7 +93,7 @@ function Pending({ job, item, labels }: { job: JobView; item: SessionItem; label
title={title}
text={job.enhanced_prompt!}
streaming={job.status === "enhancing_prompt"}
- withImage={!!src}
+ withImage={!!src || item.request?.mode === "compose"}
budget={job.plan?.estimated_seconds || null}
onCancel={() => cancelJob(job.id)}
onGone={() => setPromptGone(true)}
@@ -389,7 +392,7 @@ function MoreMenu({ item, path }: { item: SessionItem; path: string | null }) {
function GenActions({ item, g, showOriginal, onLut }: { item: SessionItem; g: GenerationRecord; showOriginal: boolean; onLut: (lut: LutEntry) => void }) {
// Save, copy and "show in folder" act on the image on screen: the result or its pre-upscale original.
const shownPath = (showOriginal && g.pipeline?.original_path) || g.file_path;
- const original = g.references[0] && g.mode !== "generate" && g.mode !== "upscale" && g.mode !== "lut" ? { width: g.references[0].width, height: g.references[0].height } : null;
+ const original = g.references[0] && g.mode !== "generate" && g.mode !== "compose" && g.mode !== "upscale" && g.mode !== "lut" ? { width: g.references[0].width, height: g.references[0].height } : null;
const [fav, setFav] = useState(g.favorite);
return (
<div className="actions">
@@ -681,7 +684,7 @@ function Timeline({ labels }: { labels: Record<string, string> }) {
const making = pending && !failed;
const mode: Mode | "lut" | undefined = it.gen?.mode ?? job?.plan?.mode;
const link = links[it.key];
- const pendingSrc = pending && it.request?.mode !== "generate" ? it.request?.images?.[0] : undefined;
+ const pendingSrc = pending && it.request?.mode !== "generate" && it.request?.mode !== "compose" ? it.request?.images?.[0] : undefined;
const prompt = it.gen?.prompt || it.request?.prompt || "";
const what = mode ? (mode === "generate" && link?.kind === "start" ? "New image" : MODE_LABEL[mode]) : it.input ? "Imported" : "";
const tip = [[imageName(labels[it.key]), what, linkText(link, labels)].filter(Boolean).join(" · "), prompt, src ? "Drag onto the prompt box to use it there" : ""].filter(Boolean).join("\n");
diff --git a/src/components/jobMotion.ts b/src/components/jobMotion.ts
index 5889adb..3f3e8d5 100644
--- a/src/components/jobMotion.ts
+++ b/src/components/jobMotion.ts
@@ -27,7 +27,7 @@ function rememberProgress(m: Partial<ProgressMemory>) {
}
}
-const ENHANCED_MODES = new Set(["generate", "edit", "multi_reference"]);
+const ENHANCED_MODES = new Set(["generate", "compose", "edit", "multi_reference"]);
/** Live percentage of a whole job (`jobPercent`), computed a few times a second, only ever going
* up, and eased so it counts up smoothly. Tracks when the job and each phase started; `learn`
diff --git a/src/lib/api.ts b/src/lib/api.ts
index 613d8d2..a9e8583 100644
--- a/src/lib/api.ts
+++ b/src/lib/api.ts
@@ -90,7 +90,7 @@ export const api = {
cancelInstall: () => call<InstallStatus>("/setup/install/cancel", { method: "POST" }),
config: () => call<AppConfig>("/config"),
/** The prompt enhancer's built-in instructions. */
- enhancerDefaults: () => call<{ t2i: string; edit: string; max_chars: number }>("/enhancer/defaults"),
+ enhancerDefaults: () => call<{ t2i: string; edit: string; compose: string; max_chars: number }>("/enhancer/defaults"),
saveConfig: (c: AppConfig) => call<{ saved: boolean; backend_restart_needed: boolean }>("/config", { method: "PUT", body: json(c) }),
startBackend: () => call<{ ready: boolean }>("/backend/start", { method: "POST" }),
stopBackend: () => call<{ stopped: boolean }>("/backend/stop", { method: "POST" }),
diff --git a/src/lib/logic.test.ts b/src/lib/logic.test.ts
index ec0c040..9fb1871 100644
--- a/src/lib/logic.test.ts
+++ b/src/lib/logic.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
import {
- activeLoras, activeOverrides, buildRequest, toggleLora, MAX_LORAS, jobPercent, compareBase, composerFromRecord, enhancerApplies, diffPixels, emptyComposer, expansionPixels, expansionPreset, jobLabel, jobSecondsLeft, lutInfo, moveRef, needsPrompt, normalizeQuality, persistentAdvanced, pipelineSummary,
+ activeLoras, activeOverrides, buildRequest, composing, editing, reviewRequest, wantsPromptReview, toggleLora, MAX_LORAS, jobPercent, compareBase, composerFromRecord, enhancerApplies, diffPixels, emptyComposer, expansionPixels, expansionPreset, jobLabel, jobSecondsLeft, lutInfo, moveRef, needsPrompt, normalizeQuality, persistentAdvanced, pipelineSummary,
planPipeline, remainingSeconds, sizeForWidth, timeAgo, upscaleRequest, upscaleTargets, versionLabels, type JobClock, type Ref,
neighbourAfterRemoval, previewIndex, starPromptDue, STAR_PROMPT_AFTER, formatBytes, formatDuration, installItemShort, installItemText, installProgress, installStep, installTimeLeft, timelineLinks, undoTarget, aspectLabel, parseRatio, sizeForRatio, expandToRatio, expandToSize, arcLayout,
} from "./logic";
@@ -117,6 +117,44 @@ describe("buildRequest", () => {
const plain = composerFromRecord({ ...g, original_prompt: null }, { ...emptyComposer(), enhance: true });
expect([plain.prompt, plain.enhance]).toEqual(["A tabby cat sleeping on a sunlit windowsill.", false]);
});
+ it("New image with images makes a new image that uses them as references", () => {
+ const c = { ...emptyComposer(), prompt: "lei che beve questo caffè", refs: [ref(1), ref(2)], create: true, aspect: "4:5" };
+ expect(composing(c) && !editing(c)).toBe(true);
+ const r = buildRequest(c);
+ expect([r.mode, r.images, r.aspect_ratio]).toEqual(["compose", ["input:1", "input:2"], "4:5"]);
+ // A mask or an expansion left from editing image 1 does not apply to a new image.
+ const leftovers = { ...c, mask: { inputId: "m", refKey: "k1" }, outpaint: { left: 10, right: 0, top: 0, bottom: 0, units: "percent" as const } };
+ const r2 = buildRequest({ ...leftovers, enhance: true });
+ expect([r2.mask, r2.outpaint, r2.aspect_ratio, r2.enhance]).toEqual([null, null, "4:5", true]);
+ // Without images it is text-to-image; editing sends the images as before.
+ expect(buildRequest({ ...c, refs: [] }).mode).toBe("auto");
+ expect(buildRequest({ ...c, create: false }).mode).toBe("auto");
+ expect(editing({ ...c, create: false })).toBe(true);
+ });
+ it("reopening a result made from references goes back to New image with them", () => {
+ const g = { prompt: "x", original_prompt: null, mode: "compose", references: [{ index: 0, input_id: "a", width: 10, height: 10 }], mask_input_id: null, outpaint: null, quality: "fast", request: { mode: "compose", images: ["input:a"] } } as unknown as GenerationRecord;
+ const c = composerFromRecord(g, emptyComposer());
+ expect([c.create, c.mode, buildRequest(c).mode]).toEqual([true, "auto", "compose"]);
+ });
+ it("Prompt+ review: Enter first writes the prompt into the box, then sends it as written", () => {
+ expect(emptyComposer().enhanceReview).toBe(false);
+ expect(emptyComposer({ enhanceReview: true }).enhanceReview).toBe(true);
+ const c = { ...emptyComposer(), prompt: "un gatto", enhance: true, enhanceReview: true };
+ expect(wantsPromptReview(c)).toBe(true);
+ expect(wantsPromptReview({ ...c, enhanceReview: false })).toBe(false);
+ expect(wantsPromptReview({ ...c, enhance: false })).toBe(false);
+ expect(wantsPromptReview({ ...c, prompt: " " })).toBe(false);
+ expect(wantsPromptReview({ ...c, refs: [ref(1)], mask: { inputId: "m", refKey: "k1" } })).toBe(false);
+ const r = reviewRequest(c);
+ expect([r.enhance, r.enhance_only, r.prompt]).toEqual([true, true, "un gatto"]);
+ // The written prompt is sent as is, with the user's words, and not rewritten again.
+ const written = { ...c, prompt: "A ginger cat asleep on a windowsill.", enhancedFrom: "un gatto" };
+ expect(wantsPromptReview(written)).toBe(false);
+ const sent = buildRequest(written);
+ expect([sent.prompt, sent.enhanced_from, "enhance" in sent, "enhance_only" in sent]).toEqual(["A ginger cat asleep on a windowsill.", "un gatto", false, false]);
+ // Emptied box: the user's next words are rewritten again.
+ expect("enhanced_from" in buildRequest({ ...written, prompt: " " })).toBe(false);
+ });
});
describe("LoRA", () => {
diff --git a/src/lib/logic.ts b/src/lib/logic.ts
index 1b0818a..35d028f 100644
--- a/src/lib/logic.ts
+++ b/src/lib/logic.ts
@@ -31,6 +31,15 @@ export interface Composer {
advanced: Advanced;
/** Prompt enhancer on (remembered; used only where `enhancerApplies`). */
enhance: boolean;
+ /** Prompt+ writes its prompt into the box first, to read and change before making the image
+ * (remembered); otherwise it writes and the image follows. */
+ enhanceReview: boolean;
+ /** The user's own words when the prompt in the box was written by Prompt+ (a review, or a
+ * reused enhanced prompt): sent as is, without rewriting it again. */
+ enhancedFrom: string | null;
+ /** "New image" chosen: images added to the prompt are references for a new image (people,
+ * products, a style), not the image to edit. */
+ create: boolean;
/** LoRAs switched on in this project; null = the ones on by default (`activeLoras`). */
loras: string[] | null;
}
@@ -58,9 +67,18 @@ export const emptyComposer = (prefs?: Partial<Composer>): Composer => ({
seed: null,
advanced: newChatAdvanced(prefs?.advanced),
enhance: prefs?.enhance === true,
+ enhanceReview: prefs?.enhanceReview === true,
+ enhancedFrom: null,
+ create: false,
loras: null,
});
+/** The prompt makes a new image from the reference images (rather than editing image 1). */
+export const composing = (c: Pick<Composer, "create" | "refs">): boolean => c.create && c.refs.length > 0;
+
+/** The prompt edits image 1 (with any other images as references). */
+export const editing = (c: Pick<Composer, "create" | "refs">): boolean => !c.create && c.refs.length > 0;
+
/** LoRAs one image can use at once (`lora::MAX_ACTIVE`). */
export const MAX_LORAS = 3;
@@ -113,19 +131,24 @@ export function hasOutpaint(o: OutpaintSpec | null): boolean {
return !!o && (o.left > 0 || o.right > 0 || o.top > 0 || o.bottom > 0);
}
+/** A mask painted on image 1 that the request uses (not for a new image from references). */
+const maskInUse = (c: Composer) => !composing(c) && !!c.mask && !!c.refs[0] && c.mask.refKey === c.refs[0].key;
+const outpaintInUse = (c: Composer) => !composing(c) && hasOutpaint(c.outpaint);
+
/** Composer state -> stable service request. */
export function buildRequest(c: Composer, parentId?: string | null): GenerationRequest {
- const maskValid = c.mask && c.refs[0] && c.mask.refKey === c.refs[0].key;
+ const maskValid = maskInUse(c);
const custom = c.resolution === "custom";
// Inpaint and expand keep the source's shape; create, edit and combine take the chosen ratio.
- const shaped = !maskValid && !hasOutpaint(c.outpaint);
+ const shaped = !maskValid && !outpaintInUse(c);
+ const reviewed = !!c.enhancedFrom && !!c.prompt.trim();
return {
prompt: c.prompt.trim(),
- mode: c.mode,
- images: c.mode === "generate" ? [] : c.refs.map((r) => r.source),
+ mode: composing(c) ? "compose" : c.mode,
+ images: c.mode === "generate" && !composing(c) ? [] : c.refs.map((r) => r.source),
mask: maskValid ? `input:${c.mask!.inputId}` : null,
...(maskValid ? { inpaint_action: c.inpaintAction } : {}),
- outpaint: hasOutpaint(c.outpaint) ? c.outpaint : null,
+ outpaint: outpaintInUse(c) ? c.outpaint : null,
quality: c.quality,
resolution: c.resolution,
aspect_ratio: shaped && c.aspect !== "auto" && !custom ? c.aspect : null,
@@ -136,21 +159,30 @@ export function buildRequest(c: Composer, parentId?: string | null): GenerationR
advanced: cleanAdvanced(c.advanced),
client: "ui",
parent_id: parentId ?? null,
- ...(c.enhance && enhancerApplies(c) ? { enhance: true } : {}),
+ // A prompt Prompt+ wrote already is sent as it is, with the user's words kept beside it.
+ ...(reviewed ? { enhanced_from: c.enhancedFrom } : c.enhance && enhancerApplies(c) ? { enhance: true } : {}),
};
}
+/** Prompt+ in review mode: Enter first has the prompt written into the box (no image yet). */
+export function wantsPromptReview(c: Composer): boolean {
+ return c.enhance && c.enhanceReview && enhancerApplies(c) && !c.enhancedFrom && !!c.prompt.trim();
+}
+
+/** The request that only writes the prompt (Prompt+ review). */
+export function reviewRequest(c: Composer): GenerationRequest {
+ return { ...buildRequest(c), enhance: true, enhance_only: true };
+}
+
/** The prompt enhancer works on new images, edits and combines; a painted area or an expansion
* wraps the prompt in its own instruction. */
export function enhancerApplies(c: Composer): boolean {
- const maskValid = c.mask && c.refs[0] && c.mask.refKey === c.refs[0].key;
- return !maskValid && !hasOutpaint(c.outpaint);
+ return !maskInUse(c) && !outpaintInUse(c);
}
/** False only for a removal in a painted area, which needs no description. */
export function needsPrompt(c: Composer): boolean {
- const maskValid = c.mask && c.refs[0] && c.mask.refKey === c.refs[0].key;
- return !(maskValid && c.inpaintAction === "remove");
+ return !(maskInUse(c) && c.inpaintAction === "remove");
}
/** Advanced fields that change how the model samples. They last for the session only: a value
@@ -192,12 +224,14 @@ export function composerFromRecord(g: GenerationRecord, base: Composer): Compose
// An enhanced result is the user's prompt with the enhancer on (Reuse prompt takes its text).
prompt: g.original_prompt ?? g.prompt,
enhance: !!g.original_prompt,
+ enhancedFrom: null,
+ create: g.mode === "compose" && refs.length > 0,
refs,
mask: g.mask_input_id && refs[0] ? { inputId: g.mask_input_id, refKey: refs[0].key } : null,
inpaintAction: req?.inpaint_action ?? "edit",
outpaint: g.outpaint ? { ...g.outpaint, units: "pixels" } : null,
// Upscales are started from the image toolbar, not the composer.
- mode: req?.mode && req.mode !== "upscale" && g.mode !== "lut" ? req.mode : "auto",
+ mode: req?.mode && req.mode !== "upscale" && req.mode !== "compose" && g.mode !== "lut" ? req.mode : "auto",
quality: normalizeQuality(g.quality, base.quality),
resolution: req?.resolution ?? base.resolution,
aspect: req?.aspect_ratio ?? "auto",
@@ -226,6 +260,7 @@ export const MODE_LABEL: Record<Mode | "lut", string> = {
inpaint: "Inpaint",
outpaint: "Expand",
multi_reference: "Combine",
+ compose: "From references",
upscale: "Upscale",
lut: "LUT",
};
@@ -406,7 +441,7 @@ export interface JobClock {
}
/** About how many words the built-in enhancer prompts ask for. */
-const ENHANCER_WORDS = { generate: 110, edit: 35 };
+const ENHANCER_WORDS = { generate: 110, compose: 150, edit: 35 };
const SAVE_SECONDS = 1;
/** Time left of a phase estimated at `est` seconds, `t` seconds in. Past ~80 % of the
@@ -432,7 +467,7 @@ export function jobSecondsLeft(j: JobView, c: JobClock): number {
const decodeS = genS * 0.1;
const batch = Math.max(1, p?.batch_count ?? 1);
const imagesAfter = j.image && j.image[1] > 1 ? j.image[1] - j.image[0] : 0;
- const words = ENHANCER_WORDS[p?.mode === "generate" ? "generate" : "edit"];
+ const words = ENHANCER_WORDS[p?.mode === "generate" || p?.mode === "compose" ? p.mode : "edit"];
const enhanceS = c.enhance ? 0.5 + words * c.enhancerSecondsPerWord : 0;
const fromGeneration = genS + upS + SAVE_SECONDS;
switch (j.status) {
diff --git a/src/lib/store.ts b/src/lib/store.ts
index 4bd884b..12bd904 100644
--- a/src/lib/store.ts
+++ b/src/lib/store.ts
@@ -8,7 +8,7 @@
import { useSyncExternalStore } from "react";
import { markFresh } from "../components/Cocoon";
import { api, ApiError, setPrivateInputs, subscribe } from "./api";
-import { activeLoras, buildRequest, emptyComposer, needsPrompt, newKey, persistentAdvanced, refFromGen, refFromInput, starPromptDue, timelineLinks, undoTarget, versionLabels, type CompareMode, type Composer, type Ref } from "./logic";
+import { activeLoras, buildRequest, composing, emptyComposer, needsPrompt, newKey, persistentAdvanced, refFromGen, refFromInput, reviewRequest, starPromptDue, timelineLinks, undoTarget, versionLabels, wantsPromptReview, type CompareMode, type Composer, type Ref } from "./logic";
import type { AppErrorBody, GenerationRecord, GenerationRequest, InputRecord, JobView, LoraItem, ServerState, StatusResponse } from "./types";
export type Overlay = null | "gallery" | "settings" | "inpaint" | "expand" | "welcome" | "whats-new" | "prompt-tips" | "shortcuts";
@@ -92,6 +92,8 @@ export interface State {
loras: LoraItem[];
/** Tab Settings opens on (then cleared). */
settingsTab: string | null;
+ /** Prompt+ is writing a prompt into the box for review: its job, and the user's words. */
+ review: { jobId: string; prompt: string } | null;
}
const PREFS_KEY = "qls.prefs.v1";
@@ -110,9 +112,9 @@ function loadPrefs(): Partial<Composer> {
function savePrefs(c: Composer) {
try {
- const { quality, resolution, aspect, customWidth, customHeight, enhance } = c;
+ const { quality, resolution, aspect, customWidth, customHeight, enhance, enhanceReview } = c;
const advanced = persistentAdvanced(c.advanced);
- localStorage.setItem(PREFS_KEY, JSON.stringify({ quality, resolution, aspect, customWidth, customHeight, advanced, enhance }));
+ localStorage.setItem(PREFS_KEY, JSON.stringify({ quality, resolution, aspect, customWidth, customHeight, advanced, enhance, enhanceReview }));
} catch {
/* storage unavailable */
}
@@ -302,6 +304,7 @@ let state: State = {
starPrompt: false,
loras: [],
settingsTab: null,
+ review: null,
};
const listeners = new Set<() => void>();
@@ -446,6 +449,11 @@ function onJob(job: JobView) {
if (job.status === "done" && prev?.status !== "done" && getState().session.some((i) => i.jobId === job.id && i.kind === "job")) {
markFresh(job.results.map((g) => g.id));
}
+ // Prompt+ review: the prompt it wrote goes into the box (no image, no version).
+ if (getState().review?.jobId === job.id) {
+ onReviewJob(job);
+ return;
+ }
// Made with this app (it had a pending version), not by another client such as MCP.
let made = false;
setState((s) => {
@@ -459,10 +467,11 @@ function onJob(job: JobView) {
const pending = s.session[idx];
const session = [...s.session.slice(0, idx), ...results, ...s.session.slice(idx + 1)];
const wasSelected = s.selected === pending.key;
- // Editing carries on from the new version; creating new images stays in create mode.
+ // Editing carries on from the new version; creating new images (also from references)
+ // stays in create mode with the same references.
let composer = s.composer;
const src = pending.request?.images?.[0];
- if (wasSelected && results[0]?.gen && src && composer.refs[0]?.source === src) {
+ if (wasSelected && results[0]?.gen && src && composer.refs[0]?.source === src && !composer.create) {
composer = { ...composer, refs: [refFromGen(results[0].gen), ...composer.refs.slice(1)], mask: null, outpaint: null };
}
return { jobs, session, composer, selected: wasSelected && results[0] ? results[0].key : s.selected };
@@ -488,6 +497,21 @@ function onJob(job: JobView) {
if (job.status === "failed" && job.error) toastError(new ApiError(job.error, 500));
}
+/** A Prompt+ review job changed: the text streams into the box; when done the box keeps it
+ * (with the user's words, for Undo); a failure or a cancel leaves the user's prompt. */
+function onReviewJob(job: JobView) {
+ setState((s) => {
+ const jobs = { ...s.jobs, [job.id]: job };
+ if (!["done", "failed", "cancelled"].includes(job.status)) return { jobs };
+ const words = s.review?.prompt ?? s.composer.prompt;
+ const text = job.status === "done" ? job.enhanced_prompt?.trim() : "";
+ const composer = text ? { ...s.composer, prompt: text, enhancedFrom: words } : { ...s.composer, prompt: words };
+ return { jobs, review: null, composer };
+ });
+ if (job.status === "failed" && job.error) toastError(new ApiError(job.error, 500));
+ if (job.status === "done") focusPrompt(true);
+}
+
// ---------------------------------------------------------------------------------------
// Star prompt: once, after a few images made with the app, never again whatever the answer.
// ---------------------------------------------------------------------------------------
@@ -708,7 +732,7 @@ export async function openGeneration(g: GenerationRecord) {
const items: SessionItem[] = [];
const root = chain[0];
const ref = root.references[0];
- if (ref && root.references.length === 1 && root.mode !== "generate") {
+ if (ref && root.references.length === 1 && root.mode !== "generate" && root.mode !== "compose") {
try {
const r = inputCache.get(ref.input_id) ?? (await api.input(ref.input_id));
items.push({ key: newKey(), kind: "input", input: r });
@@ -762,23 +786,33 @@ export function selectItem(key: string, keepRedo = false) {
setState((s) => {
const it = s.session.find((i) => i.key === key);
if (!it) return {};
- const ref = s.composer.refs.length ? refOf(it) : null;
+ const ref = s.composer.refs.length && !s.composer.create ? refOf(it) : null;
return { selected: key, composer: ref ? retarget(s.composer, ref) : s.composer, ...(keepRedo ? {} : { redo: [] }) };
});
}
-/** "New image": the prompt creates an image from scratch; the versions stay to look at. */
+/** "New image": the prompt creates a new image; images in the prompt stay, as references
+ * (people, products, a style) instead of the image to edit. The versions stay to look at. */
export function startNewImage() {
- setState((s) => ({ composer: { ...s.composer, refs: [], mask: null, outpaint: null } }));
+ setState((s) => ({ composer: { ...s.composer, create: true, mask: null, outpaint: null } }));
focusPrompt();
}
-/** "Edit image": the prompt edits the version shown (or the latest image). */
+/** "Edit image": the prompt edits the version shown (or the latest image). When it is one of a
+ * new image's references it becomes image 1 and the others stay; a version that is not (such as
+ * the new image just made) is edited on its own. */
export function editShownImage() {
setState((s) => {
const shown = s.session.find((i) => i.key === s.selected);
const ref = refOf(shown) ?? refOf([...s.session].reverse().find((i) => i.gen || i.input));
- return ref ? { composer: retarget(s.composer, ref) } : {};
+ if (!ref) return composing(s.composer) ? { composer: { ...s.composer, create: false, aspect: "auto" } } : {};
+ const c = s.composer;
+ if (composing(c)) {
+ const here = c.refs.find((r) => r.source === ref.source);
+ const refs = here ? [here, ...c.refs.filter((r) => r !== here)] : [ref];
+ return { composer: { ...c, refs, create: false, mask: null, outpaint: null, aspect: "auto" } };
+ }
+ return { composer: { ...retarget(c, ref), create: false } };
});
focusPrompt();
}
@@ -788,7 +822,8 @@ export function editShownImage() {
export function itemOrigin(i: SessionItem): { from: string[]; variant: boolean } {
const req = i.gen?.request ?? i.request;
const mode = i.gen?.mode ?? req?.mode;
- const images = mode === "generate" ? [] : req?.images ?? [];
+ // A new image (also one made from references) starts a line of its own.
+ const images = mode === "generate" || mode === "compose" ? [] : req?.images ?? [];
if (images.length) return { from: images, variant: false };
const parent = i.gen?.parent_id ?? req?.parent_id;
return parent ? { from: [`gen:${parent}`], variant: true } : { from: [], variant: false };
@@ -808,7 +843,8 @@ export const sessionLinks = (session: SessionItem[]) => timelineLinks(lineage(se
export function reusePrompt(g: GenerationRecord) {
setState((s) => {
const c = s.composer;
- const sources = itemOrigin({ key: "", kind: "gen", gen: g });
+ const compose = g.mode === "compose";
+ const sources = compose ? { from: g.request?.images ?? [], variant: false } : itemOrigin({ key: "", kind: "gen", gen: g });
const refs: Ref[] = [];
if (!sources.variant) {
sources.from.forEach((src, i) => {
@@ -823,13 +859,15 @@ export function reusePrompt(g: GenerationRecord) {
composer: {
...c,
prompt: g.prompt,
- // The enhancer's text is a full prompt already: rewriting it again would drift.
- enhance: g.original_prompt ? false : c.enhance,
+ // The enhancer's text is a full prompt already: sent as it is (rewriting it again would
+ // drift); Undo in the box brings back the user's words.
+ enhancedFrom: g.original_prompt ?? null,
+ create: compose && refs.length > 0,
refs,
mask,
inpaintAction: mask ? g.request?.inpaint_action ?? "edit" : c.inpaintAction,
outpaint: g.outpaint && refs.length ? { ...g.outpaint, units: "pixels" } : null,
- aspect: refs.length && !c.refs.length ? "auto" : c.aspect,
+ aspect: refs.length && !c.refs.length && !compose ? "auto" : c.aspect,
seed: null,
},
};
@@ -837,6 +875,12 @@ export function reusePrompt(g: GenerationRecord) {
focusPrompt(true);
}
+/** Back to the user's own words from a prompt Prompt+ wrote (the box's Undo). */
+export function undoEnhancedPrompt() {
+ setState((s) => (s.composer.enhancedFrom == null ? {} : { composer: { ...s.composer, prompt: s.composer.enhancedFrom, enhancedFrom: null } }));
+ focusPrompt(true);
+}
+
const undoItems = (session: SessionItem[]) => session.map((i) => ({ key: i.key, source: itemSource(i), from: itemOrigin(i).from[0] ?? null }));
/** The version Undo goes back to (what the selected one was made from), if any. */
@@ -864,14 +908,16 @@ export function redoVersion() {
setState({ redo });
}
-/** New images: into an empty project (or with nothing being edited) they become versions to
- * work on; while editing they are added as extra references. */
+/** New images: into an empty project they become versions to work on (the photo to edit);
+ * in a project they are added to the prompt: as extra references while editing, else as
+ * references for a new image ("New image" stays; Edit image edits image 1). */
export function addInputs(records: InputRecord[]) {
if (!records.length) return;
setState((s) => {
const added = records.map(refFromInput);
- if (s.composer.refs.length && s.session.length) {
- return { composer: { ...s.composer, refs: [...s.composer.refs, ...added].slice(0, 10), outpaint: null } };
+ if (s.session.length) {
+ const create = s.composer.refs.length ? s.composer.create : true;
+ return { composer: { ...s.composer, refs: [...s.composer.refs, ...added].slice(0, 10), create, outpaint: null } };
}
const items: SessionItem[] = records.map((r) => ({ key: newKey(), kind: "input", input: r }));
return {
@@ -911,7 +957,9 @@ export function addResult(g: GenerationRecord) {
export async function submitComposer() {
const s = getState();
- const target = s.composer.refs[0]?.source;
+ if (s.review) return;
+ if (wantsPromptReview(s.composer)) return startPromptReview();
+ const target = composing(s.composer) ? undefined : s.composer.refs[0]?.source;
const parent = target?.startsWith("gen:") ? target.slice(4) : null;
const req: GenerationRequest = { ...buildRequest(s.composer, parent), loras: activeLoras(s.composer, s.loras) };
if (!req.prompt && needsPrompt(s.composer)) {
@@ -919,7 +967,39 @@ export async function submitComposer() {
return;
}
if (await submitRequest(req)) {
- setState((st) => ({ lastPrompt: req.prompt, composer: { ...st.composer, prompt: st.composer.prompt.trim() === req.prompt ? "" : st.composer.prompt, seed: null } }));
+ setState((st) => {
+ const sent = st.composer.prompt.trim() === req.prompt;
+ return {
+ lastPrompt: st.composer.enhancedFrom ?? req.prompt,
+ composer: { ...st.composer, prompt: sent ? "" : st.composer.prompt, enhancedFrom: sent ? null : st.composer.enhancedFrom, seed: null },
+ };
+ });
+ }
+}
+
+/** Prompt+ review: the prompt is written into the box first (a job that makes no image). */
+async function startPromptReview() {
+ const s = getState();
+ let req = reviewRequest(s.composer);
+ if (s.privateMode) req = { ...req, private: true };
+ try {
+ const job = await api.submit(req);
+ setState((st) => ({ jobs: { ...st.jobs, [job.id]: job }, review: { jobId: job.id, prompt: st.composer.prompt } }));
+ } catch (e) {
+ if (isMissingModel(e)) openModelSetup();
+ toastError(e);
+ }
+}
+
+/** Stops Prompt+ writing a prompt for review; the user's words stay in the box. */
+export async function cancelPromptReview() {
+ const r = getState().review;
+ if (!r) return;
+ try {
+ onReviewJob(await api.cancel(r.jobId));
+ } catch (e) {
+ setState((s) => ({ review: null, composer: { ...s.composer, prompt: r.prompt } }));
+ toastError(e);
}
}
@@ -932,7 +1012,8 @@ export async function cancelJob(jobId: string) {
}
}
-/** Adds a version as an extra reference (or as the image to edit when there is none). */
+/** Adds a version to the prompt: an extra reference while editing, else a reference for a new
+ * image ("New image" stays; Edit image edits image 1). */
export function addAsReference(item: SessionItem) {
const ref = item.gen ? refFromGen(item.gen) : item.input ? refFromInput(item.input) : null;
if (!ref) return;
@@ -944,7 +1025,7 @@ export function addAsReference(item: SessionItem) {
toastInfo("Up to 10 reference images are supported.");
return;
}
- setState((s) => ({ composer: { ...s.composer, refs: [...s.composer.refs, ref].slice(0, 10), outpaint: null, aspect: s.composer.refs.length ? s.composer.aspect : "auto" } }));
+ setState((s) => ({ composer: { ...s.composer, refs: [...s.composer.refs, ref].slice(0, 10), create: s.composer.refs.length ? s.composer.create : true, outpaint: null } }));
}
export function focusPrompt(cursorToEnd = false) {
diff --git a/src/lib/types.ts b/src/lib/types.ts
index d42c957..451d8c2 100644
--- a/src/lib/types.ts
+++ b/src/lib/types.ts
@@ -1,6 +1,6 @@
// Mirrors the kokon-service JSON contract (crates/qls-core).
-export type Mode = "auto" | "generate" | "edit" | "inpaint" | "outpaint" | "multi_reference" | "upscale";
+export type Mode = "auto" | "generate" | "edit" | "inpaint" | "outpaint" | "multi_reference" | "compose" | "upscale";
export type ResolvedMode = Exclude<Mode, "auto">;
/** What made a saved result: a generation mode, or a colour LUT applied to an image. */
export type RecordMode = ResolvedMode | "lut";
@@ -61,6 +61,10 @@ export interface GenerationRequest {
private?: boolean;
/** Prompt enhancer: the model's language model rewrites the prompt first (new images, edits, combines). */
enhance?: boolean;
+ /** Prompt+ review: only write the prompt (the job ends with `enhanced_prompt` and no image). */
+ enhance_only?: boolean;
+ /** The user's own words when `prompt` was written by Prompt+ in a review. */
+ enhanced_from?: string | null;
/** LoRA ids to use (the app always sends its list; omitted = none, as for MCP). */
loras?: string[] | null;
}
@@ -302,9 +306,10 @@ export interface AppConfig {
hardwarePreset: string;
/** Plan as if the GPU had this much VRAM (MiB); 0 = detected. */
vramOverrideMib: number;
- /** Prompt enhancer instructions for new images and for edits; "" = the built-in ones. */
+ /** Prompt enhancer instructions for new images, edits and new images from references; "" = the built-in ones. */
enhancerT2iPrompt?: string;
enhancerEditPrompt?: string;
+ enhancerComposePrompt?: string;
ui: Record<string, unknown>;
}
diff --git a/src/styles.css b/src/styles.css
index c2ccd34..99e90d1 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -384,6 +384,15 @@ svg { display: block; flex: none; }
.prompt { width: 100%; border: 0; outline: 0; resize: none; background: transparent; font-size: 15.5px; line-height: 1.5; padding: 4px 2px; max-height: 200px; min-height: 26px; }
.prompt::placeholder { color: var(--text-3); }
+/* Prompt+ review: its prompt streams into the box, read-only until it is done */
+.prompt.writing { color: var(--text-2); cursor: progress; }
+.prompt.writing::placeholder { animation: writing-pulse 1.6s ease-in-out infinite; }
+@keyframes writing-pulse { 50% { opacity: 0.45; } }
+@media (prefers-reduced-motion: reduce) { .prompt.writing::placeholder { animation: none; } }
+.enhanced-from { display: flex; align-items: center; gap: 6px; margin-top: 4px; padding: 0 2px; color: var(--text-3); font-size: 12px; min-width: 0; }
+.enhanced-from .text { flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.enhanced-from button.link { display: inline-flex; align-items: center; gap: 3px; text-decoration: none; color: var(--text-2); flex-shrink: 0; }
+.enhanced-from button.link:hover { color: var(--text); text-decoration: underline; }
.controls { display: flex; align-items: center; gap: 5px; margin-top: 6px; }
.controls .spacer { flex: 1; }
.plan-hint { color: var(--text-3); font-size: 12px; font-variant-numeric: tabular-nums; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; margin-right: 6px; }
@@ -664,6 +673,9 @@ pre.diag { font-family: ui-monospace, "Cascadia Mono", Consolas, monospace; font
/* ---------- aspect ratio and size menus ---------- */
.popover.wide { min-width: 0; }
+/* Prompt+ menu: one line per choice */
+.popover.prompt-plus { width: 260px; }
+.popover.prompt-plus .opt > span:not(.check) { white-space: nowrap; }
.ratio-icon { display: inline-grid; place-items: center; flex: none; }
.ratio-icon i { display: block; border: 1.5px solid currentColor; border-radius: 3px; box-sizing: border-box; }
.aspect-menu { width: 296px; display: flex; flex-direction: column; gap: 6px; }