AI media harness for planning, generating, and editing locally
TypeScript
import { describe, expect, it } from "vitest";
import { completeImageDraft, createTemplateImageDraft, imageFamily, imageFamilyRoot, imageGenerationSnapshot, makeImagePrimary, removeImageAsset, restoreGeneratedImage, saveImageDraft } from "./imageHistory";
import { imageGenerationSnapshotSchema, parseProjectConfig } from "./project";
import fixture from "../../fixtures/project-v1-image.json";
import snapshotFixture from "../../fixtures/image-generation-snapshot.json";
import { createImageEditScene, createImageScene } from "./imageScene";
describe("generated image history", () => {
it("restores a generated original's own prompt despite legacy shared edit instructions", () => {
const config = parseProjectConfig(fixture);
config.imageScene = createImageScene("A forest at sunrise");
const generation = imageGenerationSnapshot(config, "Compiled forest", "generator");
const source = { name: "Original", relativePath: "media/original.png", width: 640, height: 480 };
config.imageScene = createImageEditScene(source);
config.imageScene.nodes[0].description = "Make it snow";
const legacyEditing = imageGenerationSnapshot(config, "Compiled snow", "generator");
config.assets = [{ ...source, id: "original", kind: "image", mimeType: "image/png", createdAt: config.createdAt,
imageGeneration: generation, imageEditing: legacyEditing }];
config.imageScene.outputAssetId = "original";
const drafted = saveImageDraft(config, "generator");
const draftId = drafted.imageScene!.outputAssetId!;
const changed = structuredClone(drafted);
changed.imageScene!.nodes[0].description = "Make it moonlit";
changed.imageScene!.steps = 32;
const saved = saveImageDraft(changed, "generator");
expect(saved.assets[0]).toEqual(config.assets[0]);
expect(drafted.assets[1].imageGeneration!.scene.nodes[0].description).toBe("Make it snow");
const reopened = parseProjectConfig(JSON.parse(JSON.stringify(saved)));
const original = restoreGeneratedImage(reopened, "original");
expect(original.imageScene!.nodes[0].description).toBe("A forest at sunrise");
expect(original.imageScene!.steps).toBe(20);
const edit = restoreGeneratedImage(original, draftId);
expect(edit.imageScene!.nodes[0].description).toBe("Make it moonlit");
expect(edit.imageScene!.steps).toBe(32);
});
it("keeps edits on their own image after reopening and deleting children", () => {
const initial = parseProjectConfig(fixture);
const source = { name: "Original", relativePath: "media/original.png", width: 640, height: 480 };
initial.assets = [{ ...source, id: "original", kind: "image", mimeType: "image/png", createdAt: initial.createdAt }];
initial.imageScene = { ...createImageEditScene(source), outputAssetId: "original" };
initial.imageScene.nodes[0].description = "Make the sky pink";
const drafted = saveImageDraft(initial, "generator");
const draft = drafted.assets.find((asset) => asset.imageDraft)!;
const completed = completeImageDraft(drafted, draft.id, { ...draft, name: "Edited", relativePath: "media/edited.png" });
expect(completed.imageScene!.nodes[0].description).toBe("");
expect(completed.imageScene!.sourceImage?.relativePath).toBe("media/edited.png");
const reopened = parseProjectConfig(JSON.parse(JSON.stringify(completed)));
const parent = restoreGeneratedImage({ ...reopened, assets: removeImageAsset(reopened.assets, draft.id) }, "original");
expect(parent.imageScene!.nodes[0].description).toBe("");
expect(completed.assets[0]).toEqual(initial.assets[0]);
expect(draft.imageGeneration!.scene.nodes[0].description).toBe("Make the sky pink");
expect(parent.imageScene!.sourceImage).toEqual(source);
expect(saveImageDraft(parent)).toBe(parent);
expect(parent.assets).toHaveLength(1);
expect(parent.assets[0].imageGeneration).toBeUndefined();
expect(parent.assets[0].imageEditing).toBeUndefined();
});
it("keeps a submitted template intact when editing its pending entry and completing in the background", () => {
const config = parseProjectConfig(fixture);
config.imageScene = createImageScene("Forest");
const source = { id: "source", kind: "image" as const, name: "Original", relativePath: "media/original.png", width: 512, height: 512, mimeType: "image/png", createdAt: config.createdAt };
config.assets = [source];
const generation = { ...imageGenerationSnapshot(config, "Frozen prompt", "generator"), usedSeed: 12,
template: { kind: "extend" as const, sourceId: source.id, sourceName: source.name, generatorName: "Default", prompt: "Forest", steps: 20, seed: -1,
bounds: { x: -32, y: 0, width: 768, height: 512 } } };
const pending = createTemplateImageDraft(config, "job", "Extended image", generation, { width: 512, height: 320 });
const scene = structuredClone(pending.imageScene!);
scene.nodes[0].description = "A new idea";
const edited = saveImageDraft({ ...pending, imageScene: scene });
const draft = edited.assets.at(-1)!;
expect(draft).toMatchObject({ imageDraft: true, parentAssetId: "source", imageGeneration: { scene: { nodes: [{ description: "A new idea" }] } } });
expect(draft.id).not.toBe("job");
expect(draft.imageGeneration!.template).toBeUndefined();
expect(edited.assets[1]).toEqual(pending.assets[1]);
const result = { ...source, id: "job", name: "Extended image", relativePath: "media/extended.png" };
const done = completeImageDraft(edited, "job", { ...result, imageGeneration: { ...generation, scene: createImageEditScene(result) } });
expect(done.imageScene!.outputAssetId).toBe(draft.id);
expect(done.assets).toHaveLength(3);
expect(done.assets[1]).toMatchObject({ imageDraft: false, imageGeneration: { template: generation.template, usedSeed: 12 } });
expect(done.assets[2]).toEqual(draft);
});
it("preserves a whole-image prompt and linked references as a new draft of a saved image", () => {
const config = parseProjectConfig(fixture);
const source = { relativePath: "media/generated/source.png", name: "Source", width: 101, height: 77 };
config.assets = [{ id: "saved", kind: "image", ...source, mimeType: "image/png", createdAt: config.createdAt }];
config.imageScene = { ...createImageEditScene(source), outputAssetId: "saved" };
config.imageScene.nodes[0].description = "Make the lighting warmer";
config.imageScene.nodes[0].referenceIds = ["mood"];
config.references = [{ id: "mood", name: "Mood", kind: "text", description: "Warm sunset", intendedUse: [], createdAt: config.createdAt }];
const saved = saveImageDraft(config, "test");
expect(saved.assets).toHaveLength(2);
expect(saved.imageScene!.outputAssetId).not.toBe("saved");
const reopened = parseProjectConfig(JSON.parse(JSON.stringify(saved)));
reopened.references = [];
const restored = restoreGeneratedImage(reopened, saved.imageScene!.outputAssetId!);
expect(restored.references).toEqual(config.references);
expect(restored.imageScene!.nodes[0]).toMatchObject({ description: "Make the lighting warmer", referenceIds: ["mood"] });
const snapshot = reopened.assets[1].imageGeneration!;
expect(imageGenerationSnapshotSchema.safeParse({ ...snapshot, references: [] }).success).toBe(false);
});
it("restores saved inputs and references after reopening without changing other results", () => {
const config = parseProjectConfig(fixture);
const snapshot = imageGenerationSnapshotSchema.parse(snapshotFixture);
config.assets = [{ id: "result", kind: "image", name: "Lantern", relativePath: "media/generated/lantern.jpg", mimeType: "image/jpeg", createdAt: config.createdAt, imageGeneration: snapshot }];
config.references = [
{ ...snapshot.references[0], description: "Later reference edit" },
{ id: "unrelated", name: "Unrelated", kind: "text", description: "Keep this", intendedUse: [], createdAt: config.createdAt },
];
const reopened = parseProjectConfig(JSON.parse(JSON.stringify(config)));
const restored = restoreGeneratedImage(reopened, "result");
expect(restored.imageScene).toEqual({ ...snapshot.scene, outputAssetId: "result" });
expect(restored.settings).toEqual(config.settings);
expect(restored.brief.resolution).toBe(config.brief.resolution);
expect(restored.brief.aspectRatio).toBe(config.brief.aspectRatio);
expect(restored.imageSettings).toMatchObject({ resolution: "1088p", aspectRatio: "4:5", defaultLook: "watercolor" });
expect(restored.brief.prompt).toBe(snapshot.briefPrompt);
expect(restored.references).toEqual([snapshot.references[0], config.references[1]]);
expect(restored.assets).toEqual(config.assets);
restored.imageScene!.nodes[0].description = "New edit";
restored.references[0].refmods![0].strength = 0;
expect(restored.assets[0].imageGeneration).toEqual(snapshotFixture);
reopened.references = [];
expect(restoreGeneratedImage(reopened, "result").references).toEqual(snapshot.references);
});
it("captures an independent snapshot and preserves legacy images without inventing history", () => {
const config = parseProjectConfig(fixture);
const snapshot = imageGenerationSnapshot(config, "Exact submitted prompt", "generator");
config.imageScene!.nodes[0].description = "Later edit";
config.settings.resolution = "1344p";
expect(snapshot.scene.nodes[0].description).not.toBe("Later edit");
expect(snapshot.resolution).toBe("768p");
expect(snapshot.prompt).toBe("Exact submitted prompt");
expect(snapshot.scene.outputAssetId).toBeNull();
config.assets = [{ id: "legacy", kind: "image", name: "Legacy", relativePath: "media/generated/legacy.jpg", mimeType: "image/jpeg", createdAt: config.createdAt }];
const restored = restoreGeneratedImage(config, "legacy");
expect(restored.imageScene).toEqual({ ...createImageScene(), outputAssetId: "legacy" });
expect(restored.settings).toEqual(config.settings);
});
it("rejects corrupt snapshot trees and missing or duplicate reference definitions", () => {
const snapshot = structuredClone(snapshotFixture);
snapshot.scene.nodes[1].parentId = "missing";
expect(imageGenerationSnapshotSchema.safeParse(snapshot).success).toBe(false);
expect(imageGenerationSnapshotSchema.safeParse({ ...snapshotFixture, references: [] }).success).toBe(false);
expect(imageGenerationSnapshotSchema.safeParse({ ...snapshotFixture, references: [...snapshotFixture.references, ...snapshotFixture.references] }).success).toBe(false);
});
it("leaves image-root mode when selecting an older result without a snapshot", () => {
const config = parseProjectConfig(fixture);
config.imageScene = createImageEditScene({ relativePath: "media/imported/source.png", name: "Source", width: 65, height: 41 });
config.assets = [{ id: "legacy", kind: "image", name: "Legacy", relativePath: "media/generated/legacy.jpg", mimeType: "image/jpeg", createdAt: config.createdAt }];
const restored = restoreGeneratedImage(config, "legacy");
expect(restored.imageScene!.rootType).not.toBe("image");
expect(restored.imageScene!.outputAssetId).toBe("legacy");
expect(restored.imageScene!.sourceImage).toBeUndefined();
});
it("puts an edit of any image in its original's family, one level deep", () => {
const config = parseProjectConfig(fixture);
const image = (id: string, parentAssetId?: string) => ({ id, name: id, kind: "image" as const, relativePath: `media/generated/${id}.png`, mimeType: "image/png", width: 101, height: 77, createdAt: config.createdAt, ...(parentAssetId ? { parentAssetId } : {}) });
config.assets = [image("original"), image("child", "original")];
expect(imageFamilyRoot(config.assets, "child")).toBe("original");
expect(imageFamilyRoot(config.assets, "original")).toBe("original");
// Editing the child starts a draft in the original's family, not the child's.
config.imageScene = createImageEditScene({ relativePath: "media/generated/child.png", name: "child", width: 101, height: 77 });
const drafted = saveImageDraft(config, "test");
const draft = drafted.assets.find((asset) => asset.imageDraft)!;
expect(draft.parentAssetId).toBe("original");
// Generating it keeps the family.
const done = completeImageDraft(drafted, draft.id, { ...image(draft.id), imageGeneration: { ...draft.imageGeneration!, usedSeed: 91234 } });
expect(done.assets.find((asset) => asset.id === draft.id)).toMatchObject({ imageDraft: false, parentAssetId: "original" });
expect(done.assets.some((asset) => asset.imageDraft)).toBe(false);
expect(done.assets.find((asset) => asset.id === draft.id)!.imageGeneration!.usedSeed).toBe(91234);
expect(parseProjectConfig(JSON.parse(JSON.stringify(done))).assets).toEqual(done.assets);
// An imported file starts a family of its own.
config.imageScene = createImageEditScene({ relativePath: "media/imported/photo.png", name: "photo", width: 101, height: 77 });
const imported = saveImageDraft(config, "test");
const original = imported.assets.find((asset) => asset.relativePath === "media/imported/photo.png" && !asset.imageDraft)!;
expect(original).toMatchObject({ name: "photo", width: 101, height: 77 });
expect(imported.assets.find((asset) => asset.imageDraft)!.parentAssetId).toBe(original.id);
expect(saveImageDraft(imported, "test").assets).toEqual(imported.assets);
});
it("keeps a family together when its original is removed", () => {
const config = parseProjectConfig(fixture);
const image = (id: string, parentAssetId?: string) => ({ id, name: id, kind: "image" as const, relativePath: `media/generated/${id}.jpg`, mimeType: "image/jpeg", createdAt: config.createdAt, ...(parentAssetId ? { parentAssetId } : {}) });
const assets = removeImageAsset([image("a"), image("b", "a"), image("c", "a"), image("d")], "a");
expect(assets.map((asset) => [asset.id, asset.parentAssetId])).toEqual([["b", undefined], ["c", "b"], ["d", undefined]]);
});
it("promotes an image in place, keeps the family flat, and attaches future edits to its new primary", () => {
const config = parseProjectConfig(fixture);
const image = (id: string, parentAssetId?: string) => ({ id, name: id, kind: "image" as const, relativePath: `media/${id}.png`, mimeType: "image/png", width: 640, height: 480, createdAt: config.createdAt, ...(parentAssetId ? { parentAssetId } : {}) });
config.assets = [image("before"), image("original"), image("after"), image("retry", "original"), image("chosen", "original")];
const promoted = makeImagePrimary(config.assets, "chosen");
expect(promoted.filter((asset) => !asset.parentAssetId).map((asset) => asset.id)).toEqual(["before", "chosen", "after"]);
expect(imageFamily(promoted, "original").map((asset) => [asset.id, asset.parentAssetId])).toEqual([
["chosen", undefined], ["original", "chosen"], ["retry", "chosen"],
]);
expect(config.assets[1].parentAssetId).toBeUndefined();
expect(makeImagePrimary(promoted, "chosen")).toBe(promoted);
const reopened = parseProjectConfig(JSON.parse(JSON.stringify({ ...config, assets: promoted })));
expect(imageFamilyRoot(reopened.assets, "retry")).toBe("chosen");
reopened.imageScene = createImageEditScene({ relativePath: "media/original.png", name: "original", width: 640, height: 480 });
expect(saveImageDraft(reopened).assets.at(-1)?.parentAssetId).toBe("chosen");
expect(imageFamily(removeImageAsset(promoted, "chosen"), "retry").map((asset) => asset.id)).toEqual(["original", "retry"]);
});
});