AI media harness for planning, generating, and editing locally
TypeScript
Use H3 picture anchors for image edits
Bitti5fef2f733d89
diff --git a/docs/architecture.md b/docs/architecture.mdindex ae58da4..72ba17e 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -45,6 +45,8 @@ Shots are sequential, later shots carry increasing cut timestamps, camera movesImage 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`.+Image-root edits also use all six reference sections, even without selected references. The original source is submitted as the first reference image and defined as the standalone `<Picture 1>` composition anchor. The summary uses `[keyframe completion]` (plus `reference generation` for additional subjects), and retention marks the edited keyframe `partially_preserved`. Additional reference pictures start at 2; the source consumes one of H3's nine image-reference slots. Each inpainting step uses the previous result's pixels for its edit source while retaining the original picture as the visual anchor. Debug Prompt and saved generation snapshots contain these exact per-edit prompts.+## Generation boundaryEach newly generated image asset stores an optional `imageGeneration` snapshot captured when the job is queued: the authored image tree, background and style, seed and steps, resolution and aspect ratio, project look, brief, selected reference definitions and attachments, generator template ID, and exact submitted prompt. Completion attaches that snapshot without replacing edits made during generation. Selecting the result restores a copy of its inputs and merges its saved references into the library; other results and unrelated references remain available. The native project schema validates and preserves snapshots on save and reopen. Older images without a snapshot retain the current authoring state when selected.diff --git a/src/lib/imageEditing.test.ts b/src/lib/imageEditing.test.tsindex cf2f827..e04ab60 100644--- a/src/lib/imageEditing.test.ts+++ b/src/lib/imageEditing.test.ts@@ -23,10 +23,30 @@ it("uses hierarchy order, skips empty groups, and converts boxes to original pixexpect(edits[1].prompt).toContain("A blue boat");expect(edits[0].prompt).not.toContain("watercolor");expect(edits[0].prompt).toContain("[Shot 1]");+ expect(edits[0].prompt.match(/^\w+:/gm)).toEqual(["subject_definitions:", "summary:", "retention_analysis:", "detailed_description:", "overall_soundscape:", "non_diegetic_music:"]);+ expect(edits[0].prompt).toContain("<Picture 1> is the original source image");+ expect(edits[0].prompt).toContain("[keyframe completion]");+ expect(edits[0].prompt).toContain("<Picture 1> ([Shot 1] edited keyframe): partially_preserved");+ expect(edits[0].prompt).toContain("[Shot 1] The edited keyframe corresponds to <Picture 1>");+ expect(edits[0].prompt).not.toMatch(/<Subject|video editing|A still photograph/);scene.nodes[3].box = null;expect(() => compileImageEdits(config)).toThrow("placement box");});+it("reserves Picture 1 for the source and counts it toward H3's nine-picture limit", () => {+ const config = parseProjectConfig(fixture);+ config.imageScene = addImageNode(createImageEditScene({ relativePath: "media/imported/source.png", name: "Source", width: 101, height: 77 }), "image-root", "object");+ config.imageScene.nodes[1].description = "A red balloon";+ config.references = Array.from({ length: 9 }, (_, index) => ({ id: `ref-${index}`, kind: "image" as const, name: `Reference ${index}`, description: "Red satin", relativePath: `references/${index}.png`, intendedUse: [], createdAt: config.createdAt }));+ config.imageScene.referenceIds = config.references.slice(0, 8).map((reference) => reference.id);+ const prompt = compileImageEdits(config).edits[0].prompt;+ expect(prompt).toContain("<Subject 1> is Reference 0, providing appearance from <Picture 2>");+ expect(prompt).toContain("<Subject 8> is Reference 7, providing appearance from <Picture 9>");+ expect(prompt).toContain("[keyframe completion + reference generation]");+ config.imageScene.referenceIds.push("ref-8");+ expect(() => compileImageEdits(config)).toThrow("at most nine reference images");+});+it("starts with a clean image root and requires described edits before submission", () => {const config = parseProjectConfig(fixture);config.assets.push({ id: "source", name: "Source", relativePath: "media/generated/source.jpg", mimeType: "image/jpeg", width: 101, height: 77, kind: "image", createdAt: config.createdAt });diff --git a/src/lib/imageEditing.ts b/src/lib/imageEditing.tsindex ec94648..7e3d164 100644--- a/src/lib/imageEditing.ts+++ b/src/lib/imageEditing.ts@@ -18,13 +18,11 @@ export function compileImageEdits(config: ProjectConfig): { source: ImageSource;const y = Math.min(source.height - 1, Math.floor(node.box.y * source.height / 1000));const right = Math.min(source.width, Math.ceil((node.box.x + node.box.width) * source.width / 1000));const bottom = Math.min(source.height, Math.ceil((node.box.y + node.box.height) * source.height / 1000));- const description = ["Edit the masked rectangle of the supplied image. Preserve the surrounding composition, medium and lighting.", node.description,+ const description = ["The edited keyframe corresponds to <Picture 1>, with the following change confined to the masked rectangle. Preserve the surrounding composition and any previously completed edits.", node.description,node.text ? `Render the exact text "${node.text}".` : "", node.colors.length ? `Use these colors: ${node.colors.join(", ")}.` : ""].filter(Boolean).join(" ");- const editScene = { ...createImageScene(description), referenceIds: scene.referenceIds };+ const editScene = { ...createImageScene(description), rootType: "image" as const, sourceImage: source, referenceIds: scene.referenceIds };const compiled = compileImagePrompt({ ...config, settings: { ...config.settings, defaultLook: null }, imageScene: editScene });- // Keep the existing image's medium rather than imposing Photo/Art defaults.- const prompt = compiled.prompt.replace("A still photograph.", "A still image retaining the supplied image's visual style.");- return { prompt, x, y, width: Math.max(1, right - x), height: Math.max(1, bottom - y) };+ return { prompt: compiled.prompt, x, y, width: Math.max(1, right - x), height: Math.max(1, bottom - y) };});if (!edits.length) throw new Error("Add an Object node and describe an edit before generating.");return { source, edits };diff --git a/src/lib/imagePrompt.ts b/src/lib/imagePrompt.tsindex e058f95..ac24e2b 100644--- a/src/lib/imagePrompt.ts+++ b/src/lib/imagePrompt.ts@@ -12,7 +12,10 @@ export function compileImagePrompt(config: ProjectConfig) {if (reference.kind === "video" || reference.kind === "audio") throw new Error("Still images accept image and text references.");return reference;});- let picture = 0;+ // An inpainting source is also an explicit composition anchor. The caller+ // submits it before the selected reference pictures, even with no subjects.+ const editing = scene.rootType === "image" && Boolean(scene.sourceImage);+ let picture = editing ? 1 : 0;const subjects = references.flatMap((reference) => {const labels = referenceImages(reference).map(() => `<Picture ${++picture}>`);const definition = referenceDefinition(reference);@@ -29,15 +32,25 @@ export function compileImagePrompt(config: ProjectConfig) {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 {+ if (!subjects.length && !editing) return {prompt: [`integrated_multimodal_description: [Shot 1] ${visual.style}\n${visual.composition}`, ...audio].join("\n\n"), references,};const label = (index: number) => `<Subject ${index + 1}>`;+ const definitions = subjects.map((subject, index) => `${label(index)} is ${subject.name}, providing ${subject.role}${subject.source}. ${subject.description}`);+ const retention = 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.`);+ if (editing) {+ definitions.unshift("<Picture 1> is the original source image and composition anchor for the edited still keyframe in [Shot 1], providing the framing, perspective, environment, lighting and visual style.");+ retention.unshift("<Picture 1> ([Shot 1] edited keyframe): partially_preserved - retain its composition and visual characteristics while changing the requested region. Preserve all pixels outside the edit box, including any previously completed edits.");+ }+ const summary = editing+ ? `[keyframe completion${subjects.length ? " + reference generation" : ""}] The target is a single edited still keyframe based on <Picture 1>. Apply the described change only inside the edit box.${subjects.length ? ` Use ${subjects.map((_, index) => label(index)).join(", ")} for the specified reference attributes.` : ""}`+ : `[reference generation] A single still image uses ${subjects.map((_, index) => label(index)).join(", ")} in the requested composition.`;+ const style = editing ? "The still image retains the visual medium, lighting, palette and perspective of <Picture 1>." : visual.style;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")}`,+ `subject_definitions:\n${definitions.join("\n")}`,+ `summary:\n${summary}`,+ `retention_analysis:\n${retention.join("\n")}`,+ `detailed_description:\n${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/workQueue.test.ts b/src/lib/workQueue.test.tsindex 950103e..5c7d014 100644--- a/src/lib/workQueue.test.ts+++ b/src/lib/workQueue.test.ts@@ -67,11 +67,19 @@ describe("image generation work", () => {scene.nodes.at(-1)!.description = description;}record.config.imageScene = scene;+ record.config.references = [{ id: "balloon", kind: "image", name: "Balloon", description: "Red satin", relativePath: "references/balloon.png", intendedUse: [], createdAt: record.config.createdAt }];+ scene.referenceIds = ["balloon"];const session = queue.project(record);vi.mocked(invoke).mockResolvedValue({ relativePath: "media/generated/edited.png", width: 101, height: 77 });queue.enqueueImage(session, template);await waitFor(() => expect(enqueueSlopfabGeneration).toHaveBeenCalledOnce());const request = vi.mocked(enqueueSlopfabGeneration).mock.calls[0][0];+ expect(request.referencePaths).toEqual(["C:/Image/media/generated/source.jpg", "C:/Image/references/balloon.png"]);+ expect(vi.mocked(resolveSlopfabPlan).mock.calls[0][0].referencePaths).toEqual(request.referencePaths);+ for (const edit of request.imageEdit!.edits) {+ expect(edit.prompt).toContain("<Picture 1> is the original source image");+ expect(edit.prompt).toContain("<Subject 1> is Balloon, providing appearance from <Picture 2>");+ }expect(request).toMatchObject({ stillImage: true, frames: 1, canvasWidth: 101, canvasHeight: 77, imageEdit: { sourceRelativePath: "media/generated/source.jpg", edits: [{ prompt: expect.stringContaining("A red balloon"), x: 25, y: 19, width: 51, height: 39 },{ prompt: expect.stringContaining("A blue boat"), x: 25, y: 19, width: 51, height: 39 },diff --git a/src/lib/workQueue.ts b/src/lib/workQueue.tsindex 6ac1c24..ab8cf9d 100644--- a/src/lib/workQueue.ts+++ b/src/lib/workQueue.ts@@ -218,7 +218,8 @@ export class WorkQueue {const request: SlopfabGenerationRequest = { jobId: id, stillImage: true, frames: 1, prompt: edit ? edit.edits[0].prompt : prompt,...(edit ? { imageEdit: { sourceRelativePath: edit.source.relativePath, edits: edit.edits } } : {}),canvasWidth: width, canvasHeight: height, steps: generationStepsWithLoras(scene.steps, config), seed: scene.seed,- referencePaths: references.flatMap((reference) => referenceImages(reference).map((image) => projectItemPath(session.record.folderPath, image)!)),+ referencePaths: [...(edit ? [projectItemPath(session.record.folderPath, edit.source)!] : []),+ ...references.flatMap((reference) => referenceImages(reference).map((image) => projectItemPath(session.record.folderPath, image)!))],refmods: referenceRefmodInputs(session.record.folderPath, references),};this.work.set(id, { id, image: true, imageGeneration: imageGenerationSnapshot(config, edit ? imageEditDebugPrompt(edit.edits) : prompt, template.id), session, sceneId: scene.nodes.find((node) => node.kind === "root")!.id, config, snapshot: JSON.stringify(scene), request, submitted: false, cancelled: false, done, finish });