Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Enable H3 Image character sheets

Bitti7dcb896cc811
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index a49e46d..b7501fe 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -10,6 +10,7 @@ Changes since 0.4.0.
## Fixes and improvements
+- MiniMax H3 Image now supports character sheets, using its image prompts, reference limits and six-step generation recipe.
- Updated the bundled Slopfab runtime to 0.2.0, including a higher MiniMax H3 Image canvas limit of 20 MP.
- MiniMax H3 Image resolution presets scale width and height by 1.675, rounded down to the 32-pixel grid. The largest preset is 6080 × 3424, within the 20 MP limit. Switching image models keeps the same preset position.
- Fixed Extend rejecting editing drafts that already have a saved source image.
diff --git a/src/components/ImageProject.integration.test.tsx b/src/components/ImageProject.integration.test.tsx
index 99efaa9..98786c6 100644
--- a/src/components/ImageProject.integration.test.tsx
+++ b/src/components/ImageProject.integration.test.tsx
@@ -25,11 +25,13 @@ vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn(async () => () => undefi
afterEach(() => { cleanup(); resetExportJobForTests(); localStorage.clear(); installH3TestDependencies(); vi.restoreAllMocks(); });
const record = (): ProjectRecord => ({ folderPath: "D:/Images", config: parseProjectConfig(fixture) });
-it("opens template settings and executes only after configuring prompts and clothing references", () => {
+it.each(["minimax-h3", "h3_image"])("opens %s template settings and executes only after configuring prompts and clothing references", (modelType) => {
+ installH3TestDependencies();
vi.spyOn(persistence, "isTauri").mockReturnValue(true);
vi.spyOn(persistence, "readMediaFileUrl").mockResolvedValue(null);
- const template = { id: "test", name: "Test", modelType: "minimax-h3" as const, defaultSteps: 20, attention: "sage2" as const, paths: { ...EMPTY_ENGINE_SETTINGS, transformer: "D:/h3.safetensors" } };
+ const template = { id: "test", name: "Test", modelType, defaultSteps: modelType === "h3_image" ? 6 : 20, attention: "sage2" as const, paths: { ...EMPTY_ENGINE_SETTINGS, transformer: "D:/h3.safetensors" } };
saveGeneratorTemplateSettings({ defaultTemplateId: "test", templates: [template] });
+ saveDebugOptionsEnabled(true);
const project = record();
project.config.assets = ["First", "Selected"].map((id) => ({ id, name: id, kind: "image", relativePath: `media/${id}.png`, mimeType: "image/png", createdAt: project.config.createdAt }));
project.config.references = [{ id: "outfit", name: "Red coat", kind: "image", description: "A red wool coat", relativePath: "references/coat.png", intendedUse: [], createdAt: project.config.createdAt }];
@@ -57,9 +59,16 @@ it("opens template settings and executes only after configuring prompts and clot
expect(panel.getByRole("button", { name: "Execute" })).toBeDisabled();
fireEvent.click(panel.getByRole("switch", { name: "Back view" }));
expect(panel.getByText(/Sheet size:/)).toHaveTextContent("1152 × 2048 px");
- fireEvent.change(panel.getByRole("spinbutton", { name: "Steps" }), { target: { value: "" } });
- expect(panel.getByRole("button", { name: "Execute" })).toBeDisabled();
- fireEvent.change(panel.getByRole("spinbutton", { name: "Steps" }), { target: { value: "37" } });
+ if (modelType === "h3_image") {
+ expect(panel.getByRole("spinbutton", { name: "Steps" })).toBeDisabled();
+ expect(panel.getByRole("spinbutton", { name: "Steps" })).toHaveValue(6);
+ } else {
+ fireEvent.change(panel.getByRole("spinbutton", { name: "Steps" }), { target: { value: "" } });
+ expect(panel.getByRole("spinbutton", { name: "Steps" })).toBeInvalid();
+ fireEvent.click(panel.getByRole("button", { name: "Execute" }));
+ expect(generate).not.toHaveBeenCalled();
+ fireEvent.change(panel.getByRole("spinbutton", { name: "Steps" }), { target: { value: "37" } });
+ }
fireEvent.change(panel.getByRole("spinbutton", { name: "Seed" }), { target: { value: "0" } });
expect(panel.queryByRole("textbox", { name: "Clothing and accessories" })).not.toBeInTheDocument();
const prompt = panel.getByRole("textbox", { name: "Character sheet prompt" });
@@ -69,8 +78,17 @@ it("opens template settings and executes only after configuring prompts and clot
fireEvent.click(screen.getByRole("button", { name: /Red coat/ }));
expect(prompt.querySelector(".prompt-chip")).toHaveTextContent("Red coat");
expect(queue.project(project).getSnapshot().config).toEqual(before);
+ fireEvent.click(panel.getByRole("button", { name: "Debug prompt" }));
+ const debug = within(screen.getByRole("dialog", { name: "Debug prompt" }));
+ expect(debug.getByLabelText("The compiled MiniMax H3 prompt")).toHaveTextContent("Full body back view");
+ if (modelType === "h3_image") {
+ expect(debug.getByLabelText("The compiled MiniMax H3 prompt")).toHaveTextContent("Red coat (<Picture 2>)");
+ expect(debug.getByLabelText("The compiled MiniMax H3 prompt")).not.toHaveTextContent("[Shot 1]");
+ }
+ fireEvent.click(debug.getByRole("button", { name: "Close" }));
+ expect(panel.getByRole("button", { name: "Execute" })).toBeEnabled();
fireEvent.click(panel.getByRole("button", { name: "Execute" }));
- expect(generate).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ id: "test" }), "Selected", { prompt: "Soft studio lighting. Wear @[ref:outfit]", height: 2048, steps: 37, seed: 0,
+ expect(generate).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ id: "test" }), "Selected", { prompt: "Soft studio lighting. Wear @[ref:outfit]", height: 2048, steps: modelType === "h3_image" ? 6 : 37, seed: 0,
views: { closeUp: false, front: false, side: false, back: true } });
fireEvent.click(panel.getByRole("button", { name: "Close template settings" }));
expect(screen.getByRole("complementary", { name: "Image node inspector" })).toBeInTheDocument();
diff --git a/src/components/workspace/CharacterSheetSettings.tsx b/src/components/workspace/CharacterSheetSettings.tsx
index 38e0586..e5b80a9 100644
--- a/src/components/workspace/CharacterSheetSettings.tsx
+++ b/src/components/workspace/CharacterSheetSettings.tsx
@@ -7,10 +7,12 @@ import { ComboBox, InfoBar, ItemHeader, PropRow, ToggleSwitch } from "../ui";
import { Dismiss16, Sparkle16 } from "../ui/icons";
import { PromptTextField, type PromptReference } from "./PromptTextField";
import { TemplateDebugPrompt } from "./TemplateDebugPrompt";
+import { generationStepsForTemplate } from "../../lib/settings";
-export function CharacterSheetSettings({ config, source, references, missingLabel, defaultSteps, disabledReason, busy, initialOptions, onExecute, onClose }: {
+export function CharacterSheetSettings({ config, source, references, missingLabel, defaultSteps, modelType, disabledReason, busy, initialOptions, onExecute, onClose }: {
config: ProjectConfig; source: ProjectAsset; references: PromptReference[]; missingLabel: (id: string) => string;
defaultSteps: number; disabledReason: string | null; busy: boolean;
+ modelType?: string;
initialOptions?: CharacterSheetOptions;
onExecute: (options: CharacterSheetOptions) => void; onClose: () => void;
}) {
@@ -22,10 +24,11 @@ export function CharacterSheetSettings({ config, source, references, missingLabe
const selectedViews = characterSheetViews(options);
const indices = characterSheetViewIndices(options);
const [error, setError] = useState<string | null>(null);
+ const steps = generationStepsForTemplate(options.steps ?? defaultSteps, { modelType: modelType ?? "minimax-h3" });
const compiled = useMemo(() => {
- try { return { views: compileCharacterSheet(config, source, "cache/character-sheet-preview/1.png", options), error: null }; }
+ try { return { views: compileCharacterSheet(config, source, "cache/character-sheet-preview/1.png", { ...options, steps }, modelType), error: null }; }
catch (reason) { return { views: null, error: reason instanceof Error ? reason.message : String(reason) }; }
- }, [config, source, options]);
+ }, [config, source, options, steps, modelType]);
const validation = compiled.error;
const update = <K extends keyof CharacterSheetOptions,>(field: K, value: CharacterSheetOptions[K]) => {
setOptions((current) => ({ ...current, [field]: value })); setError(null);
@@ -35,7 +38,7 @@ export function CharacterSheetSettings({ config, source, references, missingLabe
<form className="image-template-settings__form" onSubmit={(event) => {
event.preventDefault();
if (disabledReason || validation || busy) return;
- try { setError(null); onExecute(options); }
+ try { setError(null); onExecute({ ...options, steps }); }
catch (reason) { setError(reason instanceof Error ? reason.message : String(reason)); }
}}>
<div className="image-inspector__fields image-template-settings__fields">
@@ -48,8 +51,8 @@ export function CharacterSheetSettings({ config, source, references, missingLabe
<PropRow label="Resolution" htmlFor="character-sheet-resolution" tooltip="Width follows the selected view proportions."><ComboBox id="character-sheet-resolution" aria-label="Character sheet resolution" value={options.height} disabled={busy}
options={CHARACTER_SHEET_HEIGHTS.map((height) => ({ value: height, label: `${height} px high` }))} onChange={(height) => update("height", height)} /></PropRow>
<p className="image-inspector__caption">Sheet size: {indices.reduce((width, index) => width + dimensions[index].width, 0)} × {dimensions[0].height} px.</p>
- <PropRow label="Steps" htmlFor="character-sheet-steps" tooltip="All selected views use the same step count."><SliderNumberInput id="character-sheet-steps" aria-label="Steps" {...GENERATION_STEPS_RANGE} required disabled={busy}
- value={options.steps ?? defaultSteps} onCommit={(steps) => update("steps", steps)} /></PropRow>
+ <PropRow label="Steps" htmlFor="character-sheet-steps" tooltip="All selected views use the same step count."><SliderNumberInput id="character-sheet-steps" aria-label="Steps" {...GENERATION_STEPS_RANGE} required disabled={busy || modelType === "h3_image"}
+ value={steps} onCommit={(steps) => update("steps", steps)} /></PropRow>
<PropRow label="Seed" htmlFor="character-sheet-seed" tooltip="Use -1 for a random seed. All selected views use the same seed."><input id="character-sheet-seed" className="text-field" type="number" min="-1" max={Number.MAX_SAFE_INTEGER} step="1" required disabled={busy}
value={Number.isNaN(options.seed) ? "" : options.seed} onChange={(event) => update("seed", event.target.valueAsNumber)} /></PropRow>
<div className="image-inspector__area"><span tabIndex={0} data-tooltip="Use the prompt and references for clothing and other details. Leave it blank to keep the source appearance.">Prompt</span>
diff --git a/src/components/workspace/ImageEditor.tsx b/src/components/workspace/ImageEditor.tsx
index 424ffd4..3b7bf3e 100644
--- a/src/components/workspace/ImageEditor.tsx
+++ b/src/components/workspace/ImageEditor.tsx
@@ -808,7 +808,7 @@ export function ImageEditor({ config, folderPath, onChange: changeConfig, onGene
disabledReason={outpaintingBlocked ?? (!isTauri() ? "Template execution is available in the desktop app." : !onGenerateExtend || !template || !templateUsable(template) ? "Choose a downloaded generator to execute this template." : null)}
onExecute={() => attempt(() => onGenerateExtend?.(template!, output.id, extendOptions))} onClose={() => setExtendSourceId(null)}
/> : output && templateSourceId === output.id ? <CharacterSheetSettings
- config={config} source={output} references={promptReferences} missingLabel={missingReference} defaultSteps={template?.defaultSteps ?? 20} busy={Boolean(active)}
+ config={config} source={output} references={promptReferences} missingLabel={missingReference} defaultSteps={template?.defaultSteps ?? 20} modelType={template?.modelType} busy={Boolean(active)}
disabledReason={referencesBlocked ?? (!isTauri() ? "Template execution is available in the desktop app." : !onGenerateCharacterSheet || !template || !templateUsable(template) ? "Choose a downloaded generator to execute this template." : null)}
onExecute={(options) => onGenerateCharacterSheet?.(template!, output.id, options)} onClose={() => setTemplateSourceId(null)}
/> : runningTemplate && templateSource ? runningTemplate.kind === "extend" ? <ExtendSettings
@@ -816,7 +816,7 @@ export function ImageEditor({ config, folderPath, onChange: changeConfig, onGene
references={promptReferences} missingLabel={missingReference} busy disabledReason={null}
onExecute={() => {}} onClose={() => selectImage(templateSource.id)}
/> : <CharacterSheetSettings key={output!.id}
- config={config} source={templateSource} initialOptions={runningTemplate} defaultSteps={runningTemplate.steps}
+ config={config} source={templateSource} initialOptions={runningTemplate} defaultSteps={runningTemplate.steps} modelType={usedGenerator?.modelType}
references={promptReferences} missingLabel={missingReference} busy disabledReason={null}
onExecute={() => {}} onClose={() => selectImage(templateSource.id)}
/> : <aside className="image-inspector" aria-label="Image node inspector">
diff --git a/src/lib/characterSheet.test.ts b/src/lib/characterSheet.test.ts
index 9929ac9..c7c530c 100644
--- a/src/lib/characterSheet.test.ts
+++ b/src/lib/characterSheet.test.ts
@@ -46,11 +46,12 @@ async function requestAt(index: number) {
return vi.mocked(enqueueSlopfabGeneration).mock.calls[index][0];
}
-it.each([false, true])("uses a shared front-view outfit with square portrait and tall body views (source changed: %s)", async (changed) => {
+it.each(["minimax-h3", "h3_image"].flatMap((modelType) => [false, true].map((changed) => ({ modelType, changed }))))("uses a shared front-view outfit with square portrait and tall body views ($modelType, source changed: $changed)", async ({ modelType, changed }) => {
const { queue, session } = setup();
const original = structuredClone(session.getSnapshot().config);
- queue.enqueueCharacterSheet(session, template, "source");
- queue.enqueueCharacterSheet(session, template, "source");
+ const selected = { ...template, modelType };
+ queue.enqueueCharacterSheet(session, selected, "source");
+ queue.enqueueCharacterSheet(session, selected, "source");
expect(queue.getSnapshot()).toHaveLength(1);
const id = queue.getSnapshot()[0].id;
const pending = parseProjectConfig(JSON.parse(JSON.stringify(session.getSnapshot().config)));
@@ -70,6 +71,8 @@ it.each([false, true])("uses a shared front-view outfit with square portrait and
const viewIndex = order[index];
const referencePaths = ["C:/Character/media/hero.png", ...(index > 0 ? [`C:/Character/cache/character-sheets/${id}/1.png`] : [])];
expect(request).toMatchObject({ stillImage: true, frames: 1, referencePaths, seed });
+ expect(request.steps).toBe(modelType === "h3_image" ? 6 : original.imageScene!.steps);
+ expect(vi.mocked(enqueueSlopfabGeneration).mock.calls[index][1].providerSettings.slopfab?.options.modelType).toBe(modelType);
expect(request.canvasWidth / request.canvasHeight).toBe(viewIndex === 0 ? 1 : 9 / 16);
expect(request.canvasHeight).toBe(1024);
if (index > 0) {
@@ -80,7 +83,10 @@ it.each([false, true])("uses a shared front-view outfit with square portrait and
expect(request.prompt).toContain(["Waist-up front view", "Full body front view", "Full body side view", "Full body back view"][viewIndex]);
expect(request.prompt).toContain("Keep the same character and visual style");
expect(request.prompt).toContain("<Picture 1>");
- expect(request.prompt).toContain("<Subject 1> (appears in [Shot 1]): partially_preserved");
+ if (modelType === "h3_image") {
+ expect(request.prompt).not.toMatch(/\[Shot 1\]|retention_analysis|overall_soundscape/);
+ expect(request.prompt).toContain("the character (<Picture 1>");
+ } else expect(request.prompt).toContain("<Subject 1> (appears in [Shot 1]): partially_preserved");
if (viewIndex === 3) {
expect(request.prompt).toContain("head and body facing away, face hidden");
}
@@ -300,6 +306,22 @@ it("rejects missing or excessive prompt references before starting a template",
expect(enqueueSlopfabGeneration).not.toHaveBeenCalled();
});
+it("validates H3 Image's reference limit including the source and generated front view, and rejects refmods", () => {
+ const { queue, session } = setup();
+ const h3 = { ...template, modelType: "h3_image" };
+ session.update((current) => ({ ...current, references: Array.from({ length: 15 }, (_, index) => ({ id: `ref-${index}`, name: `Outfit ${index}`, kind: "image" as const, description: "", relativePath: `references/${index}.png`, intendedUse: [], createdAt: current.createdAt })) }));
+ const config = session.getSnapshot().config;
+ const prompt = config.references.map((reference) => `@[ref:${reference.id}]`).join(" ");
+ const valid = compileCharacterSheet(config, config.assets[0], "cache/front.png", { prompt: config.references.slice(0, 14).map((reference) => `@[ref:${reference.id}]`).join(" ") }, h3.modelType);
+ expect(valid[3].prompt).toContain("Outfit 13 (<Picture 16>)");
+ expect(() => queue.enqueueCharacterSheet(session, h3, "source", { prompt })).toThrow("at most 16 pictures");
+ session.update((current) => ({ ...current, references: [{ ...current.references[0], refmods: [{ id: "style", name: "Style", relativePath: "references/style.safetensors", strength: 1, copies: 1 }] }] }));
+ expect(() => queue.enqueueCharacterSheet(session, h3, "source", { prompt: "@[ref:ref-0]" })).toThrow("does not support refmods");
+ expect(queue.getSnapshot()).toHaveLength(0);
+ expect(session.getSnapshot().config.assets).toHaveLength(1);
+ expect(enqueueSlopfabGeneration).not.toHaveBeenCalled();
+});
+
it("does not publish a partial result when combining fails and lets the next job run", async () => {
const { queue, session } = setup();
vi.mocked(invoke).mockImplementation(async (command) => {
diff --git a/src/lib/characterSheet.ts b/src/lib/characterSheet.ts
index 7034e92..dcfb9be 100644
--- a/src/lib/characterSheet.ts
+++ b/src/lib/characterSheet.ts
@@ -28,7 +28,7 @@ export function characterSheetDimensions(resolution: ProjectConfig["settings"]["
return CHARACTER_SHEET_VIEWS.map((_, index) => ({ width: index === 0 ? height : height * 9 / 16, height }));
}
-export function compileCharacterSheet(config: ProjectConfig, source: ProjectAsset, frontRelativePath: string, options: CharacterSheetOptions = emptyCharacterSheetOptions()) {
+export function compileCharacterSheet(config: ProjectConfig, source: ProjectAsset, frontRelativePath: string, options: CharacterSheetOptions = emptyCharacterSheetOptions(), modelType?: string) {
const indices = characterSheetViewIndices(options);
if (!indices.length) throw new Error("Enable at least one character sheet view.");
if (options.steps !== undefined && (!Number.isInteger(options.steps) || options.steps < 2 || options.steps > 1000)) throw new Error("Steps must be a whole number from 2 to 1000.");
@@ -56,6 +56,6 @@ export function compileCharacterSheet(config: ProjectConfig, source: ProjectAsse
return [index, compileImagePrompt({
...config, settings: { ...config.settings, defaultLook: null }, references: [selectedReference, ...config.references],
imageScene: scene,
- }, { referenceTransformations: { [reference.id]: "Keep the character's identity; use the requested outfit and view." } })] as const;
+ }, { modelType, referenceTransformations: { [reference.id]: "Keep the character's identity; use the requested outfit and view." } })] as const;
}));
}
diff --git a/src/lib/generatorModels.json b/src/lib/generatorModels.json
index 874a490..5893902 100644
--- a/src/lib/generatorModels.json
+++ b/src/lib/generatorModels.json
@@ -193,7 +193,7 @@
"generationEffects": false,
"cfg": null,
"imageOutpainting": true,
- "characterSheets": false,
+ "characterSheets": true,
"requiresImageInput": false,
"editImageReferences": true,
"maxImageReferences": 16,
diff --git a/src/lib/workQueue.ts b/src/lib/workQueue.ts
index 0fa1faf..5fd9a3c 100644
--- a/src/lib/workQueue.ts
+++ b/src/lib/workQueue.ts
@@ -513,7 +513,7 @@ export class WorkQueue {
slopfab: engineProviderSetting(template.paths, current.providerSettings.slopfab, template.attention, template.loras, "prompt", template.additionalSafetensors, false, template.sources, template) } });
const id = `character-sheet-${crypto.randomUUID()}`;
const frontRelativePath = `cache/character-sheets/${id}/1.png`;
- const views = compileCharacterSheet(config, source, frontRelativePath, options);
+ const views = compileCharacterSheet(config, source, frontRelativePath, options, template.modelType);
config.imageScene = { ...(config.imageScene ?? createImageScene()),
steps: generationStepsWithLoras(options?.steps ?? current.imageScene?.steps ?? template.defaultSteps, config),
seed: options?.seed ?? current.imageScene?.seed ?? -1 };