AI media harness for planning, generating, and editing locally
TypeScript
Add granular image agent commands
Bitti9cb4ac3ceedb
diff --git a/README.md b/README.mdindex e306c88..d4a7c7d 100644--- a/README.md+++ b/README.md@@ -25,6 +25,8 @@ New projects can be **Image projects** or **Video projects**. Existing projectsImage projects use **Agent**, **Editor**, and **References** tabs. In the Editor, build a hierarchy of objects, text and groups on the left, arrange their placement boxes in the center, and edit descriptions, style, colors and generation settings in the right inspector. Choose a MiniMax H3 generator template above the canvas and press **Generate**. Generation uses the native SlopFab runtime without Python. Full-resolution JPEGs are saved in `media/generated/`, remain available in the image history, and can be exported from the canvas toolbar. Placement boxes guide the model through the prompt; they are not exact masks.+The Agent can add, edit, reorder, reparent, duplicate and remove image nodes, and adjust prompts, style, placement, palettes, references, steps and seeds. Edits are transactional and preserve generated images. See the [image command guide](src-tauri/assets/agent-image.md) for the command vocabulary and examples.+> **GPU recommendation:** A GPU with **24 GB of VRAM or more** is currently recommended for local video generation. We plan to reduce VRAM usage in future updates.diff --git a/fixtures/image-commands.json b/fixtures/image-commands.jsonnew file mode 100644index 0000000..9433ed0--- /dev/null+++ b/fixtures/image-commands.json@@ -0,0 +1,33 @@+{+ "commands": [+ { "op": "image.configure", "prompt": "Balloons over the sea", "background": "Blue sky", "style": { "lighting": "Soft morning light" }, "steps": 12, "seed": 123 },+ { "op": "image.node.add", "id": "sky", "parent": "image-root", "kind": "group", "name": "Sky", "box": { "x": 100, "y": 100, "width": 600, "height": 600 } },+ { "op": "image.node.add", "id": "balloon", "parent": "sky", "kind": "object", "name": "Balloon", "description": "A red balloon", "box": { "x": 200, "y": 200, "width": 100, "height": 100 } },+ { "op": "image.node.add", "id": "caption", "parent": "sky", "kind": "text", "name": "Caption", "text": "UP", "colors": ["#FF0000"] },+ { "op": "image.node.move", "id": "caption", "parent": "image-root", "before": "group-rocket" },+ { "op": "image.node.set", "id": "sky", "box": { "x": 200, "y": 200, "width": 300, "height": 300 } },+ { "op": "image.node.duplicate", "id": "sky", "newId": "sky-copy", "before": "group-rocket" },+ { "op": "image.node.move", "id": "sky-copy--balloon", "parent": "caption" },+ { "op": "image.node.remove", "id": "sky" },+ { "op": "image.node.set", "id": "caption", "text": "Float", "box": null }+ ],+ "invalid": [+ { "op": "image.node.move", "id": "group-rocket", "parent": "title" },+ { "op": "image.node.move", "id": "title", "parent": "image-root", "before": "title" },+ { "op": "image.node.move", "id": "title", "parent": "group-rocket", "before": "image-root" },+ { "op": "image.node.move", "id": "image-root", "parent": "group-rocket" },+ { "op": "image.node.remove", "id": "image-root" },+ { "op": "image.node.remove", "id": "missing" },+ { "op": "image.node.duplicate", "id": "image-root", "newId": "another-root" },+ { "op": "image.node.duplicate", "id": "group-rocket", "newId": "title" },+ { "op": "image.node.add", "id": "new", "parent": "missing", "kind": "text", "name": "New" },+ { "op": "image.node.add", "id": "title", "parent": "image-root", "kind": "text", "name": "Duplicate ID" },+ { "op": "image.node.set", "id": "title", "box": { "x": 900, "y": 0, "width": 200, "height": 100 } },+ { "op": "image.node.set", "id": "title" },+ { "op": "image.configure", "style": {} },+ { "op": "image.configure", "steps": 1 },+ { "op": "image.configure", "referenceIds": ["missing"] },+ { "op": "image.configure", "outputAssetId": "overwrite" },+ { "op": "image.node.set", "id": "title", "relativePath": "outside.jpg" }+ ]+}diff --git a/src-tauri/assets/agent-image.md b/src-tauri/assets/agent-image.mdindex 900d0dc..49e03e3 100644--- a/src-tauri/assets/agent-image.md+++ b/src-tauri/assets/agent-image.md@@ -1,6 +1,23 @@This is an IMAGE project. Apply these image-specific instructions instead of video planning instructions. The model is MiniMax H3 in native still-image mode. There is no timeline, soundtrack, scene sequence, or Python worker in this workflow. Use the Agent, Editor and References tabs.-Author the image tree with this command, then a commit line:+Prefer small, targeted commands for edits to the image hierarchy. Unmentioned fields and unrelated nodes are preserved. Every edit response is JSONL with a final {"op":"commit","summary":"..."} line, just like other project commands.++- {"op":"image.configure","prompt"?:string,"background"?:string,"style"?:{"mode"?:"photo"|"art","aesthetics"?:string,"lighting"?:string,"medium"?:string,"detail"?:string},"steps"?:integer,"seed"?:integer,"referenceIds"?:string[]}. Updates only supplied fields; prompt edits the root description. Style merges supplied fields. An empty string clears a description, [] clears references. Use project.set for resolution and aspectRatio.+- {"op":"image.node.add","id":string,"parent":existing-node-id,"kind":"object"|"text"|"group"|"background","name":string,"description"?:string,"text"?:string,"box"?:box|null,"colors"?:string[],"before"?:sibling-id|null}. Adds a node under parent. Optional text and description default to empty, colors to [], and box to null (automatic placement). before inserts before an existing child of parent; omit it or use null to append.+- {"op":"image.node.set","id":existing-node-id,"name"?:string,"description"?:string,"text"?:string,"box"?:box|null,"colors"?:string[]}. Edits only supplied fields. Setting box moves/resizes the node and transforms its descendants' boxes with it. box:null clears only this node's explicit placement; omission leaves placement unchanged. [] clears its palette. Root description is the image prompt.+- {"op":"image.node.move","id":existing-node-id,"parent":destination-node-id,"before"?:sibling-id|null}. Reparents and/or reorders the node with its subtree. before must be a child of the destination parent. Omit it or use null to append. Absolute placement stays unchanged. A node cannot become its own ancestor.+- {"op":"image.node.duplicate","id":existing-node-id,"newId":unique-id,"parent"?:destination-node-id,"before"?:sibling-id|null}. Copies the entire subtree, preserving descriptions and placement. The copied root uses newId; each copied descendant uses newId + "--" + its original ID. All resulting IDs must be unique. Parent defaults to the original parent. Rename or reposition the copy with image.node.set.+- {"op":"image.node.remove","id":existing-node-id}. Removes the node and all descendants. Never remove, move or duplicate the root. The root may be edited with image.node.set or image.configure.++Example: add a grouped title, then refine its typography without replacing other nodes:+{"op":"image.node.add","id":"headline-group","parent":"image-root","kind":"group","name":"Headline","box":{"x":100,"y":100,"width":800,"height":200}}+{"op":"image.node.add","id":"headline-text","parent":"headline-group","kind":"text","name":"Title","text":"LIFT OFF","description":"Bold condensed lettering","box":{"x":150,"y":150,"width":700,"height":100}}+{"op":"image.node.set","id":"headline-text","colors":["#FF0000"],"description":"Bold red condensed lettering with subtle shadow"}+{"op":"commit","summary":"Added a grouped red headline."}++Use the actual root ID in the current document; image-root is the default. Commands apply transactionally: a missing target, cycle, invalid placement, duplicate ID, or invalid setting rejects the whole batch. Generated images, assets, outputAssetId, file paths and provider settings cannot be edited with these commands. There are no generation commands: the user controls Generate in the Editor.++For an explicitly requested complete composition replacement, the older full-authoring command remains available:{"op":"image.set","nodes":[...],"background":"environment description","style":{"mode":"photo","aesthetics":"","lighting":"","medium":"","detail":"camera/lens or art style"},"steps":20,"seed":-1,"referenceIds":[]}All fields are required; copy unchanged authored fields from imageScene in the current project. Do not send outputAssetId: generated results belong to the app. Each node has exactly these fields:@@ -8,4 +25,4 @@ All fields are required; copy unchanged authored fields from imageScene in the cUse exactly one root with parentId null. Other nodes have kind group, object, text or background, and parentId naming an existing node. IDs must be unique and the tree connected and acyclic. Objects, groups and text may carry box {"x":100,"y":100,"width":400,"height":600} in 0–1000 image coordinates; extents must be positive and stay within the image. Box null means automatic placement. A group's description provides context to its children. Text nodes use text for the exact lettering and description for appearance. Colors are hex #RRGGBB strings (up to 16). Names are short tree labels; put visual instructions in description. At most 500 nodes. Style mode is photo or art, steps 2–1000, seed -1 for random or a nonnegative safe integer. Placement is prose guidance to H3, not a guaranteed pixel mask.-Use project.set for project name, resolution and aspectRatio. Use ref.add/ref.set for reusable descriptions, then include their IDs in image.set referenceIds. Bind only existing image/text references. Do not create scene.*, shot.* or clip.* commands for image projects. Preserve the current image composition unless asked to change it. Never invent files or claim to have generated an image: the user runs Generate in the Editor.+Use project.set for project name, resolution and aspectRatio. Use ref.add/ref.set for reusable descriptions, then include their IDs in image.configure referenceIds. Unbind a reference before ref.remove. Bind only existing image/text references. Do not create scene.*, shot.* or clip.* commands for image projects. Preserve the current image composition unless asked to change it. Never invent files or claim to have generated an image: the user runs Generate in the Editor.diff --git a/src-tauri/src/project/commands/batch.rs b/src-tauri/src/project/commands/batch.rsindex 3c84611..e13e454 100644--- a/src-tauri/src/project/commands/batch.rs+++ b/src-tauri/src/project/commands/batch.rs@@ -80,42 +80,14 @@ fn apply_command(effects: &mut Effects,) -> Result<(), String> {match command {- ProjectCommand::ImageSet {- nodes,- background,- style,- steps,- seed,- reference_ids,- } => {- if project.generation_type != crate::project::GenerationType::Image {- return Err("image.set requires an image project.".into());- }- let scene = crate::project::image::ImageScene {- nodes: nodes.clone(),- background: background.clone(),- style: style.clone(),- steps: *steps,- seed: *seed,- reference_ids: reference_ids.clone(),- output_asset_id: project- .image_scene- .as_ref()- .and_then(|scene| scene.output_asset_id.clone()),- };- scene.validate()?;- for id in reference_ids {- if !project- .references- .iter()- .any(|reference| &reference.id == id)- {- return Err(format!("Image reference '{id}' does not exist."));- }- }- project.image_scene = Some(scene);- project.updated_at = timestamp.into();- Ok(())+ ProjectCommand::ImageSet { .. }+ | ProjectCommand::ImageConfigure { .. }+ | ProjectCommand::ImageNodeAdd { .. }+ | ProjectCommand::ImageNodeSet { .. }+ | ProjectCommand::ImageNodeMove { .. }+ | ProjectCommand::ImageNodeDuplicate { .. }+ | ProjectCommand::ImageNodeRemove { .. } => {+ super::images::apply(project, command, timestamp)}ProjectCommand::ProjectSet { .. } => {super::project::apply(project, command, timestamp, effects)diff --git a/src-tauri/src/project/commands/images.rs b/src-tauri/src/project/commands/images.rsnew file mode 100644index 0000000..6ab60c7--- /dev/null+++ b/src-tauri/src/project/commands/images.rs@@ -0,0 +1,352 @@+use super::{batch::ensure_any, patch::Patch, types::ProjectCommand};+use crate::project::{+ image::{ImageBox, ImageNode, ImageScene, ImageStyle},+ GenerationType, ProjectConfig,+};+use serde::{Deserialize, Serialize};+use std::collections::HashSet;++#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct ImageStylePatch {+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub mode: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub aesthetics: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub lighting: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub medium: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub detail: Option<String>,+}++fn new_scene(prompt: &str) -> ImageScene {+ ImageScene {+ nodes: vec![ImageNode {+ id: "image-root".into(),+ parent_id: None,+ kind: "root".into(),+ name: "Image".into(),+ description: prompt.into(),+ text: String::new(),+ r#box: None,+ colors: vec![],+ }],+ background: String::new(),+ style: ImageStyle {+ mode: "photo".into(),+ aesthetics: String::new(),+ lighting: String::new(),+ medium: String::new(),+ detail: String::new(),+ },+ steps: 20,+ seed: -1,+ reference_ids: vec![],+ output_asset_id: None,+ }+}++fn index(scene: &ImageScene, id: &str) -> Result<usize, String> {+ scene+ .nodes+ .iter()+ .position(|node| node.id == id)+ .ok_or_else(|| format!("Image node '{id}' was not found."))+}+fn non_root(scene: &ImageScene, id: &str) -> Result<usize, String> {+ let at = index(scene, id)?;+ if scene.nodes[at].kind == "root" {+ return Err("The image root cannot be moved, duplicated or removed.".into());+ }+ Ok(at)+}+fn descendants(scene: &ImageScene, id: &str) -> HashSet<String> {+ let mut ids = HashSet::from([id.to_string()]);+ loop {+ let previous = ids.len();+ for node in &scene.nodes {+ if node+ .parent_id+ .as_ref()+ .is_some_and(|parent| ids.contains(parent))+ {+ ids.insert(node.id.clone());+ }+ }+ if ids.len() == previous {+ return ids;+ }+ }+}+fn insert(+ scene: &mut ImageScene,+ nodes: Vec<ImageNode>,+ parent: &str,+ before: Option<&str>,+) -> Result<(), String> {+ index(scene, parent)?;+ let at = if let Some(before) = before {+ scene+ .nodes+ .iter()+ .position(|node| node.id == before && node.parent_id.as_deref() == Some(parent))+ .ok_or("The before node must be a child of the destination parent.")?+ } else {+ scene.nodes.len()+ };+ scene.nodes.splice(at..at, nodes);+ Ok(())+}+fn resize(scene: &mut ImageScene, id: &str, new_box: &ImageBox) -> Result<(), String> {+ let at = index(scene, id)?;+ let old = scene.nodes[at].r#box.clone();+ let ids = descendants(scene, id);+ scene.nodes[at].r#box = Some(new_box.clone());+ if let Some(old) = old {+ for node in &mut scene.nodes {+ if node.id == id || !ids.contains(&node.id) {+ continue;+ }+ if let Some(b) = node.r#box.as_mut() {+ b.x = (new_box.x + (b.x - old.x) * new_box.width / old.width)+ .round()+ .clamp(0.0, 999.0);+ b.y = (new_box.y + (b.y - old.y) * new_box.height / old.height)+ .round()+ .clamp(0.0, 999.0);+ b.width = (b.width * new_box.width / old.width)+ .round()+ .clamp(1.0, 1000.0 - b.x);+ b.height = (b.height * new_box.height / old.height)+ .round()+ .clamp(1.0, 1000.0 - b.y);+ }+ }+ }+ Ok(())+}++pub(super) fn apply(+ project: &mut ProjectConfig,+ command: &ProjectCommand,+ timestamp: &str,+) -> Result<(), String> {+ if project.generation_type != GenerationType::Image {+ return Err("Image commands require an image project.".into());+ }+ let mut scene = project+ .image_scene+ .clone()+ .unwrap_or_else(|| new_scene(&project.brief.prompt));+ match command {+ ProjectCommand::ImageSet {+ nodes,+ background,+ style,+ steps,+ seed,+ reference_ids,+ } => {+ scene = ImageScene {+ nodes: nodes.clone(),+ background: background.clone(),+ style: style.clone(),+ steps: *steps,+ seed: *seed,+ reference_ids: reference_ids.clone(),+ output_asset_id: scene.output_asset_id,+ };+ }+ ProjectCommand::ImageConfigure {+ prompt,+ background,+ style,+ steps,+ seed,+ reference_ids,+ } => {+ ensure_any(+ [+ prompt.is_some(),+ background.is_some(),+ style+ .as_ref()+ .is_some_and(|s| s != &ImageStylePatch::default()),+ steps.is_some(),+ seed.is_some(),+ reference_ids.is_some(),+ ],+ "Image settings have no fields to change.",+ )?;+ if let Some(value) = prompt {+ scene+ .nodes+ .iter_mut()+ .find(|node| node.kind == "root")+ .ok_or("Image root was not found.")?+ .description = value.clone();+ }+ if let Some(value) = background {+ scene.background = value.clone();+ }+ if let Some(value) = steps {+ scene.steps = *value;+ }+ if let Some(value) = seed {+ scene.seed = *value;+ }+ if let Some(value) = reference_ids {+ scene.reference_ids = value.clone();+ }+ if let Some(value) = style {+ if let Some(value) = &value.mode {+ scene.style.mode = value.clone();+ }+ if let Some(value) = &value.aesthetics {+ scene.style.aesthetics = value.clone();+ }+ if let Some(value) = &value.lighting {+ scene.style.lighting = value.clone();+ }+ if let Some(value) = &value.medium {+ scene.style.medium = value.clone();+ }+ if let Some(value) = &value.detail {+ scene.style.detail = value.clone();+ }+ }+ }+ ProjectCommand::ImageNodeAdd {+ id,+ parent,+ kind,+ name,+ description,+ text,+ r#box,+ colors,+ before,+ } => {+ if !matches!(kind.as_str(), "object" | "text" | "group" | "background") {+ return Err("New image nodes must be objects, text, groups or backgrounds.".into());+ }+ let node = ImageNode {+ id: id.clone(),+ parent_id: Some(parent.clone()),+ kind: kind.clone(),+ name: name.clone(),+ description: description.clone().unwrap_or_default(),+ text: text.clone().unwrap_or_default(),+ r#box: r#box.clone(),+ colors: colors.clone().unwrap_or_default(),+ };+ insert(&mut scene, vec![node], parent, before.as_deref())?;+ }+ ProjectCommand::ImageNodeSet {+ id,+ name,+ description,+ text,+ r#box,+ colors,+ } => {+ let at = index(&scene, id)?;+ ensure_any(+ [+ name.is_some(),+ description.is_some(),+ text.is_some(),+ r#box.is_changed(),+ colors.is_some(),+ ],+ "Image node update has no fields to change.",+ )?;+ match r#box {+ Patch::Set(value) => resize(&mut scene, id, value)?,+ Patch::Clear => scene.nodes[at].r#box = None,+ Patch::Unchanged => {}+ }+ if let Some(value) = name {+ scene.nodes[at].name = value.clone();+ }+ if let Some(value) = description {+ scene.nodes[at].description = value.clone();+ }+ if let Some(value) = text {+ scene.nodes[at].text = value.clone();+ }+ if let Some(value) = colors {+ scene.nodes[at].colors = value.clone();+ }+ }+ ProjectCommand::ImageNodeMove { id, parent, before } => {+ let at = non_root(&scene, id)?;+ if descendants(&scene, id).contains(parent) {+ return Err("An image node cannot move inside its own subtree.".into());+ }+ if before.as_ref() == Some(id) {+ return Err("An image node cannot be placed before itself.".into());+ }+ let mut node = scene.nodes.remove(at);+ node.parent_id = Some(parent.clone());+ insert(&mut scene, vec![node], parent, before.as_deref())?;+ }+ ProjectCommand::ImageNodeDuplicate {+ id,+ new_id,+ parent,+ before,+ } => {+ let source = scene.nodes[non_root(&scene, id)?].clone();+ let parent = parent+ .as_ref()+ .or(source.parent_id.as_ref())+ .ok_or("Missing image parent.")?;+ let ids = descendants(&scene, id);+ let renamed = |old: &str| {+ if old == id {+ new_id.clone()+ } else {+ format!("{new_id}--{old}")+ }+ };+ let copies = scene+ .nodes+ .iter()+ .filter(|node| ids.contains(&node.id))+ .map(|node| {+ let mut copy = node.clone();+ copy.id = renamed(&node.id);+ copy.parent_id = Some(if node.id == *id {+ parent.clone()+ } else {+ renamed(node.parent_id.as_deref().unwrap_or_default())+ });+ copy+ })+ .collect();+ insert(&mut scene, copies, parent, before.as_deref())?;+ }+ ProjectCommand::ImageNodeRemove { id } => {+ non_root(&scene, id)?;+ let ids = descendants(&scene, id);+ scene.nodes.retain(|node| !ids.contains(&node.id));+ }+ _ => unreachable!("command dispatched to the wrong domain"),+ }+ scene.validate()?;+ for id in &scene.reference_ids {+ if !project.references.iter().any(|reference| {+ &reference.id == id && matches!(reference.kind.as_str(), "image" | "text")+ }) {+ return Err(format!(+ "Image reference '{id}' must name an existing image or text reference."+ ));+ }+ }+ project.image_scene = Some(scene);+ project.updated_at = timestamp.into();+ Ok(())+}diff --git a/src-tauri/src/project/commands/mod.rs b/src-tauri/src/project/commands/mod.rsindex eaf6336..2c7846d 100644--- a/src-tauri/src/project/commands/mod.rs+++ b/src-tauri/src/project/commands/mod.rs@@ -3,6 +3,7 @@ mod batch;mod clips;mod effects;mod jsonl;+mod images;mod patch;mod project;mod references;diff --git a/src-tauri/src/project/commands/types.rs b/src-tauri/src/project/commands/types.rsindex becdddb..bf0181a 100644--- a/src-tauri/src/project/commands/types.rs+++ b/src-tauri/src/project/commands/types.rs@@ -12,6 +12,75 @@ pub const MAX_COMMANDS_PER_TURN: usize = 100;#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]#[serde(tag = "op", deny_unknown_fields)]pub enum ProjectCommand {+ #[serde(rename = "image.configure")]+ ImageConfigure {+ #[serde(default, skip_serializing_if = "Option::is_none")]+ prompt: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ background: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ style: Option<super::images::ImageStylePatch>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ steps: Option<u32>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ seed: Option<i64>,+ #[serde(+ default,+ rename = "referenceIds",+ skip_serializing_if = "Option::is_none"+ )]+ reference_ids: Option<Vec<String>>,+ },+ #[serde(rename = "image.node.add")]+ ImageNodeAdd {+ id: String,+ parent: String,+ kind: String,+ name: String,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ description: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ text: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ r#box: Option<crate::project::image::ImageBox>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ colors: Option<Vec<String>>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ before: Option<String>,+ },+ #[serde(rename = "image.node.set")]+ ImageNodeSet {+ id: String,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ name: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ description: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ text: Option<String>,+ #[serde(default, skip_serializing_if = "Patch::is_unchanged")]+ r#box: Patch<crate::project::image::ImageBox>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ colors: Option<Vec<String>>,+ },+ #[serde(rename = "image.node.move")]+ ImageNodeMove {+ id: String,+ parent: String,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ before: Option<String>,+ },+ #[serde(rename = "image.node.duplicate")]+ ImageNodeDuplicate {+ id: String,+ #[serde(rename = "newId")]+ new_id: String,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ parent: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ before: Option<String>,+ },+ #[serde(rename = "image.node.remove")]+ ImageNodeRemove { id: String },#[serde(rename = "image.set")]ImageSet {nodes: Vec<crate::project::image::ImageNode>,@@ -233,6 +302,12 @@ pub(super) struct CommitLine {}pub(super) fn command_name(command: &ProjectCommand) -> &'static str {match command {+ ProjectCommand::ImageConfigure { .. } => "image.configure",+ ProjectCommand::ImageNodeAdd { .. } => "image.node.add",+ ProjectCommand::ImageNodeSet { .. } => "image.node.set",+ ProjectCommand::ImageNodeMove { .. } => "image.node.move",+ ProjectCommand::ImageNodeDuplicate { .. } => "image.node.duplicate",+ ProjectCommand::ImageNodeRemove { .. } => "image.node.remove",ProjectCommand::ImageSet { .. } => "image.set",ProjectCommand::ProjectSet { .. } => "project.set",ProjectCommand::ReferenceAdd { .. } => "ref.add",diff --git a/src-tauri/src/tests/images.rs b/src-tauri/src/tests/images.rsindex 964b285..5c79b18 100644--- a/src-tauri/src/tests/images.rs+++ b/src-tauri/src/tests/images.rs@@ -87,3 +87,127 @@ fn agent_image_edits_preserve_outputs_and_reject_video_projects_or_invalid_treeslet parsed: ProjectCommand = serde_json::from_value(command).unwrap();assert!(execute_commands_at(&config, &[parsed], &config.updated_at).is_err());}++#[test]+fn granular_image_commands_edit_subtrees_without_touching_generated_outputs() {+ use crate::project::commands::{execute_commands_at, parse_jsonl_commands};+ let cases: serde_json::Value =+ serde_json::from_str(include_str!("../../../fixtures/image-commands.json")).unwrap();+ let stream = cases["commands"]+ .as_array()+ .unwrap()+ .iter()+ .map(|command| serde_json::to_string(command).unwrap())+ .collect::<Vec<_>>()+ .join("\n")+ + "\n{\"op\":\"commit\",\"summary\":\"Composed balloons\"}";+ let commands = parse_jsonl_commands(&stream).unwrap().commands;+ let mut current = image_fixture();+ current.image_scene.as_mut().unwrap().output_asset_id = Some("saved-result".into());+ let next = execute_commands_at(¤t, &commands, ¤t.updated_at).unwrap();+ let scene = next.image_scene.unwrap();+ assert_eq!(scene.output_asset_id.as_deref(), Some("saved-result"));+ assert_eq!(scene.nodes[0].description, "Balloons over the sea");+ assert_eq!(scene.style.lighting, "Soft morning light");+ assert_eq!(scene.style.mode, "art");+ let siblings: Vec<_> = scene+ .nodes+ .iter()+ .filter(|node| node.parent_id.as_deref() == Some("image-root"))+ .map(|node| node.id.as_str())+ .collect();+ assert_eq!(siblings, ["caption", "sky-copy", "group-rocket"]);+ let balloon = scene+ .nodes+ .iter()+ .find(|node| node.id == "sky-copy--balloon")+ .unwrap();+ assert_eq!(balloon.parent_id.as_deref(), Some("caption"));+ assert_eq!(balloon.description, "A red balloon");+ assert_eq!(+ balloon.r#box,+ Some(crate::project::image::ImageBox {+ x: 250.0,+ y: 250.0,+ width: 50.0,+ height: 50.0+ })+ );+ assert!(scene+ .nodes+ .iter()+ .all(|node| node.id != "sky" && node.id != "balloon"));+ assert_eq!(+ scene.nodes.iter().find(|node| node.id == "title"),+ Some(¤t.image_scene.as_ref().unwrap().nodes[2])+ );+ for command in &commands {+ assert!(+ execute_commands_at(&created_fixture(), &[command.clone()], ¤t.updated_at)+ .is_err()+ );+ }+}++#[test]+fn invalid_image_commands_roll_back_the_entire_batch() {+ use crate::project::commands::{execute_commands_at, ProjectCommand};+ let cases: serde_json::Value =+ serde_json::from_str(include_str!("../../../fixtures/image-commands.json")).unwrap();+ let current = image_fixture();+ let original = current.clone();+ let valid: ProjectCommand = serde_json::from_value(+ serde_json::json!({"op":"image.configure","background":"Must not stick"}),+ )+ .unwrap();+ for invalid in cases["invalid"].as_array().unwrap() {+ if let Ok(command) = serde_json::from_value::<ProjectCommand>(invalid.clone()) {+ assert!(+ execute_commands_at(¤t, &[valid.clone(), command], ¤t.updated_at)+ .is_err(),+ "{invalid}"+ );+ }+ assert_eq!(current, original);+ }+}++#[test]+fn image_node_patches_distinguish_missing_and_null_and_initialize_older_image_projects() {+ use crate::project::commands::{execute_commands_at, ProjectCommand};+ let current = image_fixture();+ let edit = |config: &ProjectConfig, value: serde_json::Value| {+ let command: ProjectCommand = serde_json::from_value(value).unwrap();+ execute_commands_at(config, &[command], &config.updated_at).unwrap()+ };+ let renamed = edit(+ ¤t,+ serde_json::json!({"op":"image.node.set","id":"group-rocket","name":"Vehicle"}),+ );+ assert_eq!(+ renamed.image_scene.as_ref().unwrap().nodes[1].r#box,+ current.image_scene.as_ref().unwrap().nodes[1].r#box+ );+ let cleared = edit(+ &renamed,+ serde_json::json!({"op":"image.node.set","id":"group-rocket","box":null}),+ );+ assert!(cleared.image_scene.as_ref().unwrap().nodes[1]+ .r#box+ .is_none());+ assert_eq!(+ cleared.image_scene.as_ref().unwrap().nodes[2].r#box,+ current.image_scene.as_ref().unwrap().nodes[2].r#box+ );+ let mut older = current;+ older.image_scene = None;+ let initialized = edit(+ &older,+ serde_json::json!({"op":"image.node.add","id":"subject","parent":"image-root","kind":"object","name":"Subject"}),+ );+ assert_eq!(+ initialized.image_scene.as_ref().unwrap().nodes[0].description,+ older.brief.prompt+ );+ assert_eq!(initialized.image_scene.as_ref().unwrap().nodes.len(), 2);+}diff --git a/src/lib/imageCommands.test.ts b/src/lib/imageCommands.test.tsnew file mode 100644index 0000000..9630799--- /dev/null+++ b/src/lib/imageCommands.test.ts@@ -0,0 +1,51 @@+// @vitest-environment jsdom+import { describe, expect, it } from "vitest";+import projectFixture from "../../fixtures/project-v1-image.json";+import cases from "../../fixtures/image-commands.json";+import { applyImageCommand, imageCommandSchema, type ImageCommand } from "./imageCommands";+import { createImageScene } from "./imageScene";+import { parseProjectConfig } from "./project";+import { executeAgentCommands } from "./runtime";++describe("image agent commands", () => {+ it("edits, orders, reparents and duplicates subtrees while preserving generated output and unrelated fields", async () => {+ const original = parseProjectConfig(projectFixture);+ original.imageScene!.outputAssetId = "saved-result";+ const untouched = structuredClone(original);+ const result = await executeAgentCommands(original, cases.commands.map((command) => imageCommandSchema.parse(command)));+ const scene = result.imageScene!;+ expect(scene.outputAssetId).toBe("saved-result");+ expect(scene.nodes.find((node) => node.kind === "root")!.description).toBe("Balloons over the sea");+ expect(scene.style).toEqual({ ...original.imageScene!.style, lighting: "Soft morning light" });+ expect(scene.nodes.filter((node) => node.parentId === "image-root").map((node) => node.id)).toEqual(["caption", "sky-copy", "group-rocket"]);+ expect(scene.nodes.find((node) => node.id === "sky-copy--balloon")).toMatchObject({ parentId: "caption", description: "A red balloon", box: { x: 250, y: 250, width: 50, height: 50 } });+ expect(scene.nodes.find((node) => node.id === "caption")).toMatchObject({ text: "Float", colors: ["#FF0000"], box: null });+ expect(scene.nodes.some((node) => ["sky", "balloon"].includes(node.id))).toBe(false);+ expect(scene.nodes.find((node) => node.id === "title")).toEqual(original.imageScene!.nodes[2]);+ expect(original).toEqual(untouched);+ });++ it.each(cases.invalid)("rejects invalid commands transactionally: %j", async (invalid) => {+ const original = parseProjectConfig(projectFixture);+ const before = structuredClone(original);+ await expect(executeAgentCommands(original, [{ op: "image.configure", background: "Must not stick" }, invalid as ImageCommand])).rejects.toThrow();+ expect(original).toEqual(before);+ });++ it("distinguishes unchanged boxes from cleared boxes and preserves descendants when only a parent placement is cleared", () => {+ const scene = parseProjectConfig(projectFixture).imageScene!;+ const renamed = applyImageCommand(scene, { op: "image.node.set", id: "group-rocket", name: "Vehicle" });+ expect(renamed.nodes[1].box).toEqual(scene.nodes[1].box);+ const cleared = applyImageCommand(renamed, { op: "image.node.set", id: "group-rocket", box: null });+ expect(cleared.nodes[1].box).toBeNull();+ expect(cleared.nodes[2].box).toEqual(scene.nodes[2].box);+ });++ it("initializes an older image project without imageScene and rejects image edits in video projects", async () => {+ const project = parseProjectConfig(projectFixture);+ project.imageScene = undefined;+ const updated = await executeAgentCommands(project, [{ op: "image.node.add", id: "subject", parent: "image-root", kind: "object", name: "Subject" }]);+ expect(updated.imageScene?.nodes[0]).toEqual(createImageScene(project.brief.prompt).nodes[0]);+ for (const command of cases.commands) await expect(executeAgentCommands({ ...project, generationType: "video" }, [imageCommandSchema.parse(command)])).rejects.toThrow("image project");+ });+});diff --git a/src/lib/imageCommands.ts b/src/lib/imageCommands.tsnew file mode 100644index 0000000..dc284c7--- /dev/null+++ b/src/lib/imageCommands.ts@@ -0,0 +1,87 @@+import { z } from "zod";+import { imageDescendants, imageNodeSchema, imageSceneSchema, removeImageNode, resizeImageNode, type ImageScene } from "./imageScene";++const id = z.string().min(1);+const before = id.nullish();+const editableNode = imageNodeSchema.pick({ name: true, description: true, text: true, box: true, colors: true }).partial();+const authoredScene = imageSceneSchema.innerType().omit({ outputAssetId: true });+const configuration = authoredScene.omit({ nodes: true, style: true }).partial().extend({ prompt: z.string().optional(), style: authoredScene.shape.style.partial().strict().optional() });+export const imageCommandSchema = z.discriminatedUnion("op", [+ authoredScene.extend({ op: z.literal("image.set") }).strict(),+ configuration.extend({ op: z.literal("image.configure") }).strict(),+ editableNode.extend({ op: z.literal("image.node.add"), id, parent: id, name: imageNodeSchema.shape.name, kind: z.enum(["object", "text", "group", "background"]), before }).strict(),+ editableNode.extend({ op: z.literal("image.node.set"), id }).strict(),+ z.object({ op: z.literal("image.node.move"), id, parent: id, before }).strict(),+ z.object({ op: z.literal("image.node.duplicate"), id, newId: id, parent: id.optional(), before }).strict(),+ z.object({ op: z.literal("image.node.remove"), id }).strict(),+]);+export type ImageCommand = z.infer<typeof imageCommandSchema>;++/** Apply one authored operation to a private copy. Generated output never+ * enters the command vocabulary and cannot be overwritten by an agent. */+export function applyImageCommand(current: ImageScene, command: ImageCommand): ImageScene {+ command = imageCommandSchema.parse(command);+ let scene = structuredClone(current);+ const node = (id: string) => {+ const found = scene.nodes.find((item) => item.id === id);+ if (!found) throw new Error(`Image node '${id}' was not found.`);+ return found;+ };+ const nonRoot = (id: string) => {+ const found = node(id);+ if (found.kind === "root") throw new Error("The image root cannot be moved, duplicated or removed.");+ return found;+ };+ const insert = (nodes: ImageScene["nodes"], parent: string, before?: string | null) => {+ node(parent);+ const index = before ? scene.nodes.findIndex((item) => item.id === before && item.parentId === parent) : scene.nodes.length;+ if (index < 0) throw new Error("The before node must be a child of the destination parent.");+ scene.nodes.splice(index, 0, ...nodes);+ };+ switch (command.op) {+ case "image.set": {+ const { op: _op, ...authored } = command;+ scene = { ...authored, outputAssetId: current.outputAssetId };+ break;+ }+ case "image.configure": {+ const { op: _op, prompt, style, ...settings } = command;+ if (prompt === undefined && !Object.values(settings).some((value) => value !== undefined) && !Object.values(style ?? {}).some((value) => value !== undefined)) throw new Error("Image settings have no fields to change.");+ scene = { ...scene, ...Object.fromEntries(Object.entries(settings).filter(([, value]) => value !== undefined)), style: { ...scene.style, ...style } };+ if (prompt !== undefined) scene.nodes.find((item) => item.kind === "root")!.description = prompt;+ break;+ }+ case "image.node.add":+ insert([{ id: command.id, parentId: command.parent, kind: command.kind, name: command.name, description: command.description ?? "", text: command.text ?? "", box: command.box ?? null, colors: command.colors ?? [] }], command.parent, command.before);+ break;+ case "image.node.set": {+ node(command.id);+ const { op: _op, id, box, ...patch } = command;+ const fields = Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined));+ if (!Object.keys(fields).length && box === undefined) throw new Error("Image node update has no fields to change.");+ if (box) scene = resizeImageNode(scene, id, box);+ scene.nodes = scene.nodes.map((item) => item.id === id ? { ...item, ...fields, ...(box === null ? { box: null } : {}) } : item);+ break;+ }+ case "image.node.move": {+ const source = nonRoot(command.id);+ if (imageDescendants(scene, source.id).has(command.parent)) throw new Error("An image node cannot move inside its own subtree.");+ if (command.before === source.id) throw new Error("An image node cannot be placed before itself.");+ scene.nodes = scene.nodes.filter((item) => item.id !== source.id);+ insert([{ ...source, parentId: command.parent }], command.parent, command.before);+ break;+ }+ case "image.node.duplicate": {+ const source = nonRoot(command.id);+ const ids = imageDescendants(scene, source.id);+ const renamed = (id: string) => id === source.id ? command.newId : `${command.newId}--${id}`;+ const parent = command.parent ?? source.parentId!;+ const copies = scene.nodes.filter((item) => ids.has(item.id)).map((item) => ({ ...item, id: renamed(item.id), parentId: item.id === source.id ? parent : renamed(item.parentId!) }));+ insert(copies, parent, command.before);+ break;+ }+ case "image.node.remove":+ nonRoot(command.id); scene = removeImageNode(scene, command.id); break;+ }+ return imageSceneSchema.parse(scene);+}diff --git a/src/lib/runtime.ts b/src/lib/runtime.tsindex b447b0d..014bd3d 100644--- a/src/lib/runtime.ts+++ b/src/lib/runtime.ts@@ -1,5 +1,6 @@import { invoke } from "@tauri-apps/api/core";-import { imageSceneSchema, type ImageScene } from "./imageScene";+import { createImageScene } from "./imageScene";+import { applyImageCommand, type ImageCommand } from "./imageCommands";import { isTauri } from "./persistence";import type { TemplateLora } from "./loras";import { refreshDownloadedLoras, refreshDownloadedWeights } from "./weightDownloads";@@ -41,7 +42,7 @@ export interface SlopfabStatus {export interface RuntimeStatus { providers: ProviderStatus[]; slopfab: SlopfabStatus }export type ProjectCommand =- | ({ op: "image.set" } & Omit<ImageScene, "outputAssetId">)+ | ImageCommand| { op: "project.set"; name?: string; prompt?: string; targetSeconds?: number; aspectRatio?: string; resolution?: string; frameRate?: number; backgroundColor?: string }| { op: "ref.add"; id: string; name: string; text: string; use: string[] }| { op: "ref.set"; id: string; name?: string; text?: string; use?: string[] }@@ -310,11 +311,11 @@ function executeDemoCommands(config: ProjectConfig, commands: ProjectCommand[]):};for (const command of commands) {switch (command.op) {- case "image.set": {- if (next.generationType !== "image") throw new Error("image.set requires an image project.");- const { op: _op, ...authored } = command;- for (const id of authored.referenceIds) if (!next.references.some((reference) => reference.id === id)) throw new Error(`Image reference '${id}' does not exist.`);- next.imageScene = imageSceneSchema.parse({ ...authored, outputAssetId: next.imageScene?.outputAssetId ?? null });+ case "image.set": case "image.configure": case "image.node.add": case "image.node.set": case "image.node.move": case "image.node.duplicate": case "image.node.remove": {+ if (next.generationType !== "image") throw new Error(`${command.op} requires an image project.`);+ const scene = applyImageCommand(next.imageScene ?? createImageScene(next.brief.prompt), command);+ for (const id of scene.referenceIds) if (!next.references.some((reference) => reference.id === id && ["image", "text"].includes(reference.kind))) throw new Error(`Image reference '${id}' must name an existing image or text reference.`);+ next.imageScene = scene;break;}case "project.set":