Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Restore H3 prompt structure for still images

Bitti6e6a64a5e4be
diff --git a/docs/architecture.md b/docs/architecture.md
index 1d0c3b3..1b3ddb3 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -43,7 +43,7 @@ non_diegetic_music: ...
Shots are sequential, later shots carry increasing cut timestamps, camera moves combine motion type with meaningful amplitude and speed, and dialogue uses stable speaker IDs. Keyframe jobs prepend the appropriate first/last-frame alignment instruction. Full-reference jobs additionally define stable subject/picture/video/audio labels and retention relationships. The editor stores both the human creative brief and the compiled H3 prompt so either can be revised.
-Image projects use Slopus's still-image adaptation of the [H3 visual prompt guidance](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/VIDEO_PROMPT_WRITING_GUIDE_base_en.md), rather than a published image-specific schema. `imageScenePrompt` places medium, look, aesthetics, lighting and camera/art details before one composition. It describes nested visual elements, full-image placement percentages, palettes and verbatim quoted lettering. `compileImagePrompt` appends selected visual references, numbering `<Picture N>` in the exact order of the submitted image paths. It adds no shot markers, timestamps, camera motion or audio sections, and preserves authored descriptions. Debug Prompt and generation use this same compiler. The native request sets `stillImage: true` and `frames: 1`.
+Image projects retain the [H3 base prompt structure](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/VIDEO_PROMPT_WRITING_GUIDE_base_en.md): `integrated_multimodal_description` begins with `[Shot 1]`, visual style and one still composition. With selected references, `compileImagePrompt` uses the [six-section reference format](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/VIDEO_PROMPT_WRITING_GUIDE_ref_en.md): `subject_definitions`, `summary`, `retention_analysis`, `detailed_description`, `overall_soundscape`, `non_diegetic_music`. Reference-mode style precedes `[Shot 1]`. Stable `<Subject N>` labels identify referenced content; `<Picture N>` sources follow the exact submitted image-path order. Refmods provide conditioning without consuming picture labels. Both audio fields are `N/A` for the silent still-image workflow. The compiler preserves nested visual elements, full-image placement percentages, palettes and verbatim quoted lettering; it adds no timestamps, subsequent shots or camera motion. Debug Prompt and generation use this same compiler. This applies the published video formats to native still-image requests, which set `stillImage: true` and `frames: 1`.
## Generation boundary
diff --git a/src-tauri/assets/agent-image.md b/src-tauri/assets/agent-image.md
index 43e4fa1..db99f97 100644
--- a/src-tauri/assets/agent-image.md
+++ b/src-tauri/assets/agent-image.md
@@ -1,6 +1,6 @@
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.
-Describe a single visible composition: subjects, pose, spatial relationships, background, lighting, materials and appearance. Write camera/lens details as framing, perspective, focal length and depth of field. For action subjects, describe the moment depicted in the image. Do not add shot markers, timestamps, camera movements, dialogue delivery or audio sections. Put visible lettering verbatim in text nodes, including its language and line breaks. Slopus compiles the hierarchy and style into visual prose and adds the selected picture references; do not paste a video prompt template into descriptions.
+Describe a single visible composition: subjects, pose, spatial relationships, background, lighting, materials and appearance. Write camera/lens details as framing, perspective, focal length and depth of field. For action subjects, describe the moment depicted in the image. Do not add shot markers, timestamps, camera movements, dialogue delivery or audio sections to authored descriptions. Put visible lettering verbatim in text nodes, including its language and line breaks. Slopus compiles the hierarchy and style into H3's base three-field or reference six-section format, with one [Shot 1], stable reference labels and N/A audio fields; do not paste a compiled prompt template into descriptions.
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.
diff --git a/src/components/ImageProject.integration.test.tsx b/src/components/ImageProject.integration.test.tsx
index 5c2a670..9b9ac15 100644
--- a/src/components/ImageProject.integration.test.tsx
+++ b/src/components/ImageProject.integration.test.tsx
@@ -37,10 +37,12 @@ it("shows the full image prompt at the end of the inspector only when debug is e
button.focus();
fireEvent.click(button);
const prompt = within(screen.getByRole("dialog", { name: "Debug Prompt" })).getByLabelText("The compiled MiniMax H3 prompt");
- for (const line of imageScenePrompt(project.config.imageScene!).split("\n")) expect(prompt.textContent).toContain(line);
+ for (const line of imageScenePrompt(project.config.imageScene!, "Watercolor").split("\n")) expect(prompt.textContent).toContain(line);
expect(prompt.textContent).toContain('Render the exact text "TO THE MOON".');
- expect(prompt.textContent).toContain("Visual style: Watercolor.");
- expect(prompt.textContent).toContain("Use <Picture 1>, <Picture 2> as visual guidance for Rocket. A silver rocket.\nAdditional visual guidance: Peaceful and bright.");
+ expect(prompt.textContent).toContain("Watercolor visual style");
+ expect(prompt.textContent).toContain("subject_definitions:\n<Subject 1> is Rocket, providing appearance from <Picture 1> and <Picture 2>. A silver rocket.\n<Subject 2> is Mood, providing appearance. Peaceful and bright.");
+ expect(prompt.textContent).toContain("[Shot 1] A rocket launch over the ocean at dawn.");
+ expect(prompt.textContent).toMatch(/overall_soundscape: N\/A\n\nnon_diegetic_music: N\/A$/);
expect(prompt.textContent).not.toContain("Do not include this reference");
fireEvent.keyDown(window, { key: "Escape" });
expect(screen.queryByRole("dialog", { name: "Debug Prompt" })).not.toBeInTheDocument();
diff --git a/src/components/workspace/ImageEditor.test.tsx b/src/components/workspace/ImageEditor.test.tsx
index 785ad7b..1ce7980 100644
--- a/src/components/workspace/ImageEditor.test.tsx
+++ b/src/components/workspace/ImageEditor.test.tsx
@@ -46,7 +46,7 @@ it("edits ordered style chips with suggestions, custom tags, removal, undo, and
fireEvent.keyDown(window, { key: "Escape" });
fireEvent.click(screen.getByRole("button", { name: "Add Camera / lens tag" }));
fireEvent.click(screen.getByRole("button", { name: "35mm" }));
- expect(imageScenePrompt(current().imageScene!)).toContain("Medium: Photograph.\nAesthetics: Minimal poster, intricate, custom finish.\nLighting: Sunrise, golden hour.\nCamera and lens: Screen print, 35mm.");
+ expect(imageScenePrompt(current().imageScene!)).toContain("A still photograph with Minimal poster, intricate, custom finish aesthetics, Sunrise, golden hour lighting, Screen print, 35mm camera and lens characteristics.");
fireEvent.keyDown(window, { key: "Escape" });
fireEvent.click(screen.getByRole("button", { name: "Add Aesthetics tag" }));
expect(screen.getByRole("button", { name: "photorealistic" })).toBeInTheDocument();
diff --git a/src/lib/imagePrompt.test.ts b/src/lib/imagePrompt.test.ts
index 0d6551a..e5d7feb 100644
--- a/src/lib/imagePrompt.test.ts
+++ b/src/lib/imagePrompt.test.ts
@@ -6,21 +6,18 @@ import fixture from "../../fixtures/project-v1-image.json";
const photo = () => createProjectConfig({ name: "Portrait", generationType: "image", prompt: "A runner suspended mid-stride", aspectRatio: "1:1", resolution: "768p", targetDurationSeconds: 60 });
describe("MiniMax H3 still-image prompts", () => {
- it("places photo style before a single visual composition without video scaffolding", () => {
+ it("uses H3's three core fields with style inside the first shot and silent audio", () => {
const config = photo();
config.settings.defaultLook = "watercolor";
config.imageScene!.style = { mode: "photo", aesthetics: "editorial, high contrast", lighting: "golden hour", medium: "Ignored art medium", detail: "85mm, f/1.4" };
const snapshot = structuredClone(config);
expect(compileImagePrompt(config).prompt).toBe([
- "Create one still image with a single composition.",
- "Medium: Photograph.",
- "Visual style: Watercolor.",
- "Aesthetics: editorial, high contrast.",
- "Lighting: golden hour.",
- "Camera and lens: 85mm, f/1.4.",
- "", "A runner suspended mid-stride.",
+ "integrated_multimodal_description: [Shot 1] A still photograph with Watercolor visual style, editorial, high contrast aesthetics, golden hour lighting, 85mm, f/1.4 camera and lens characteristics.",
+ "A runner suspended mid-stride.",
+ "", "overall_soundscape: N/A",
+ "", "non_diegetic_music: N/A",
].join("\n"));
- expect(compileImagePrompt(config).prompt).not.toMatch(/\[Shot|overall_soundscape|non_diegetic_music|integrated_multimodal_description|00:|root:|Ignored art medium/);
+ expect(compileImagePrompt(config).prompt).not.toMatch(/\[Shot 2|00:|root:|Ignored art medium|Medium:|Aesthetics:|Camera and lens:/);
expect(config).toEqual(snapshot);
});
@@ -28,8 +25,8 @@ describe("MiniMax H3 still-image prompts", () => {
const config = parseProjectConfig(fixture);
config.imageScene!.nodes[1].description = "";
const prompt = compileImagePrompt(config).prompt;
- expect(prompt).toContain("Medium: Illustration.");
- expect(prompt).toContain("Art style: Screen print.");
+ expect(prompt).toContain("integrated_multimodal_description: [Shot 1] A still image in Illustration");
+ expect(prompt).toContain("Screen print art style.");
expect(prompt).toContain("Overall color palette: #204060.");
expect(prompt).toContain("Background: Ocean at dawn.");
expect(prompt).toContain("A grouped arrangement. Position in the full image: left 30%, top 10%, width 40%, height 80%. Its composition includes:\n Visible lettering. Bold red lettering.");
@@ -47,7 +44,7 @@ describe("MiniMax H3 still-image prompts", () => {
expect(imageScenePrompt(scene)).not.toContain("\\n");
});
- it("numbers pictures in selected payload order and treats text references as visual guidance", () => {
+ it("uses all six reference sections with stable subjects and pictures in payload order", () => {
const config = photo();
config.references = [
{ id: "runner", kind: "image", name: "Runner", description: "Red jersey", relativePath: "references/runner.png", images: [{ id: "detail", name: "Detail", relativePath: "references/detail.png", sourcePath: null }], intendedUse: [], createdAt: config.createdAt },
@@ -58,12 +55,18 @@ describe("MiniMax H3 still-image prompts", () => {
config.imageScene!.referenceIds = ["track", "palette", "runner"];
const result = compileImagePrompt(config);
expect(result.references.map((reference) => reference.id)).toEqual(["track", "palette", "runner"]);
- expect(result.prompt).toContain([
- "Visual references for this still image:",
- "Use <Picture 1> as visual guidance for Track. A gravel track.",
- "Additional visual guidance: Warm ochre and red.",
- "Use <Picture 2>, <Picture 3> as visual guidance for Runner. Red jersey.",
- ].join("\n"));
+ expect(result.prompt.match(/^\w+:/gm)).toEqual(["subject_definitions:", "summary:", "retention_analysis:", "detailed_description:", "overall_soundscape:", "non_diegetic_music:"]);
+ expect(result.prompt).toContain("<Subject 1> is Track, providing appearance from <Picture 1>. A gravel track.");
+ expect(result.prompt).toContain("<Subject 2> is Palette, providing appearance. Warm ochre and red.");
+ expect(result.prompt).toContain("<Subject 3> is Runner, providing appearance from <Picture 2> and <Picture 3>. Red jersey.");
+ expect(result.prompt).toContain("summary:\n[reference generation] A single still image uses <Subject 1>, <Subject 2>, <Subject 3>");
+ expect(result.prompt).toContain("detailed_description:\nA still photograph.\n[Shot 1] A runner suspended mid-stride.");
+ for (let index = 1; index <= 3; index++) {
+ expect(result.prompt).toContain(`<Subject ${index}> (appears in [Shot 1]): fully_preserved`);
+ expect(result.prompt.split("detailed_description:")[1]).toContain(`Use <Subject ${index}>`);
+ }
+ expect(result.prompt).toMatch(/overall_soundscape: N\/A\n\nnon_diegetic_music: N\/A$/);
+ expect(result.prompt).not.toContain("integrated_multimodal_description");
expect(result.prompt).not.toMatch(/Exclude these words|<Video|<Audio|first frame|last frame/);
config.imageScene!.referenceIds = ["missing"];
expect(() => compileImagePrompt(config)).toThrow("no longer exists");
@@ -82,9 +85,24 @@ describe("MiniMax H3 still-image prompts", () => {
refmods: [{ id: "encoded", name: "Identity", sourcePath: "D:/identity.safetensors", strength: 1, copies: 1 }] }];
config.imageScene!.referenceIds = ["identity"];
const prompt = compileImagePrompt(config).prompt;
- expect(prompt).toContain("Use the supplied reference conditioning for Woman's identity and appearance in this still image");
+ expect(prompt).toContain("<Subject 1> is Woman, providing identity and appearance from the supplied reference conditioning.");
+ expect(prompt).toContain("Use <Subject 1> for Woman's identity and appearance from the supplied reference conditioning.");
expect(prompt).not.toMatch(/Additional visual guidance: Woman|<Picture|<Video|safetensors/);
config.references[0].refmods![0].strength = 0;
expect(compileImagePrompt(config).prompt).not.toContain("Woman");
+ expect(compileImagePrompt(config).prompt).toMatch(/^integrated_multimodal_description: \[Shot 1\]/);
+ });
+ it("keeps picture numbering independent of refmod and text subjects", () => {
+ const config = photo();
+ config.references = [
+ { id: "disabled", kind: "text", name: "Disabled", description: "", intendedUse: [], createdAt: config.createdAt, refmods: [{ id: "off", name: "Off", sourcePath: "D:/off.safetensors", strength: 0, copies: 1 }] },
+ { id: "style", kind: "text", name: "Style", description: "", intendedUse: ["style"], createdAt: config.createdAt, refmods: [{ id: "style-mod", name: "Style", sourcePath: "D:/style.safetensors", strength: 1, copies: 1 }] },
+ { id: "runner", kind: "image", name: "Runner", description: "Red jersey", relativePath: "references/runner.png", intendedUse: ["character"], createdAt: config.createdAt },
+ ];
+ config.imageScene!.referenceIds = config.references.map((reference) => reference.id);
+ const prompt = compileImagePrompt(config).prompt;
+ expect(prompt).toContain("<Subject 1> is Style, providing visual style from the supplied reference conditioning.");
+ expect(prompt).toContain("<Subject 2> is Runner, providing identity and appearance from <Picture 1>.");
+ expect(prompt).not.toMatch(/Disabled|<Subject 3>|<Picture 2>|<Video/);
});
});
diff --git a/src/lib/imagePrompt.ts b/src/lib/imagePrompt.ts
index 98d23d0..e058f95 100644
--- a/src/lib/imagePrompt.ts
+++ b/src/lib/imagePrompt.ts
@@ -1,8 +1,9 @@
-import { createImageScene, imageScenePrompt } from "./imageScene";
+import { createImageScene, imageScenePromptParts } from "./imageScene";
import { activeReferenceRefmods, referenceDefinition, referenceImages, type ProjectConfig } from "./project";
import { SHOT_TAG_GROUPS } from "./shot-tags";
-/** Shared by the generation request and its debug preview. */
+/** Shared by generation and Debug Prompt. H3's base three-field / reference
+ * six-section contracts still apply to a single silent image. */
export function compileImagePrompt(config: ProjectConfig) {
const scene = config.imageScene ?? createImageScene(config.brief.prompt);
const references = scene.referenceIds.map((id) => {
@@ -12,29 +13,31 @@ export function compileImagePrompt(config: ProjectConfig) {
return reference;
});
let picture = 0;
- const referencePrompts = references.map((reference) => {
+ const subjects = references.flatMap((reference) => {
const labels = referenceImages(reference).map(() => `<Picture ${++picture}>`);
const definition = referenceDefinition(reference);
const refmods = activeReferenceRefmods(reference);
- if (reference.refmods?.length && !refmods.length && !labels.length && !definition) return "";
+ if (reference.refmods?.length && !refmods.length && !labels.length && !definition) return [];
const content = definition || reference.name;
const description = /[.!?。!?]$/.test(content) ? content : `${content}.`;
- if (refmods.length) {
- const role = reference.intendedUse.includes("character") || reference.intendedUse.includes("animal") ? "identity and appearance" : reference.intendedUse.includes("style") ? "visual style" : "appearance";
- return [
- `Use the supplied reference conditioning for ${reference.name}'s ${role} in this still image, while following the requested composition and styling.`,
- ...(definition ? [description] : []),
- ...(labels.length ? [`Use ${labels.join(", ")} as additional visual guidance for ${reference.name}.`] : []),
- ].join(" ");
- }
- return labels.length
- ? `Use ${labels.join(", ")} as visual guidance for ${reference.name}. ${description}`
- : `Additional visual guidance: ${description}`;
- }).filter(Boolean);
+ const role = reference.intendedUse.includes("character") || reference.intendedUse.includes("animal") ? "identity and appearance" : reference.intendedUse.includes("style") ? "visual style" : "appearance";
+ const sources = [...labels, ...(refmods.length ? ["the supplied reference conditioning"] : [])];
+ return [{ name: reference.name, role, description, source: sources.length ? ` from ${sources.join(" and ")}` : "" }];
+ });
if (picture > 9) throw new Error("MiniMax H3 supports at most nine reference images per generation.");
const look = SHOT_TAG_GROUPS.find((group) => group.id === "visualStyle")?.options.find((option) => option.id === config.settings.defaultLook)?.label;
- return {
- prompt: [imageScenePrompt(scene, look), ...(referencePrompts.length ? [`Visual references for this still image:\n${referencePrompts.join("\n")}`] : [])].filter(Boolean).join("\n\n"),
- references,
+ const visual = imageScenePromptParts(scene, look);
+ if (!visual) return { prompt: "", references };
+ const audio = ["overall_soundscape: N/A", "non_diegetic_music: N/A"];
+ if (!subjects.length) return {
+ prompt: [`integrated_multimodal_description: [Shot 1] ${visual.style}\n${visual.composition}`, ...audio].join("\n\n"), references,
};
+ const label = (index: number) => `<Subject ${index + 1}>`;
+ return { prompt: [
+ `subject_definitions:\n${subjects.map((subject, index) => `${label(index)} is ${subject.name}, providing ${subject.role}${subject.source}. ${subject.description}`).join("\n")}`,
+ `summary:\n[reference generation] A single still image uses ${subjects.map((_, index) => label(index)).join(", ")} in the requested composition.`,
+ `retention_analysis:\n${subjects.map((subject, index) => `${label(index)} (appears in [Shot 1]): fully_preserved - retain the referenced ${subject.role} of ${subject.name} while following the requested composition and styling.`).join("\n")}`,
+ `detailed_description:\n${visual.style}\n[Shot 1] ${visual.composition}\n${subjects.map((subject, index) => `Use ${label(index)} for ${subject.name}'s ${subject.role}${subject.source}. ${subject.description}`).join("\n")}`,
+ ...audio,
+ ].join("\n\n"), references };
}
diff --git a/src/lib/imageScene.ts b/src/lib/imageScene.ts
index 35c596d..1263168 100644
--- a/src/lib/imageScene.ts
+++ b/src/lib/imageScene.ts
@@ -75,19 +75,20 @@ export function resizeImageNode(scene: ImageScene, id: string, box: ImageBox): I
}
const sentence = (text: string) => /[.!?。!?]$/.test(text.trim()) ? text.trim() : `${text.trim()}.`;
-/** Slopus's still-image adaptation of H3's visual prose guidance. No generated
- * shot markers, timing or audio sections; boxes refer to the full image. */
-export function imageScenePrompt(scene: ImageScene, look?: string): string {
+/** Visual content only. The compiler places style before or after [Shot 1]
+ * according to H3's reference or base format. Boxes refer to the full image. */
+export function imageScenePromptParts(scene: ImageScene, look?: string): { style: string; composition: string } | null {
const root = scene.nodes.find((node) => node.kind === "root")!;
const hasContent = scene.background.trim() || scene.nodes.some((node) => node.description.trim() || node.colors.length || (node.kind === "text" && node.text) || (node.kind !== "root" && node.box));
- if (!hasContent) return "";
- const style = [
- `Medium: ${sentence(scene.style.mode === "photo" ? "Photograph" : scene.style.medium || "Artwork")}`,
- ...(look?.trim() ? [`Visual style: ${sentence(look)}`] : []),
- ...(scene.style.aesthetics.trim() ? [`Aesthetics: ${sentence(scene.style.aesthetics)}`] : []),
- ...(scene.style.lighting.trim() ? [`Lighting: ${sentence(scene.style.lighting)}`] : []),
- ...(scene.style.detail.trim() ? [`${scene.style.mode === "photo" ? "Camera and lens" : "Art style"}: ${sentence(scene.style.detail)}`] : []),
+ if (!hasContent) return null;
+ const treatment = [
+ ...(look?.trim() ? [`${look.trim()} visual style`] : []),
+ ...(scene.style.aesthetics.trim() ? [`${scene.style.aesthetics.trim()} aesthetics`] : []),
+ ...(scene.style.lighting.trim() ? [`${scene.style.lighting.trim()} lighting`] : []),
+ ...(scene.style.detail.trim() ? [`${scene.style.detail.trim()} ${scene.style.mode === "photo" ? "camera and lens characteristics" : "art style"}`] : []),
];
+ const medium = scene.style.mode === "photo" ? "A still photograph" : `A still image in ${scene.style.medium.trim() || "an artistic medium"}`;
+ const style = sentence(`${medium}${treatment.length ? ` with ${treatment.join(", ")}` : ""}`);
const placement = (node: ImageNode) => node.box ? `Position in the full image: left ${node.box.x / 10}%, top ${node.box.y / 10}%, width ${node.box.width / 10}%, height ${node.box.height / 10}%.` : "";
const lines: string[] = [
...(root.description.trim() ? [sentence(root.description)] : []),
@@ -107,5 +108,10 @@ export function imageScenePrompt(scene: ImageScene, look?: string): string {
children.forEach((child) => visit(child, depth + 1));
};
scene.nodes.filter((node) => node.parentId === root.id).forEach((node) => visit(node, 0));
- return `Create one still image with a single composition.\n${style.join("\n")}\n\n${lines.join("\n")}`;
+ return { style, composition: lines.join("\n") };
+}
+
+export function imageScenePrompt(scene: ImageScene, look?: string): string {
+ const parts = imageScenePromptParts(scene, look);
+ return parts ? `${parts.style}\n${parts.composition}` : "";
}
diff --git a/src/lib/workQueue.test.ts b/src/lib/workQueue.test.ts
index b82e255..795c834 100644
--- a/src/lib/workQueue.test.ts
+++ b/src/lib/workQueue.test.ts
@@ -86,8 +86,9 @@ describe("image generation work", () => {
await waitFor(() => expect(enqueueSlopfabGeneration).toHaveBeenCalledOnce());
const request = vi.mocked(enqueueSlopfabGeneration).mock.calls[0][0];
expect(request.prompt).toBe(preview);
- expect(request.prompt).toContain("Visual style: Watercolor.");
- expect(request.prompt).toContain("Use <Picture 1> as visual guidance for Ocean. Turquoise water.");
+ expect(request.prompt).toContain("Watercolor visual style");
+ expect(request.prompt).toContain("<Subject 1> is Ocean, providing appearance from <Picture 1>. Turquoise water.");
+ expect(request.prompt).toMatch(/overall_soundscape: N\/A\n\nnon_diegetic_music: N\/A$/);
expect(request.referencePaths).toEqual(["C:/Image/references/ocean.png"]);
await queue.cancel(request.jobId);
});