Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Generate reference icons in the work queue

Bitti645d8616bf4d
diff --git a/README.md b/README.md
index 2eebc5e..ad36819 100644
--- a/README.md
+++ b/README.md
@@ -63,7 +63,15 @@ The web fallback seeds three deterministic showcase projects on first launch. Re
### Reference icons
-`npm run reference-icons` renders every missing character, product, location, and style preset with MiniMax H3 at 30 steps. The generator reads the application catalogue directly, requests the model's minimum temporal span, and writes frame 0 directly as a high-quality 4:4:4 256×256 JPEG without creating an intermediate video or audio file. Character entries use controlled headshot lighting; product and location entries use a complete-subject view; style entries use a representative composition with lighting and rendering tailored to the named style.
+Custom references with a prompt and no existing artwork automatically receive
+256×256 JPG icons through SlopFab's dedicated still-image mode. Category-specific
+compositions include the user's prompt. All icon work appears in one Work Queue
+entry, and waiting video generations run before the next icon. Generated icons
+are saved under `references/icons/` in the project and are not sent to the video
+engine as image attachments. Built-in presets are added as new references from
+the Add a reference dialog.
+
+`npm run reference-icons` renders every missing character, product, location, and style preset with MiniMax H3 at 30 steps. Its DLL backend uses the dedicated still-image mode and writes a high-quality 256×256 JPEG without creating an intermediate video or audio file. Character entries use controlled headshot lighting; product and location entries use a complete-subject view; style entries use a representative composition with lighting and rendering tailored to the named style.
SlopFab, Cargo, and FFmpeg must be installed. The script uses the development paths under `D:\Projects\slopfab` by default; `SLOPFAB_EXE`, `SLOPFAB_TRANSFORMER`, `SLOPFAB_TEXT_ENCODER`, `SLOPFAB_VIDEO_VAE`, `SLOPFAB_AUDIO_VAE`, `SLOPFAB_BACKEND`, `CARGO_EXE`, and `FFMPEG_EXE` can override them. Use `node scripts/generate-reference-icons.mjs --id=<preset-id> --force` to regenerate one entry.
diff --git a/src-tauri/src/agent.rs b/src-tauri/src/agent.rs
index 373816c..95883f7 100644
--- a/src-tauri/src/agent.rs
+++ b/src-tauri/src/agent.rs
@@ -1867,6 +1867,7 @@ mod tests {
images: Vec::new(),
intended_use: vec!["character".into()],
subcategory: None,
+ icon_relative_path: None,
created_at: "2026-01-02T04:00:00.000Z".into(),
});
let job = &mut next.generation_jobs[0];
diff --git a/src-tauri/src/agent_commands.rs b/src-tauri/src/agent_commands.rs
index e378871..d71c210 100644
--- a/src-tauri/src/agent_commands.rs
+++ b/src-tauri/src/agent_commands.rs
@@ -434,6 +434,7 @@ fn apply_command(
images: Vec::new(),
intended_use: intended_use.clone(),
subcategory: None,
+ icon_relative_path: None,
created_at: timestamp.into(),
});
}
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index bbc2d76..9833839 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -211,6 +211,8 @@ struct ReusableReference {
intended_use: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
subcategory: Option<String>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ icon_relative_path: Option<String>,
created_at: String,
}
@@ -792,6 +794,8 @@ fn validate_and_normalize_config(mut config: ProjectConfig) -> Result<ProjectCon
.as_deref()
.map(normalize_external_path)
.transpose()?;
+ reference.icon_relative_path = reference.icon_relative_path.as_deref()
+ .map(normalize_project_path).transpose()?;
if reference.relative_path.is_some() && reference.source_path.is_some() {
return Err(format!(
"Reference '{}' cannot have both a project-relative path and an external source path.",
@@ -2120,6 +2124,7 @@ fn create_project_at_with_references(
images: Vec::new(),
intended_use: vec!["style".into()],
subcategory: None,
+ icon_relative_path: None,
created_at: config.created_at.clone(),
});
if let Some(job) = config.generation_jobs.first_mut() {
@@ -2566,6 +2571,39 @@ fn generated_summary(job_id: String) -> Option<rendered::RenderedSummary> {
rendered::summary(&job_id)
}
+/// Save only a true 256x256 still-image result, directly from the DLL's frame
+/// buffer. Icon artwork is stored separately from conditioning attachments.
+#[tauri::command]
+fn save_reference_icon(folder_path: String, job_id: String) -> Result<String, String> {
+ let summary = rendered::summary(&job_id).ok_or("The reference icon is no longer available.")?;
+ if summary.width != 256 || summary.height != 256 || summary.frame_count != 1 {
+ return Err("A reference icon must be a single 256x256 frame.".into());
+ }
+ let rgba = rendered::frame(&job_id, 0)?.ok_or("The reference icon has no image.")?;
+ write_reference_icon_frame(&folder_path, &job_id, &rgba)
+}
+
+fn write_reference_icon_frame(folder_path: &str, job_id: &str, rgba: &[u8]) -> Result<String, String> {
+ if rgba.len() != 256 * 256 * 4 {
+ return Err("The reference icon has an invalid pixel buffer.".into());
+ }
+ let rgb: Vec<u8> = rgba.chunks_exact(4).flat_map(|pixel| [pixel[0], pixel[1], pixel[2]]).collect();
+ let mut bytes = Vec::new();
+ jpeg_encoder::Encoder::new(&mut bytes, 95)
+ .encode(&rgb, 256, 256, jpeg_encoder::ColorType::Rgb)
+ .map_err(|error| format!("Could not encode reference icon: {error}"))?;
+ let root = project_root(folder_path)?;
+ let stem = generated_file_stem(job_id)?;
+ let directory = root.join("references").join("icons");
+ fs::create_dir_all(&directory).map_err(|error| format!("Could not create icon directory: {error}"))?;
+ let directory = directory.canonicalize().map_err(|error| error.to_string())?;
+ if !directory.starts_with(&root) {
+ return Err("Reference icons must stay inside the project folder.".into());
+ }
+ export::write_atomically(&directory.join(format!("{stem}.jpg")), &bytes)?;
+ Ok(format!("references/icons/{stem}.jpg"))
+}
+
/// One frame of a finished render, as RGBA the webview can build a `VideoFrame`
/// from. A frame at a time because a whole render is hundreds of megabytes and
/// the encoder only ever wants the next one.
@@ -2783,6 +2821,7 @@ pub fn run() {
write_timeline_thumbnail,
purge_timeline_thumbnails,
generated_summary,
+ save_reference_icon,
generated_frame,
generated_audio,
release_generated_frames,
@@ -3509,6 +3548,24 @@ mod tests {
.contains("unknown reference"));
}
+ #[test]
+ fn reference_icon_files_are_256_square_jpegs_confined_to_the_project() {
+ let root = tempfile::tempdir().unwrap();
+ write_project(root.path(), &fixture()).unwrap();
+ let rgba = vec![128; 256 * 256 * 4];
+ let folder = root.path().to_str().unwrap();
+ let relative = write_reference_icon_frame(folder, "icon-test", &rgba).unwrap();
+ assert_eq!(relative, "references/icons/icon-test.jpg");
+ let jpeg = fs::read(root.path().join(&relative)).unwrap();
+ assert_eq!(&jpeg[..2], &[0xff, 0xd8]);
+ assert_eq!(&jpeg[jpeg.len() - 2..], &[0xff, 0xd9]);
+ let frame = jpeg.windows(2).position(|bytes| bytes == [0xff, 0xc0]).unwrap();
+ assert_eq!(u16::from_be_bytes([jpeg[frame + 5], jpeg[frame + 6]]), 256);
+ assert_eq!(u16::from_be_bytes([jpeg[frame + 7], jpeg[frame + 8]]), 256);
+ assert!(write_reference_icon_frame(folder, "../escape", &rgba).is_err());
+ assert!(write_reference_icon_frame(folder, "icon-invalid", &[0; 4]).is_err());
+ }
+
#[test]
fn reference_categories_and_subcategories_survive_project_save() {
let root = tempfile::tempdir().unwrap();
@@ -3522,6 +3579,7 @@ mod tests {
let reference = &mut config.references[0];
reference.intended_use = vec![category.into()];
reference.subcategory = Some(subcategory.into());
+ reference.icon_relative_path = Some("references/icons/example.jpg".into());
reference.description.clear();
reference.content = None;
write_project(root.path(), &config).unwrap();
@@ -3529,6 +3587,7 @@ mod tests {
let reference = &restored.config.references[0];
assert_eq!(reference.intended_use, vec![category]);
assert_eq!(reference.subcategory.as_deref(), Some(subcategory));
+ assert_eq!(reference.icon_relative_path.as_deref(), Some("references/icons/example.jpg"));
assert!(reference.description.is_empty());
assert!(reference.content.is_none());
}
@@ -4153,6 +4212,7 @@ mod tests {
images: Vec::new(),
intended_use: Vec::new(),
subcategory: None,
+ icon_relative_path: None,
created_at: "2026-01-01T00:07:00.000Z".into(),
});
assert!(
diff --git a/src-tauri/src/slopfab.rs b/src-tauri/src/slopfab.rs
index faefce1..e7f625d 100644
--- a/src-tauri/src/slopfab.rs
+++ b/src-tauri/src/slopfab.rs
@@ -116,6 +116,8 @@ pub struct GenerationRequest {
pub job_id: String,
pub prompt: String,
pub frames: i32,
+ #[serde(default)]
+ pub still_image: bool,
pub steps: i32,
/// -1 asks the host to draw a fresh seed for this generation.
pub seed: i64,
@@ -569,6 +571,9 @@ fn configure_request(
) -> Result<(), String> {
api.set_prompt(handle, &request.prompt)?;
api.set_frames(handle, request.frames)?;
+ if request.still_image {
+ api.set_still_image(handle)?;
+ }
api.set_steps(handle, request.steps)?;
api.set_seed(handle, generation_seed(request.seed)?)?;
api.set_resolution(handle, request.canvas_width, request.canvas_height)?;
@@ -578,6 +583,9 @@ fn configure_request(
if include_models {
api.set_reuse_models(handle, true)?;
for (id, _, path) in &configuration.models {
+ if request.still_image && *id == 4 {
+ continue;
+ }
if let Some(path) = path {
api.set_model(handle, *id, path)?;
}
@@ -806,7 +814,8 @@ fn write_reference_icon(
let request = GenerationRequest {
job_id: spec.id.clone(),
prompt: spec.prompt.clone(),
- frames: 6,
+ frames: 1,
+ still_image: true,
steps: 30,
seed: i64::try_from(spec.seed)
.map_err(|_| format!("Icon '{}' seed is too large.", spec.id))?,
@@ -828,7 +837,7 @@ fn write_reference_icon(
});
}
let output = api.output(generation.0)?;
- if output.width != 256 || output.height != 256 || output.frames < 1 {
+ if output.width != 256 || output.height != 256 || output.frames != 1 {
return Err(format!(
"Icon '{}' returned {}x{} with {} frames.",
spec.id, output.width, output.height, output.frames
@@ -1044,6 +1053,7 @@ mod ffi {
set_prompt: unsafe extern "C" fn(*mut Request, *const c_char) -> i32,
set_resolution: unsafe extern "C" fn(*mut Request, i32, i32) -> i32,
set_frames: unsafe extern "C" fn(*mut Request, i32) -> i32,
+ set_still_image: Option<unsafe extern "C" fn(*mut Request, i32) -> i32>,
set_steps: unsafe extern "C" fn(*mut Request, i32) -> i32,
set_seed: unsafe extern "C" fn(*mut Request, u64) -> i32,
set_model: unsafe extern "C" fn(*mut Request, i32, *const c_char) -> i32,
@@ -1122,6 +1132,9 @@ mod ffi {
"slopfab_request_set_frames",
unsafe extern "C" fn(*mut Request, i32) -> i32
),
+ set_still_image: library
+ .get::<unsafe extern "C" fn(*mut Request, i32) -> i32>(b"slopfab_request_set_still_image\0")
+ .ok().map(|symbol| *symbol),
set_steps: symbol!(
"slopfab_request_set_steps",
unsafe extern "C" fn(*mut Request, i32) -> i32
@@ -1259,6 +1272,10 @@ mod ffi {
pub fn set_frames(&self, r: *mut Request, v: i32) -> Result<(), String> {
self.error(unsafe { (self.set_frames)(r, v) })
}
+ pub fn set_still_image(&self, r: *mut Request) -> Result<(), String> {
+ let set = self.set_still_image.ok_or("This slopfab.dll does not support still-image generation. Update the runtime to generate reference icons.")?;
+ self.error(unsafe { set(r, 1) })
+ }
pub fn set_steps(&self, r: *mut Request, v: i32) -> Result<(), String> {
self.error(unsafe { (self.set_steps)(r, v) })
}
@@ -1478,6 +1495,19 @@ mod tests {
assert_eq!(stage_name(4), "denoising");
assert_eq!(stage_name(99), "unknown");
}
+
+ #[test]
+ fn installed_dll_resolves_icons_as_one_still_frame_when_present() {
+ if !default_dll_path().is_file() { return; }
+ let request: GenerationRequest = serde_json::from_value(serde_json::json!({
+ "jobId": "icon-plan", "prompt": "A red toy car", "frames": 1, "stillImage": true,
+ "steps": 30, "seed": 1, "canvasWidth": 256, "canvasHeight": 256
+ })).unwrap();
+ let plan = resolve_plan(&request, &BTreeMap::new()).unwrap();
+ assert_eq!(plan.aligned_frames, 1);
+ assert_eq!(plan.latent_frames, 1);
+ assert_eq!((plan.canvas_width, plan.canvas_height), (256, 256));
+ }
#[test]
fn generation_seed_accepts_random_and_non_negative_values() {
assert!(generation_seed(-1).is_ok());
diff --git a/src/components/WorkQueuePanel.tsx b/src/components/WorkQueuePanel.tsx
index 47f8ffd..2d97214 100644
--- a/src/components/WorkQueuePanel.tsx
+++ b/src/components/WorkQueuePanel.tsx
@@ -26,7 +26,7 @@ export function WorkQueuePanel({ queue, items, onClose }: { queue: WorkQueue; it
return () => window.removeEventListener("keydown", keyDown, true);
}, [onClose]);
const current = items.filter((item) => isWorkActive(item) && item.status !== "queued");
- const upcoming = items.filter((item) => item.status === "queued");
+ const upcoming = items.filter((item) => item.status === "queued").sort((a, b) => Number(a.kind === "reference-icons") - Number(b.kind === "reference-icons"));
const finished = items.filter((item) => !isWorkActive(item)).slice().reverse();
const row = (item: WorkItem) => <li className={`work-queue__item${isWorkActive(item) && item.status !== "queued" ? "" : " work-queue__item--compact"}`} key={item.id}>
<div className="work-queue__item-heading">
@@ -39,7 +39,7 @@ export function WorkQueuePanel({ queue, items, onClose }: { queue: WorkQueue; it
<div className="work-queue__metadata">
<div className="work-queue__detail"><span>{item.detail}</span>{isWorkActive(item) && item.status !== "queued" && <b>{Math.floor(item.progress * 100)}%</b>}</div>
{isWorkActive(item) && item.status !== "queued" && <progress max={1} value={item.progress} aria-label={`${item.title} progress`} />}
- <p className="work-queue__settings">{item.settings.canvasWidth} × {item.settings.canvasHeight} · {(item.settings.frames / GENERATION_FRAME_RATE).toFixed(1)}s · {item.settings.steps} steps · {item.settings.seed === -1 ? "Random seed" : `Seed ${item.settings.seed}`}</p>
+ <p className="work-queue__settings">{item.settings.canvasWidth} × {item.settings.canvasHeight} · {item.kind === "reference-icons" ? "JPG icons" : `${(item.settings.frames / GENERATION_FRAME_RATE).toFixed(1)}s`} · {item.settings.steps} steps · {item.settings.seed === -1 ? "Random seed" : `Seed ${item.settings.seed}`}</p>
</div>
{item.error && <p className="work-queue__error">{item.error}</p>}
{item.needsSave && <button type="button" className="secondary-button" onClick={() => void queue.retrySave(item.id)}>Retry project save</button>}
diff --git a/src/components/workspace/ReferencesView.test.tsx b/src/components/workspace/ReferencesView.test.tsx
index dcad5be..c1fdc2c 100644
--- a/src/components/workspace/ReferencesView.test.tsx
+++ b/src/components/workspace/ReferencesView.test.tsx
@@ -115,7 +115,7 @@ describe("Reference type presets", () => {
it("keeps legacy uncategorized references editable", () => {
setup();
expect(screen.getByRole("combobox", { name: "Category" })).toHaveValue("custom");
- expect(screen.getByRole("button", { name: "Choose preset" })).toBeInTheDocument();
+ expect(screen.queryByRole("button", { name: "Choose preset" })).not.toBeInTheDocument();
expect(screen.queryByText("Intended use")).not.toBeInTheDocument();
expect(screen.queryByText(/Select any that apply/)).not.toBeInTheDocument();
expect(screen.getByRole("textbox", { name: "Prompt" })).toHaveValue("A traveler with a weathered red coat.");
@@ -123,8 +123,8 @@ describe("Reference type presets", () => {
it("chooses one prepared character from the scalable popup", () => {
const state = setup();
- fireEvent.click(screen.getByRole("button", { name: "Choose preset" }));
- const dialog = screen.getByRole("dialog", { name: "Choose a reference type" });
+ fireEvent.click(screen.getByRole("button", { name: /Add a reference/ }));
+ const dialog = screen.getByRole("dialog", { name: "Add a reference" });
fireEvent.click(within(dialog).getByRole("button", { name: "Character" }));
const groups = within(dialog).getByRole("group", { name: "Character subcategories" });
expect(within(groups).getByRole("button", { name: "Film" })).toBeInTheDocument();
@@ -145,8 +145,8 @@ describe("Reference type presets", () => {
it("shows a bundled MiniMax icon for an illustrated character preset", () => {
setup();
- fireEvent.click(screen.getByRole("button", { name: "Choose preset" }));
- const dialog = screen.getByRole("dialog", { name: "Choose a reference type" });
+ fireEvent.click(screen.getByRole("button", { name: /Add a reference/ }));
+ const dialog = screen.getByRole("dialog", { name: "Add a reference" });
fireEvent.click(within(dialog).getByRole("button", { name: "Character" }));
fireEvent.change(within(dialog).getByRole("textbox", { name: "Search reference options" }), { target: { value: "Abby Sciuto" } });
const preset = within(dialog).getByRole("button", { name: /Abby Sciuto/ });
@@ -154,17 +154,16 @@ describe("Reference type presets", () => {
expect(preset.querySelector(".reference-preset-icon")).toHaveAttribute("src");
fireEvent.click(preset);
- // Choosing a preset changes the definition, not the user's own reference
- // name. The selected preset still supplies the matching artwork.
- const detailIcon = screen.getByAltText("Hero reference icon");
+ // A built-in preset creates its own reference and supplies its artwork.
+ const detailIcon = screen.getByAltText("Abby Sciuto reference icon");
expect(detailIcon).toHaveAttribute("src");
expect(detailIcon.parentElement).toHaveClass("reference-detail-art--preset");
});
it("searches location templates and allows editing their prompt directly", () => {
const state = setup();
- fireEvent.click(screen.getByRole("button", { name: "Choose preset" }));
- const dialog = screen.getByRole("dialog", { name: "Choose a reference type" });
+ fireEvent.click(screen.getByRole("button", { name: /Add a reference/ }));
+ const dialog = screen.getByRole("dialog", { name: "Add a reference" });
fireEvent.click(within(dialog).getByRole("button", { name: "Location" }));
const groups = within(dialog).getByRole("group", { name: "Location subcategories" });
fireEvent.click(within(groups).getByRole("button", { name: "Sci-fi" }));
@@ -217,11 +216,13 @@ describe("Reference type presets", () => {
description: "Coastal village, at night, in winter.",
content: "Coastal village, at night, in winter.",
});
- fireEvent.click(screen.getByRole("button", { name: "Choose preset" }));
- const picker = screen.getByRole("dialog", { name: "Choose a reference type" });
+ fireEvent.click(screen.getByRole("button", { name: /Add a reference/ }));
+ const picker = screen.getByRole("dialog", { name: "Add a reference" });
+ fireEvent.click(within(picker).getByRole("button", { name: "Location" }));
fireEvent.change(within(picker).getByRole("textbox", { name: "Search reference options" }), { target: { value: "lunar" } });
fireEvent.click(within(picker).getByRole("button", { name: /Lunar base/ }));
- expect(restored.latest().references[0].description).toBe("Lunar base, at night, in winter.");
+ expect(restored.latest().references[0].description).toBe("Lunar base.");
+ expect(restored.latest().references[1].description).toBe("Coastal village, at night, in winter.");
fireEvent.click(screen.getByRole("button", { name: /Add a reference/ }));
const newPicker = screen.getByRole("dialog", { name: "Add a reference" });
fireEvent.click(within(newPicker).getByRole("button", { name: "Location" }));
diff --git a/src/components/workspace/ReferencesView.tsx b/src/components/workspace/ReferencesView.tsx
index b33e45b..090a332 100644
--- a/src/components/workspace/ReferencesView.tsx
+++ b/src/components/workspace/ReferencesView.tsx
@@ -31,7 +31,6 @@ export function ReferencesView({ config, folderPath, onChange }: { config: Proje
const [selectedId, setSelectedId] = useState<string | undefined>(config.references[0]?.id);
const [importError, setImportError] = useState<string | null>(null);
const [presetDialog, setPresetDialog] = useState(false);
- const [creatingReference, setCreatingReference] = useState(false);
const [pickerType, setPickerType] = useState<PresetReferenceType>("character");
const [pickerSubcategory, setPickerSubcategory] = useState("all");
const [presetSearch, setPresetSearch] = useState("");
@@ -57,7 +56,6 @@ export function ReferencesView({ config, folderPath, onChange }: { config: Proje
return id;
};
const openNewReference = () => {
- setCreatingReference(true);
setPickerType("character");
setPickerSubcategory("all");
setPresetSearch("");
@@ -93,28 +91,16 @@ export function ReferencesView({ config, folderPath, onChange }: { config: Proje
})) });
setSelectedId(config.references.find((ref) => ref.id !== selected.id)?.id);
};
- const openPresetPicker = () => {
- if (!selected) return;
- setCreatingReference(false);
- setPickerType(selectedType === "custom" ? "character" : selectedType);
- setPickerSubcategory("all");
- setPresetSearch("");
- setPresetDialog(true);
- };
const createEmptyReference = () => {
addTextReference(`New ${referenceTypeLabel(pickerType).toLocaleLowerCase()}`, "", pickerType, pickerSubcategory === "all" ? "" : pickerSubcategory);
setPresetDialog(false);
- setCreatingReference(false);
};
const choosePreset = (preset: ReferencePreset) => {
const prompt = preset.type === "location"
- ? composeLocationPrompt(preset, creatingReference ? {} : selectedLocation?.settings ?? {})
+ ? composeLocationPrompt(preset, {})
: preset.prompt;
- if (creatingReference) addTextReference(preset.name, prompt, preset.type, preset.subcategory);
- else if (selected) update(selected.id, { intendedUse: [preset.type], subcategory: preset.subcategory, description: prompt, content: prompt });
- else return;
+ addTextReference(preset.name, prompt, preset.type, preset.subcategory);
setPresetDialog(false);
- setCreatingReference(false);
};
const visiblePresets = REFERENCE_PRESETS.filter((preset) => {
if (preset.type !== pickerType) return false;
@@ -143,6 +129,8 @@ export function ReferencesView({ config, folderPath, onChange }: { config: Proje
return <button key={ref.id} className={selectedId === ref.id ? "selected" : ""} onClick={() => setSelectedId(ref.id)}>
{cover
? <span className="reference-art reference-art--photo"><ReferenceImage folderPath={folderPath} relativePath={cover.relativePath} sourcePath={cover.sourcePath} alt={cover.name} /></span>
+ : ref.iconRelativePath
+ ? <span className="reference-art reference-art--photo"><ReferenceImage folderPath={folderPath} relativePath={ref.iconRelativePath} alt={`${ref.name} icon`} /></span>
: presetIcon
? <span className="reference-art reference-art--photo"><img src={presetIcon} alt="" /></span>
: <span className="reference-copy-art"><FileText size={26} /><em>Text definition</em></span>}
@@ -171,22 +159,23 @@ export function ReferencesView({ config, folderPath, onChange }: { config: Proje
</> : <h2>Reference details</h2>}</header>
<div className="reference-inspector__scroll">
{selected ? <>
- <div className={`reference-detail-art${selectedImages.length > 0 || selectedPresetIcon ? " reference-detail-art--photo" : " reference-detail-art--text"}${selectedPresetIcon ? " reference-detail-art--preset" : ""}`}>
+ <div className={`reference-detail-art${selectedImages.length > 0 || selected.iconRelativePath || selectedPresetIcon ? " reference-detail-art--photo" : " reference-detail-art--text"}${selectedPresetIcon || selected.iconRelativePath ? " reference-detail-art--preset" : ""}`}>
{selectedImages.length > 0
? <div className="reference-detail-images">{selectedImages.map((image) => <ReferenceImage key={image.id} folderPath={folderPath} relativePath={image.relativePath} sourcePath={image.sourcePath} alt={image.name} />)}</div>
+ : selected.iconRelativePath
+ ? <ReferenceImage className="reference-detail-preset-icon" folderPath={folderPath} relativePath={selected.iconRelativePath} alt={`${selected.name} reference icon`} />
: selectedPresetIcon
? <img className="reference-detail-preset-icon" src={selectedPresetIcon} alt={`${selected.name} reference icon`} />
: <span><Users size={30} /></span>}
{/* A caption only where there is no picture to look at. It used
to print the file's path over the thumbnail, which is neither
what the reference IS nor anything the user acts on. */}
- {selectedImages.length === 0 && !selectedPresetIcon && <em>{referenceKindLabel(selected)}</em>}
+ {selectedImages.length === 0 && !selected.iconRelativePath && !selectedPresetIcon && <em>{referenceKindLabel(selected)}</em>}
</div>
<div className="reference-fields">
<label><span>Prompt</span><textarea value={selected.description} placeholder="Describe what should stay consistent — the traits, materials, colours, or wardrobe Slopus should preserve across shots." onChange={(event) => update(selected.id, { description: event.target.value, content: event.target.value || null, subcategory: selectedSubcategory })} /></label>
<div className="reference-fields__actions">
<button className="secondary-button" onClick={() => void addImages()}><ImagePlus size={16} /> Add images</button>
- <button className="secondary-button" onClick={openPresetPicker} aria-haspopup="dialog">Choose preset<ChevronRight size={16} /></button>
</div>
</div>
{selectedLocation && <section className="reference-location-settings" aria-label="Location settings">
@@ -218,10 +207,10 @@ export function ReferencesView({ config, folderPath, onChange }: { config: Proje
</> : <div className="reference-empty"><BookOpen size={26} /><b>Select a reference</b><p>Pick one from the library, or add a new one, to edit its definition and see which generations use it.</p></div>}
</div>
</aside>
- {presetDialog && (creatingReference || selected) && <div className="reference-dialog-backdrop"><div className="reference-preset-dialog" role="dialog" aria-modal="true" aria-labelledby="reference-preset-title">
+ {presetDialog && <div className="reference-dialog-backdrop"><div className="reference-preset-dialog" role="dialog" aria-modal="true" aria-labelledby="reference-preset-title">
<header>
- <div><h2 id="reference-preset-title">{creatingReference ? "Add a reference" : "Choose a reference type"}</h2><p>Choose a preset or create a new reference, then add a prompt and images.</p></div>
- <button onClick={() => { setPresetDialog(false); setCreatingReference(false); }} aria-label="Close type picker"><X size={18} /></button>
+ <div><h2 id="reference-preset-title">Add a reference</h2><p>Choose a preset or create a new reference, then add a prompt and images.</p></div>
+ <button onClick={() => setPresetDialog(false)} aria-label="Close type picker"><X size={18} /></button>
</header>
<div className="reference-preset-dialog__body">
<nav aria-label="Reference types">
diff --git a/src/lib/project.ts b/src/lib/project.ts
index 5519db2..86409f9 100644
--- a/src/lib/project.ts
+++ b/src/lib/project.ts
@@ -267,6 +267,8 @@ export const projectReferenceSchema = z.object({
images: z.array(projectReferenceImageSchema).optional(),
intendedUse: z.array(z.enum(["character", "product", "location", "style", "audio"])).default([]),
subcategory: z.string().optional(),
+ // Generated library artwork is not an image conditioning attachment.
+ iconRelativePath: projectRelativePathSchema.optional(),
createdAt: isoDateSchema,
}).superRefine((reference, context) => {
checkOneLocation(reference, context, `Reference '${reference.id}'`);
diff --git a/src/lib/referenceIconWork.test.ts b/src/lib/referenceIconWork.test.ts
new file mode 100644
index 0000000..00e5ae2
--- /dev/null
+++ b/src/lib/referenceIconWork.test.ts
@@ -0,0 +1,177 @@
+// @vitest-environment jsdom
+import { listen } from "@tauri-apps/api/event";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { releaseRendered, saveGeneratedScene } from "./generatedVideo";
+import { createProjectConfig, parseProjectConfig, referenceImages, type ProjectRecord, type ProjectReference } from "./project";
+import { REFERENCE_PRESETS } from "./reference-presets";
+import { referenceIconPrompt } from "./referenceIcons";
+import { cancelSlopfabGeneration, enqueueSlopfabGeneration, resolveSlopfabPlan, saveReferenceIcon } from "./runtime";
+import { WorkQueue } from "./workQueue";
+
+vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn() }));
+vi.mock("./generatedVideo", () => ({ releaseRendered: vi.fn(async () => true), saveGeneratedScene: vi.fn() }));
+vi.mock("./timelineThumbnails", () => ({ purgeTimelineThumbnails: vi.fn(async () => undefined) }));
+vi.mock("./runtime", () => ({ enqueueSlopfabGeneration: vi.fn(), resolveSlopfabPlan: vi.fn(), cancelSlopfabGeneration: vi.fn(), saveReferenceIcon: vi.fn() }));
+const handlers = new Map<string, (event: { payload: any }) => void>();
+let stop: () => void;
+const reference = (id: string, type: "character" | "product" | "location" | "style" = "character"): ProjectReference => ({
+ id, kind: "text", name: id, description: `User description for ${id}.`, intendedUse: [type], createdAt: "2026-09-07T00:00:00.000Z",
+});
+const project = (name: string, references: ProjectReference[] = []): ProjectRecord => ({ folderPath: `C:/${name}`, config: {
+ ...createProjectConfig({ name, prompt: "A scene", aspectRatio: "16:9", resolution: "416p", targetDurationSeconds: 10 }), references,
+} });
+const setup = (references: ProjectReference[] = []) => {
+ const saved = vi.fn(async (_record: ProjectRecord) => undefined);
+ const queue = new WorkQueue(saved);
+ stop = queue.start();
+ const session = queue.project(project("First", references));
+ return { queue, session, saved };
+};
+const flush = () => vi.advanceTimersByTimeAsync(0);
+const finish = async (id: string, state = "framesReady", detail = "Ready") => {
+ handlers.get("slopfab-job")?.({ payload: { jobId: id, state, detail } });
+ await flush();
+};
+const requests = () => vi.mocked(enqueueSlopfabGeneration).mock.calls.map(([request]) => request);
+const video = (queue: WorkQueue, session: ReturnType<WorkQueue["project"]>) => queue.enqueue(session, [{
+ job: session.getSnapshot().config.generationJobs[0], snapshot: "test", request: {
+ jobId: "video", prompt: "Video", frames: 120, steps: 12, seed: 1, canvasWidth: 736, canvasHeight: 416, referencePaths: [],
+ },
+}]);
+
+beforeEach(() => {
+ vi.useFakeTimers(); vi.clearAllMocks(); localStorage.clear(); handlers.clear();
+ Object.assign(window, { __TAURI_INTERNALS__: {} });
+ vi.mocked(listen).mockImplementation((async (name: string, handler: (event: { payload: any }) => void) => { handlers.set(name, handler); return () => { handlers.delete(name); }; }) as typeof listen);
+ vi.mocked(enqueueSlopfabGeneration).mockResolvedValue(undefined);
+ vi.mocked(resolveSlopfabPlan).mockResolvedValue({ alignedFrames: 120, canvasWidth: 736, canvasHeight: 416 } as Awaited<ReturnType<typeof resolveSlopfabPlan>>);
+ vi.mocked(saveGeneratedScene).mockResolvedValue({ relativePath: "media/generated/scene.mp4", bytes: 10, note: null });
+ vi.mocked(saveReferenceIcon).mockImplementation(async (_folder, id) => `references/icons/${id}.jpg`);
+ vi.mocked(cancelSlopfabGeneration).mockResolvedValue(true);
+});
+afterEach(() => { stop?.(); vi.useRealTimers(); delete (window as any).__TAURI_INTERNALS__; });
+
+it("groups icons across projects and gives waiting videos priority between icons", async () => {
+ const { queue, session } = setup([reference("hero")]);
+ const second = queue.project(project("Second", [reference("place", "location")]));
+ video(queue, session);
+ await vi.advanceTimersByTimeAsync(1001);
+ expect(requests()).toHaveLength(1);
+ expect(queue.getSnapshot().filter((item) => item.kind === "reference-icons")).toHaveLength(1);
+ expect(queue.hasActiveProject(second.record)).toBe(true);
+ await finish(requests()[0].jobId);
+ expect(requests()[1]).toMatchObject({ stillImage: true, frames: 1, canvasWidth: 256, canvasHeight: 256, steps: 30 });
+ expect(requests()[1].prompt).toContain("User description for hero.");
+ video(queue, second);
+ await finish(requests()[1].jobId);
+ expect(requests()[2].stillImage).not.toBe(true);
+ await finish(requests()[2].jobId);
+ expect(requests()[3].stillImage).toBe(true);
+ await finish(requests()[3].jobId);
+ expect(queue.getSnapshot().find((item) => item.kind === "reference-icons")).toMatchObject({ status: "completed", detail: "2/2 icons saved" });
+ expect(parseProjectConfig(session.getSnapshot().config).references[0].iconRelativePath).toMatch(/\.jpg$/);
+ expect(referenceImages(session.getSnapshot().config.references[0])).toEqual([]);
+ expect(saveReferenceIcon).toHaveBeenLastCalledWith("C:/Second", requests()[3].jobId);
+ expect(releaseRendered).toHaveBeenCalledWith(requests()[3].jobId);
+});
+
+it("waits for text and skips references that already have artwork", async () => {
+ const preset = REFERENCE_PRESETS.find((preset) => preset.icon)!;
+ const { session } = setup([
+ { ...reference("blank"), description: "" },
+ { ...reference("existing"), iconRelativePath: "references/icons/existing.jpg" },
+ { ...reference("photo"), images: [{ id: "photo", name: "Photo", relativePath: "references/photo.jpg" }] },
+ { ...reference("preset", preset.type), description: preset.prompt },
+ ]);
+ await vi.advanceTimersByTimeAsync(1001);
+ expect(requests()).toHaveLength(0);
+ session.update((current) => ({ ...current, references: current.references.map((ref) => ref.id === "blank" ? { ...ref, description: "A red toy car." } : ref) }));
+ await vi.advanceTimersByTimeAsync(1001);
+ expect(requests()).toHaveLength(1);
+ expect(requests()[0].prompt).toContain("A red toy car.");
+ await finish(requests()[0].jobId);
+ await vi.advanceTimersByTimeAsync(2000);
+ expect(requests()).toHaveLength(1);
+});
+
+it("discards stale results and uses the updated prompt without overwriting edits", async () => {
+ const { session } = setup([reference("hero")]);
+ await vi.advanceTimersByTimeAsync(1001);
+ session.update((current) => ({ ...current, name: "Renamed project", references: [{ ...current.references[0], description: "Changed user prompt." }] }));
+ await finish(requests()[0].jobId);
+ expect(saveReferenceIcon).not.toHaveBeenCalled();
+ expect(requests()[1].prompt).toContain("Changed user prompt.");
+ await finish(requests()[1].jobId);
+ expect(session.getSnapshot().config.name).toBe("Renamed project");
+ expect(session.getSnapshot().config.references[0].description).toBe("Changed user prompt.");
+});
+
+it("does not attach results to a deleted reference", async () => {
+ const { session } = setup([reference("hero")]);
+ await vi.advanceTimersByTimeAsync(1001);
+ session.update((current) => ({ ...current, references: [] }));
+ await finish(requests()[0].jobId);
+ expect(saveReferenceIcon).not.toHaveBeenCalled();
+ expect(session.getSnapshot().config.references).toHaveLength(0);
+});
+
+it("saves duplicate native completion events only once and waits before the next icon", async () => {
+ let written!: (path: string) => void;
+ vi.mocked(saveReferenceIcon).mockImplementationOnce(() => new Promise((resolve) => { written = resolve; }));
+ const { session } = setup([reference("hero"), reference("place", "location")]);
+ await vi.advanceTimersByTimeAsync(1001);
+ const id = requests()[0].jobId;
+ await finish(id);
+ await finish(id);
+ expect(saveReferenceIcon).toHaveBeenCalledTimes(1);
+ expect(requests()).toHaveLength(1);
+ written("references/icons/hero.jpg");
+ await flush();
+ expect(session.getSnapshot().config.references[0].iconRelativePath).toBe("references/icons/hero.jpg");
+ expect(requests()).toHaveLength(2);
+ await finish(requests()[1].jobId);
+});
+
+it("cancels an icon even if its native enqueue acknowledgement arrives late", async () => {
+ let accepted!: () => void;
+ vi.mocked(enqueueSlopfabGeneration).mockImplementationOnce(() => new Promise((resolve) => { accepted = resolve; }));
+ const { queue } = setup([reference("hero")]);
+ await vi.advanceTimersByTimeAsync(1001);
+ await queue.cancel(queue.getSnapshot()[0].id);
+ expect(cancelSlopfabGeneration).not.toHaveBeenCalled();
+ accepted(); await flush();
+ expect(cancelSlopfabGeneration).toHaveBeenCalledWith(requests()[0].jobId);
+ await finish(requests()[0].jobId, "cancelled", "Cancelled");
+ expect(queue.getSnapshot()[0].status).toBe("cancelled");
+});
+
+it("cancels the entire icon batch and does not automatically requeue cancelled work", async () => {
+ const { queue } = setup([reference("hero"), reference("place", "location")]);
+ await vi.advanceTimersByTimeAsync(1001);
+ await queue.cancel(queue.getSnapshot()[0].id);
+ expect(cancelSlopfabGeneration).toHaveBeenCalledWith(requests()[0].jobId);
+ await finish(requests()[0].jobId, "cancelled", "Cancelled");
+ await vi.advanceTimersByTimeAsync(2000);
+ expect(requests()).toHaveLength(1);
+ expect(queue.getSnapshot()[0].status).toBe("cancelled");
+});
+
+it("continues after a failed icon and retries persistence without generating again", async () => {
+ const { queue, saved } = setup([reference("hero"), reference("place", "location")]);
+ await vi.advanceTimersByTimeAsync(1001);
+ await finish(requests()[0].jobId, "failed", "Runtime error");
+ expect(requests()).toHaveLength(2);
+ saved.mockRejectedValueOnce(new Error("Disk locked"));
+ await finish(requests()[1].jobId);
+ expect(queue.getSnapshot()[0]).toMatchObject({ status: "failed", needsSave: true });
+ await queue.retrySave(queue.getSnapshot()[0].id);
+ expect(queue.getSnapshot()[0].needsSave).toBe(false);
+ expect(requests()).toHaveLength(2);
+ expect(queue.getSnapshot()[0].error).toContain("Runtime error");
+});
+
+it("uses a distinct composition for every reference type and preserves the user's prompt", () => {
+ const prompts = ["character", "product", "location", "style"].map((type) => referenceIconPrompt(reference("example", type as "character")));
+ expect(new Set(prompts).size).toBe(4);
+ for (const prompt of prompts) expect(prompt).toContain("User description for example.");
+});
diff --git a/src/lib/referenceIconWork.ts b/src/lib/referenceIconWork.ts
new file mode 100644
index 0000000..012a54b
--- /dev/null
+++ b/src/lib/referenceIconWork.ts
@@ -0,0 +1,238 @@
+import { describeDiagnosticError } from "./diagnostics";
+import { releaseRendered } from "./generatedVideo";
+import { isTauri } from "./persistence";
+import type { ProjectSession } from "./projectSession";
+import { needsReferenceIcon, referenceIconPrompt, REFERENCE_ICON_SIZE, REFERENCE_ICON_STEPS } from "./referenceIcons";
+import { cancelSlopfabGeneration, enqueueSlopfabGeneration, saveReferenceIcon } from "./runtime";
+import { withEngineSettings } from "./settings";
+import type { WorkItem } from "./workQueue";
+
+type TaskStatus = "queued" | "generating" | "saving" | "completed" | "failed" | "cancelled" | "skipped";
+interface IconTask {
+ key: string;
+ session: ProjectSession;
+ referenceId: string;
+ name: string;
+ prompt: string;
+ status: TaskStatus;
+ nativeId?: string;
+ submitted: boolean;
+ cancelled: boolean;
+ error?: string;
+ needsSave?: boolean;
+ finish?: () => void;
+}
+
+/** One visible batch across projects. The owner runs only one icon at a time,
+ * returning to its video-priority scheduler after each native result is freed. */
+export class ReferenceIconWork {
+ private tasks = new Map<string, IconTask>();
+ private timers = new Map<ProjectSession, ReturnType<typeof setTimeout>>();
+ private active?: IconTask;
+ private progress = 0;
+ private item?: WorkItem;
+ private watches = new Map<ProjectSession, () => void>();
+
+ constructor(private changed: (item: WorkItem) => void, private wake: () => void) {}
+
+ watch(session: ProjectSession) {
+ if (!isTauri() || this.watches.has(session)) return;
+ let references = session.getSnapshot().config.references;
+ const schedule = () => {
+ clearTimeout(this.timers.get(session));
+ this.timers.set(session, setTimeout(() => {
+ this.timers.delete(session);
+ this.scan(session);
+ }, 1000));
+ };
+ this.watches.set(session, session.subscribe(() => {
+ const next = session.getSnapshot().config.references;
+ if (next === references) return;
+ references = next;
+ schedule();
+ }));
+ schedule();
+ }
+
+ forget(session: ProjectSession) {
+ clearTimeout(this.timers.get(session));
+ this.timers.delete(session);
+ this.watches.get(session)?.();
+ this.watches.delete(session);
+ for (const [key, task] of this.tasks) if (task.session === session) this.tasks.delete(key);
+ }
+
+ stop() {
+ this.timers.forEach(clearTimeout);
+ this.timers.clear();
+ this.watches.forEach((stop) => stop());
+ this.watches.clear();
+ }
+
+ scan(session: ProjectSession) {
+ const references = session.getSnapshot().config.references;
+ for (const task of this.tasks.values()) {
+ if (task.session !== session || task.status !== "queued") continue;
+ const reference = references.find((reference) => reference.id === task.referenceId);
+ if (!reference || !needsReferenceIcon(reference)) task.status = "skipped";
+ }
+ let added = false;
+ for (const reference of references) {
+ if (!needsReferenceIcon(reference)) continue;
+ const key = `${session.record.folderPath}::${session.record.config.id}::${reference.id}`;
+ const prompt = referenceIconPrompt(reference);
+ const previous = this.tasks.get(key);
+ if (previous && (previous === this.active || (previous.prompt === prompt && previous.status !== "skipped"))) continue;
+ this.tasks.set(key, { key, session, referenceId: reference.id, name: reference.name, prompt, status: "queued", submitted: false, cancelled: false });
+ added = true;
+ }
+ if (added && !this.item) {
+ this.item = {
+ id: `icons-${crypto.randomUUID()}`, kind: "reference-icons", projectKey: "", folderPath: "", projectName: "", sceneId: "",
+ title: "Reference icons", submittedAt: new Date().toISOString(), status: "queued", progress: 0,
+ detail: "Waiting to generate icons", error: null, completionAt: null, cancelling: false, needsSave: false,
+ settings: { frames: 1, steps: REFERENCE_ICON_STEPS, seed: -1, canvasWidth: REFERENCE_ICON_SIZE, canvasHeight: REFERENCE_ICON_SIZE },
+ };
+ }
+ this.publish();
+ if (added) this.wake();
+ }
+
+ hasQueued() { return [...this.tasks.values()].some((task) => task.status === "queued"); }
+ hasActiveProject(session: ProjectSession) {
+ return [...this.tasks.values()].some((task) => task.session === session && ["queued", "generating", "saving"].includes(task.status));
+ }
+ owns(id: string) { return this.item?.id === id; }
+ clearFinished(id: string) { if (this.owns(id)) this.item = undefined; }
+
+ private publish() {
+ if (!this.item) return;
+ const tasks = [...this.tasks.values()].filter((task) => task.status !== "skipped");
+ const completed = tasks.filter((task) => task.status === "completed").length;
+ const settled = tasks.filter((task) => ["completed", "failed", "cancelled"].includes(task.status)).length;
+ const queued = this.hasQueued();
+ const failed = tasks.filter((task) => task.status === "failed");
+ const projects = new Set(tasks.map((task) => task.session));
+ this.item = {
+ ...this.item,
+ projectName: projects.size === 1 ? [...projects][0].getSnapshot().config.name : `${projects.size} projects`,
+ status: this.active ? (this.active.status === "saving" ? "encoding" : "generating") : queued ? "queued" : failed.length ? "failed" : tasks.some((task) => task.status === "cancelled") ? "cancelled" : "completed",
+ progress: tasks.length ? Math.min(1, (settled + (this.active ? this.progress : 0)) / tasks.length) : 1,
+ detail: this.active ? `${this.active.cancelled ? "Cancelling" : this.active.status === "saving" ? "Saving" : "Generating"} ${this.active.name} · ${completed}/${tasks.length} icons saved`
+ : queued ? `${completed}/${tasks.length} icons saved · waiting behind videos` : `${completed}/${tasks.length} icons saved`,
+ error: failed.length ? failed.map((task) => `${task.name}: ${task.error}`).join("\n") : null,
+ cancelling: this.active?.cancelled ?? false,
+ needsSave: tasks.some((task) => task.needsSave),
+ };
+ this.changed(this.item);
+ }
+
+ async runNext(ready: Promise<void>, videoWaiting: () => boolean) {
+ const task = [...this.tasks.values()].find((task) => task.status === "queued");
+ if (!task) return;
+ this.active = task;
+ task.status = "generating";
+ this.progress = 0;
+ this.publish();
+ try {
+ await ready;
+ if (task.cancelled) return;
+ await task.session.save();
+ if (task.cancelled) return;
+ if (videoWaiting()) { task.status = "queued"; return; }
+ const reference = task.session.getSnapshot().config.references.find((reference) => reference.id === task.referenceId);
+ if (!reference || !needsReferenceIcon(reference)) { task.status = "skipped"; return; }
+ task.prompt = referenceIconPrompt(reference);
+ task.name = reference.name;
+ task.nativeId = `icon-${crypto.randomUUID()}`;
+ const done = new Promise<void>((resolve) => { task.finish = resolve; });
+ await enqueueSlopfabGeneration({
+ jobId: task.nativeId, prompt: task.prompt, stillImage: true, frames: 1,
+ steps: REFERENCE_ICON_STEPS, seed: -1, canvasWidth: REFERENCE_ICON_SIZE, canvasHeight: REFERENCE_ICON_SIZE, referencePaths: [],
+ }, withEngineSettings(task.session.getSnapshot().config));
+ task.submitted = true;
+ if (task.cancelled) await this.cancelNative(task);
+ await done;
+ } catch (reason) {
+ task.status = task.cancelled ? "cancelled" : "failed";
+ task.error = describeDiagnosticError(reason);
+ } finally {
+ if (task.cancelled) task.status = "cancelled";
+ this.active = undefined;
+ this.publish();
+ this.scan(task.session);
+ }
+ }
+
+ progressEvent(event: { jobId: string; step: number; totalSteps: number }): boolean {
+ if (!this.active || this.active.nativeId !== event.jobId) return false;
+ this.progress = Math.max(this.progress, event.totalSteps > 0 ? Math.min(0.9, 0.1 + event.step / event.totalSteps * 0.8) : 0.05);
+ this.publish();
+ return true;
+ }
+
+ event(event: { jobId: string; state: string; detail: string }): boolean {
+ const task = this.active;
+ if (!task || task.nativeId !== event.jobId) return false;
+ if (task.status === "saving") return true;
+ if (event.state === "framesReady") {
+ task.status = "saving";
+ this.publish();
+ void this.save(task);
+ } else if (event.state === "failed" || event.state === "cancelled") {
+ task.status = task.cancelled || event.state === "cancelled" ? "cancelled" : "failed";
+ task.error = event.detail;
+ task.finish?.();
+ }
+ return true;
+ }
+
+ private async save(task: IconTask) {
+ try {
+ const reference = task.session.getSnapshot().config.references.find((reference) => reference.id === task.referenceId);
+ if (task.cancelled) { task.status = "cancelled"; return; }
+ if (!reference || !needsReferenceIcon(reference) || referenceIconPrompt(reference) !== task.prompt) { task.status = "skipped"; return; }
+ const iconRelativePath = await saveReferenceIcon(task.session.record.folderPath, task.nativeId!);
+ let attached = false;
+ task.session.update((current) => ({ ...current, references: current.references.map((reference) => {
+ if (reference.id !== task.referenceId || !needsReferenceIcon(reference) || referenceIconPrompt(reference) !== task.prompt) return reference;
+ attached = true;
+ return { ...reference, iconRelativePath };
+ }) }));
+ if (!attached) { task.status = "skipped"; return; }
+ task.needsSave = true;
+ await task.session.save();
+ task.needsSave = false;
+ task.status = "completed";
+ } catch (reason) {
+ task.status = "failed";
+ task.error = describeDiagnosticError(reason);
+ } finally {
+ await releaseRendered(task.nativeId!);
+ task.finish?.();
+ }
+ }
+
+ async cancel() {
+ for (const task of this.tasks.values()) {
+ if (task.status === "queued") { task.cancelled = true; task.status = "cancelled"; }
+ }
+ if (this.active && this.active.status !== "saving") {
+ this.active.cancelled = true;
+ if (this.active.submitted) await this.cancelNative(this.active);
+ }
+ this.publish();
+ }
+ private async cancelNative(task: IconTask) {
+ try { await cancelSlopfabGeneration(task.nativeId!); }
+ catch (reason) { task.cancelled = false; task.error = describeDiagnosticError(reason); }
+ }
+ async retrySave() {
+ for (const task of this.tasks.values()) {
+ if (!task.needsSave) continue;
+ try { await task.session.save(); task.needsSave = false; task.status = "completed"; task.error = undefined; }
+ catch (reason) { task.error = describeDiagnosticError(reason); }
+ }
+ this.publish();
+ }
+}
diff --git a/src/lib/referenceIcons.ts b/src/lib/referenceIcons.ts
new file mode 100644
index 0000000..c4e8858
--- /dev/null
+++ b/src/lib/referenceIcons.ts
@@ -0,0 +1,29 @@
+import { referenceImages, type ProjectReference } from "./project";
+import { referenceType, selectedReferencePreset } from "./reference-presets";
+
+export const REFERENCE_ICON_SIZE = 256;
+export const REFERENCE_ICON_STEPS = 30;
+
+const COMPOSITIONS = {
+ character: "A clear head-and-shoulders character portrait. Emphasize recognizable facial features, hair, clothing, and personality against a simple background.",
+ product: "A clean hero view of the product. Show its complete silhouette, materials, colors, and defining details with controlled lighting and an uncluttered background.",
+ location: "An establishing view of the location. Show its defining architecture or landscape, atmosphere, lighting, and spatial character in a readable composition.",
+ style: "A representative scene demonstrating the visual style. Make its palette, medium, textures, lighting, and composition immediately recognizable.",
+ custom: "A clear visual representation of the reference's defining subject, appearance, and atmosphere.",
+};
+
+export function referenceIconPrompt(reference: ProjectReference): string {
+ return [
+ "Create one square reference-library icon, composed to remain recognizable at 256 by 256 pixels.",
+ COMPOSITIONS[referenceType(reference)],
+ "Follow the reference description's visual medium and details. No captions, lettering, watermarks, borders, or collage panels.",
+ `Reference name: ${reference.name}`,
+ reference.subcategory ? `Subcategory: ${reference.subcategory}` : "",
+ `Reference description:\n${reference.description.trim()}`,
+ ].filter(Boolean).join("\n\n");
+}
+
+export function needsReferenceIcon(reference: ProjectReference): boolean {
+ return Boolean(reference.description.trim()) && !reference.iconRelativePath
+ && referenceImages(reference).length === 0 && !selectedReferencePreset(reference)?.icon;
+}
diff --git a/src/lib/runtime.ts b/src/lib/runtime.ts
index bac65b0..4c59f6a 100644
--- a/src/lib/runtime.ts
+++ b/src/lib/runtime.ts
@@ -79,6 +79,7 @@ export interface SlopfabGenerationRequest {
jobId: string;
prompt: string;
frames: number;
+ stillImage?: boolean;
steps: number;
seed: number;
canvasWidth: number;
@@ -221,6 +222,10 @@ export async function cancelSlopfabGeneration(jobId: string): Promise<boolean> {
return isTauri() ? invoke<boolean>("cancel_slopfab_generation", { jobId }) : true;
}
+export async function saveReferenceIcon(folderPath: string, jobId: string): Promise<string> {
+ return invoke<string>("save_reference_icon", { folderPath, jobId });
+}
+
function demoTurn(_config: ProjectConfig, prompt: string): AgentTurnResult {
const clean = prompt.trim();
if (/\b(which|what)\b.*\?/i.test(clean)) {
diff --git a/src/lib/workQueue.ts b/src/lib/workQueue.ts
index f3848fe..f1a1150 100644
--- a/src/lib/workQueue.ts
+++ b/src/lib/workQueue.ts
@@ -8,10 +8,12 @@ import { ProjectSession, type ProjectWriter } from "./projectSession";
import { cancelSlopfabGeneration, enqueueSlopfabGeneration, resolveSlopfabPlan, type SlopfabGenerationRequest } from "./runtime";
import { withEngineSettings } from "./settings";
import { purgeTimelineThumbnails } from "./timelineThumbnails";
+import { ReferenceIconWork } from "./referenceIconWork";
export type WorkStatus = "queued" | "preparing" | "generating" | "encoding" | "completed" | "failed" | "cancelled";
export interface GenerationSubmission { job: GenerationJob; request: SlopfabGenerationRequest; snapshot: string }
export interface WorkItem {
+ kind?: "reference-icons";
id: string;
projectKey: string;
folderPath: string;
@@ -60,6 +62,12 @@ export class WorkQueue {
private timing = new GenerationTimingEstimator();
private connections = 0;
private disconnect: (() => void) | null = null;
+ private icons = new ReferenceIconWork((item) => {
+ this.items = this.items.some((current) => current.id === item.id)
+ ? this.items.map((current) => current.id === item.id ? item : current)
+ : [...this.items, item];
+ this.publish();
+ }, () => { void this.pump(); });
ready: Promise<void> = Promise.resolve();
constructor(private writer: ProjectWriter = saveProject) {}
@@ -81,21 +89,29 @@ export class WorkQueue {
session = new ProjectSession({ ...record, config }, this.writer);
this.projects.set(key, session);
}
+ this.icons.watch(session);
return session;
}
- hasActiveProject(record: ProjectRecord) { return this.items.some((item) => item.projectKey === projectQueueKey(record) && isWorkActive(item)); }
+ hasActiveProject(record: ProjectRecord) {
+ const session = this.projects.get(projectQueueKey(record));
+ return Boolean(session && this.icons.hasActiveProject(session)) || this.items.some((item) => item.projectKey === projectQueueKey(record) && isWorkActive(item));
+ }
forgetProject(record: ProjectRecord) {
if (this.hasActiveProject(record)) throw new Error("Cancel or finish this project's work before deleting it.");
+ const session = this.projects.get(projectQueueKey(record));
+ if (session) this.icons.forget(session);
this.projects.delete(projectQueueKey(record));
}
clearFinished() {
const cleared = this.items.filter((item) => !isWorkActive(item) && !item.needsSave);
cleared.forEach((item) => this.work.delete(item.id));
+ cleared.forEach((item) => this.icons.clearFinished(item.id));
this.items = this.items.filter((item) => isWorkActive(item) || item.needsSave);
this.publish();
}
start = () => {
this.connections += 1;
+ this.projects.forEach((session) => this.icons.watch(session));
if (this.connections === 1 && isTauri()) {
let disposed = false;
const stops: (() => void)[] = [];
@@ -112,7 +128,7 @@ export class WorkQueue {
}
return () => {
this.connections -= 1;
- if (this.connections === 0) { this.disconnect?.(); this.disconnect = null; }
+ if (this.connections === 0) { this.disconnect?.(); this.disconnect = null; this.icons.stop(); }
};
};
@@ -150,8 +166,12 @@ export class WorkQueue {
this.pumping = true;
try {
while (true) {
- const next = this.items.find((item) => item.status === "queued");
- if (!next) break;
+ const next = this.items.find((item) => item.status === "queued" && item.kind !== "reference-icons");
+ if (!next) {
+ if (!this.icons.hasQueued()) break;
+ await this.icons.runNext(this.ready, () => this.items.some((item) => item.status === "queued" && item.kind !== "reference-icons"));
+ continue;
+ }
const work = this.work.get(next.id)!;
this.patch(work.id, { status: "preparing", detail: "Preparing generation" });
try {
@@ -176,6 +196,7 @@ export class WorkQueue {
} finally { this.pumping = false; }
}
async cancel(id: string): Promise<void> {
+ if (this.icons.owns(id)) { await this.icons.cancel(); return; }
const item = this.items.find((candidate) => candidate.id === id);
const work = this.work.get(id);
if (!item || !work || !isWorkActive(item) || item.status === "encoding" || item.cancelling) return;
@@ -219,6 +240,7 @@ export class WorkQueue {
work.finish();
}
private progress(event: GenerationTimingProgress) {
+ if (this.icons.progressEvent(event)) return;
const work = this.work.get(event.jobId);
const item = this.items.find((candidate) => candidate.id === event.jobId);
if (!work || !item || !["preparing", "generating"].includes(item.status)) return;
@@ -227,6 +249,7 @@ export class WorkQueue {
this.updateScene(work, { status: "generating", stage: event.stage === "starting" || event.stage === "transformerLoad" ? "preparing" : "generating", progress }, false);
}
private event(event: JobEvent) {
+ if (this.icons.event(event)) return;
const work = this.work.get(event.jobId);
const item = this.items.find((candidate) => candidate.id === event.jobId);
if (!work || !item) return;
@@ -276,6 +299,7 @@ export class WorkQueue {
finally { await releaseRendered(work.id); work.finish(); }
}
async retrySave(id: string) {
+ if (this.icons.owns(id)) { await this.icons.retrySave(); return; }
const work = this.work.get(id);
if (!work) return;
try { await work.session.save(); this.patch(id, { status: "completed", needsSave: false, error: null, detail: "Video saved" }); }