feat: implement generation workflow with resource loading and candidate management

README.md

@@ -5,6 +5,8 @@ Image Studio is a Bun + React image editor prototype. It uses a command-driven a
 ## Features
 
 - Import images into an artboard
+- Save and open versioned project files with embedded, project-owned assets
+- Automatic local recovery snapshots after document changes
 - Export the active artboard as PNG
 - Layer selection and layer sheet
 - Select, transform, pan, brush, eraser, chroma key, and magic wand tools
@@ -71,6 +73,8 @@ bun start
 | `Space` | Hold to pan |
 | `L` | Toggle layers |
 | `Cmd/Ctrl` + `O` | Open image |
+| `Shift` + `Cmd/Ctrl` + `O` | Open project |
+| `Cmd/Ctrl` + `S` | Save project |
 | `Cmd/Ctrl` + `Z` | Undo |
 | `Shift` + `Cmd/Ctrl` + `Z` | Redo |
 | `Delete` / `Backspace` | Delete selection |

app/app.ts

@@ -10,14 +10,17 @@ import { transformCommands } from "@commands/transform";
 import { viewportCommands } from "@commands/viewport";
 import { workspaceCommands } from "@commands/workspace";
 import { editorCommands } from "@commands/editor";
+import { projectCommands } from "@commands/project";
 import { createInitialAppState } from "@editor/initial-state";
 import { createAppStore } from "@editor/store";
+import { createGenerationWorkflow } from "@operations/generation/workflow";
 
 export type ImageStudioApp = ReturnType<typeof createImageStudioApp>;
 
 export function createImageStudioApp(options?: { documentName?: string; createDefaultArtboard?: boolean }) {
-  const registry = createCommandRegistry([...viewportCommands, ...selectionCommands, ...documentCommands, ...toolCommands, ...generationCommands, ...transformCommands, ...historyCommands, ...commandPaletteCommands, ...workspaceCommands, ...editorCommands]);
+  const registry = createCommandRegistry([...projectCommands, ...viewportCommands, ...selectionCommands, ...documentCommands, ...toolCommands, ...generationCommands, ...transformCommands, ...historyCommands, ...commandPaletteCommands, ...workspaceCommands, ...editorCommands]);
   const store = createAppStore(createInitialAppState(options?.documentName), registry);
+  const generation = createGenerationWorkflow(store);
 
   if (options?.createDefaultArtboard !== false) {
     const artboardId = crypto.randomUUID();
@@ -32,5 +35,6 @@ export function createImageStudioApp(options?: { documentName?: string; createDe
   return {
     registry,
     store,
+    workflows: { generation },
   };
 }

commands/ids.ts

@@ -1,4 +1,5 @@
 export const commandIds = {
+  projectOpen: "project.open",
   documentAddArtboard: "document.addArtboard",
   documentSetArtboardBounds: "document.setArtboardBounds",
   documentRemoveArtboard: "document.removeArtboard",

commands/index.ts

@@ -1,4 +1,6 @@
 export type { Command, CommandContext } from "./command";
+export { projectCommands, projectOpenCommand } from "./project";
+export type { ProjectOpenPayload } from "./project";
 export {
   documentAddArtboardCommand,
   documentAddAssetCommand,

commands/payloads.ts

@@ -46,6 +46,7 @@ import type { ToolEnterMaskEditPayload, ToolSetActivePayload, ToolSetBrushPrevie
 import type { TransformBeginPayload, TransformSetBoundsPayload, TransformUpdatePayload } from "./transform";
 import type { WorkspaceSetPanelPayload } from "./workspace";
 import type { EditorSetPointerSessionPayload } from "./editor";
+import type { ProjectOpenPayload } from "./project";
 import type {
   ViewportFitArtboardPayload,
   ViewportPanPayload,
@@ -55,6 +56,7 @@ import type {
 } from "./viewport";
 
 export type CommandPayloads = {
+  [commandIds.projectOpen]: ProjectOpenPayload;
   [commandIds.documentAddArtboard]: DocumentAddArtboardPayload;
   [commandIds.documentSetArtboardBounds]: DocumentSetArtboardBoundsPayload;
   [commandIds.documentRemoveArtboard]: DocumentRemoveArtboardPayload;

commands/project.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import { createInitialAppState } from "@editor/initial-state";
+import { createAppStore } from "@editor/store";
+import { createCommandRegistry } from "./registry";
+import { documentAddArtboardCommand, documentRenameArtboardCommand } from "./document";
+import { projectOpenCommand } from "./project";
+import { commandIds } from "./ids";
+
+describe("open project command", () => {
+  test("replaces the document and resets transient sessions and history", () => {
+    const app = createTestApp("Original");
+    const replacement = createTestApp("Opened").store.getState().document;
+    const originalArtboardId = app.store.getState().document.artboards[0]!.id;
+    app.store.dispatch(commandIds.documentRenameArtboard, { id: originalArtboardId, name: "Changed" });
+    expect(app.store.getState().history.past).toHaveLength(2);
+
+    app.store.dispatch(commandIds.projectOpen, { document: replacement });
+
+    const state = app.store.getState();
+    expect(state.document).toBe(replacement);
+    expect(state.editor.selection).toEqual({ artboardId: replacement.artboards[0]!.id, layerIds: [] });
+    expect(state.editor.generation.candidates).toEqual([]);
+    expect(state.history).toEqual({ past: [], future: [] });
+  });
+});
+
+function createTestApp(name: string) {
+  const store = createAppStore(createInitialAppState(name), createCommandRegistry([projectOpenCommand, documentAddArtboardCommand, documentRenameArtboardCommand]));
+  store.dispatch(commandIds.documentAddArtboard, { id: `${name}-artboard`, name: "Board", bounds: { x: 0, y: 0, w: 100, h: 100 } });
+  return { store };
+}

commands/project.ts

@@ -0,0 +1,37 @@
+import type { ImageDocument } from "@core/document";
+import { initialEditorState } from "@editor/initial-state";
+import type { Command } from "./command";
+import { commandIds } from "./ids";
+
+export type ProjectOpenPayload = { document: ImageDocument };
+
+export const projectOpenCommand: Command<ProjectOpenPayload> = {
+  id: commandIds.projectOpen,
+  name: "Open project",
+  history: { mode: "ignore" },
+  execute({ state }, payload) {
+    const firstArtboard = payload.document.artboards[0];
+    const viewport = state.editor.viewport;
+    const padding = 48;
+    const availableWidth = Math.max(0, viewport.size.w - padding * 2);
+    const availableHeight = Math.max(0, viewport.size.h - padding * 2);
+    const canFit = Boolean(firstArtboard && availableWidth > 0 && availableHeight > 0 && firstArtboard.bounds.w > 0 && firstArtboard.bounds.h > 0);
+    return {
+      document: payload.document,
+      editor: {
+        ...initialEditorState,
+        viewport: {
+          ...viewport,
+          center: firstArtboard
+            ? { x: firstArtboard.bounds.x + firstArtboard.bounds.w / 2, y: firstArtboard.bounds.y + firstArtboard.bounds.h / 2 }
+            : viewport.center,
+          zoom: canFit && firstArtboard ? Math.max(0.01, Math.min(availableWidth / firstArtboard.bounds.w, availableHeight / firstArtboard.bounds.h)) : viewport.zoom,
+        },
+        selection: { artboardId: firstArtboard?.id, layerIds: [] },
+      },
+      history: { past: [], future: [] },
+    };
+  },
+};
+
+export const projectCommands = [projectOpenCommand] satisfies Command<unknown>[];

operations/generation/options.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { initialToolState } from "@editor/tools";
+import { resolveGenerationModeOptions, resolveGenerationModelOptions } from "./options";
+
+describe("generation compatibility options", () => {
+  test("uses backend compatibility data for modes", () => {
+    const settings = { ...initialToolState.generate, architecture: "anima" as const, mode: "inpaint" as const };
+    const modes = [
+      { value: "text-to-image" as const, label: "Text" },
+      { value: "inpaint" as const, label: "Inpaint" },
+    ];
+    const options = { architectures: [{ value: "anima" as const, label: "Anima", models: [], defaultModel: "auto", supportedModes: ["text-to-image" as const] }], models: [], samplers: [], schedulers: [], textEncoders: [], vaes: [] };
+
+    expect(resolveGenerationModeOptions(settings, options, modes).map((option) => option.value)).toEqual(["inpaint", "text-to-image"]);
+  });
+
+  test("keeps the current model alongside discovered models", () => {
+    const settings = { ...initialToolState.generate, model: "current.safetensors" };
+    const options = { architectures: [], models: ["found.safetensors"], samplers: [], schedulers: [], textEncoders: [], vaes: [] };
+
+    expect(resolveGenerationModelOptions(settings, options).map((option) => option.value)).toEqual(["auto", "found.safetensors", "current.safetensors"]);
+  });
+});

operations/generation/options.ts

@@ -0,0 +1,41 @@
+import type { GenerationOptions } from "@editor/state";
+import { generateArchitectureDefaults } from "@editor/tools";
+import type { GenerateMode, GenerateModel, GenerateSettings } from "@editor/tools";
+
+export type GenerationSelectOption<TValue extends string> = { value: TValue; label: string };
+
+export function resolveGenerationModelOptions(settings: GenerateSettings, options: GenerationOptions | undefined): readonly GenerationSelectOption<GenerateModel>[] {
+  const architecture = options?.architectures?.find((item) => item.value === settings.architecture);
+  const models = architecture?.models ?? (settings.architecture === "sdxl" ? options?.models : undefined) ?? [];
+  const fallbackModel = architecture?.defaultModel ?? generateArchitectureDefaults[settings.architecture].model;
+  const values = unique(["auto", ...models, ...(models.length === 0 && fallbackModel !== "auto" ? [fallbackModel] : []), settings.model]);
+  return values.map((model) => ({ value: model, label: model === "auto" ? "Auto" : model }));
+}
+
+export function resolveGenerationSupportOptions(settings: GenerateSettings, options: GenerationOptions | undefined) {
+  const defaults = generateArchitectureDefaults[settings.architecture];
+  return {
+    textEncoders: resolveGenerationStringOptions([...(options?.textEncoders ?? []), defaults.textEncoder].filter((value) => value !== "auto"), settings.textEncoder),
+    vaes: resolveGenerationStringOptions([...(options?.vaes ?? []), defaults.vae].filter((value) => value !== "auto"), settings.vae),
+  };
+}
+
+export function resolveGenerationStringOptions(values: string[] | undefined, current: string): readonly GenerationSelectOption<string>[] {
+  return unique([...(values ?? []), current]).map((value) => ({ value, label: value }));
+}
+
+export function resolveGenerationModeOptions(
+  settings: GenerateSettings,
+  options: GenerationOptions | undefined,
+  modes: readonly GenerationSelectOption<GenerateMode>[],
+): readonly GenerationSelectOption<GenerateMode>[] {
+  const architecture = options?.architectures?.find((item) => item.value === settings.architecture);
+  const supportedModes = architecture?.supportedModes?.length ? architecture.supportedModes : generateArchitectureDefaults[settings.architecture].supportedModes;
+  const availableModes = modes.filter((mode) => supportedModes.includes(mode.value));
+  if (availableModes.some((mode) => mode.value === settings.mode)) return availableModes;
+  return [modes.find((mode) => mode.value === settings.mode), ...availableModes].filter((mode): mode is GenerationSelectOption<GenerateMode> => Boolean(mode));
+}
+
+function unique<T>(values: T[]): T[] {
+  return Array.from(new Set(values));
+}

operations/generation/outputPlacement.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import type { ImageDocument } from "@core/document";
+import type { GenerateSettings } from "@editor/tools";
+import { createInitialAppState } from "@editor/initial-state";
+import { resolveGeneratedOutputPlacement } from "./outputPlacement";
+
+describe("generated output placement", () => {
+  test("centers text-to-image output in the active artboard", () => {
+    const placement = resolveGeneratedOutputPlacement({
+      document: document(),
+      selection: { artboardId: "artboard", layerIds: [] },
+      settings: settings("text-to-image"),
+      intrinsicSize: { w: 400, h: 200 },
+    });
+
+    expect(placement).toEqual({
+      artboardId: "artboard",
+      layerName: "Generated image",
+      transform: { position: { x: 310, y: 270 }, scale: { x: 1, y: 1 }, rotation: 0 },
+    });
+  });
+
+  test("matches image-to-image output to the selected layer bounds", () => {
+    const placement = resolveGeneratedOutputPlacement({
+      document: document(),
+      selection: selected(),
+      settings: settings("image-to-image"),
+      intrinsicSize: { w: 200, h: 250 },
+    });
+
+    expect(placement.transform).toEqual({
+      position: { x: 80, y: 90 },
+      scale: { x: 0.75, y: 1 },
+      rotation: 12,
+    });
+  });
+
+  test("places an inpaint crop at its recorded document bounds", () => {
+    const placement = resolveGeneratedOutputPlacement({
+      document: document(),
+      selection: selected(),
+      settings: settings("inpaint"),
+      intrinsicSize: { w: 128, h: 64 },
+      inpaintBundle: {
+        inputImage: "input", maskImage: "mask", width: 256, height: 128,
+        targetLayerId: "source", maskLayerId: "mask", sourceAssetId: "source-asset", maskAssetId: "mask-asset",
+        crop: { assetBounds: { x: 0, y: 0, w: 256, h: 128 }, documentBounds: { x: 140, y: 150, w: 384, h: 64 }, padding: 16, maskedAreaOnly: true },
+        mask: { polarity: "hidden", activeBounds: { x: 20, y: 20, w: 40, h: 40 } },
+        placement: { artboardId: "artboard", layerName: "Source inpaint", transform: { position: { x: 140, y: 150 }, scale: { x: 1.5, y: 0.5 }, rotation: 12 } },
+        backend: { growMaskBy: 6, maskedContent: "neutral", maskBlur: 0, maskFeather: 0, maskExpand: 0, cropPadding: 16 },
+      },
+    });
+
+    expect(placement.transform).toEqual({ position: { x: 140, y: 150 }, scale: { x: 3, y: 1 }, rotation: 12 });
+  });
+
+  test("extends outpaint output left and top while preserving source pixel scale", () => {
+    const outpaint = { ...settings("outpaint"), outpaint: { left: 40, top: 20, right: 10, bottom: 30, feathering: 8 } };
+    const placement = resolveGeneratedOutputPlacement({
+      document: document(),
+      selection: selected(),
+      settings: outpaint,
+      intrinsicSize: { w: 150, h: 550 },
+    });
+
+    expect(placement.transform).toEqual({
+      position: { x: 20, y: 80 },
+      scale: { x: 1.5, y: 0.5 },
+      rotation: 12,
+    });
+  });
+});
+
+function settings(mode: GenerateSettings["mode"]): GenerateSettings {
+  return { ...createInitialAppState("Test").editor.tools.generate, mode };
+}
+
+function selected() {
+  return { artboardId: "artboard", layerIds: ["source"] };
+}
+
+function document(): ImageDocument {
+  return {
+    id: "document", name: "Test", version: 1,
+    assets: [
+      { id: "source-asset", name: "Source", mimeType: "image/png", source: "source", intrinsicSize: { w: 100, h: 500 } },
+      { id: "mask-asset", name: "Mask", mimeType: "image/png", source: "mask", intrinsicSize: { w: 100, h: 500 } },
+    ],
+    artboards: [{
+      id: "artboard", name: "Artboard", bounds: { x: 10, y: 20, w: 1000, h: 700 }, backgroundColor: "transparent", visible: true, locked: false,
+      layers: [{ id: "source", type: "raster", name: "Source", visible: true, locked: false, opacity: 1, assetId: "source-asset", transform: { position: { x: 80, y: 90 }, scale: { x: 1.5, y: 0.5 }, rotation: 12 } }],
+    }],
+  };
+}

operations/generation/outputPlacement.ts

@@ -0,0 +1,105 @@
+import type { ImageDocument } from "@core/document";
+import type { Size, Transform } from "@core/geometry";
+import type { ArtboardId } from "@core/id";
+import { createDocumentReadIndex } from "@editor/document-indexes";
+import type { GenerationCandidate, SelectionState } from "@editor/state";
+import type { GenerateSettings } from "@editor/tools";
+import type { InpaintBundle } from "./inpaintPrep";
+
+export type GeneratedOutputPlacement = GenerationCandidate["placement"];
+
+export function resolveGeneratedOutputPlacement(options: {
+  document: ImageDocument;
+  selection: SelectionState;
+  settings: GenerateSettings;
+  intrinsicSize: Size;
+  inpaintBundle?: InpaintBundle;
+}): GeneratedOutputPlacement {
+  const { document, selection, settings, intrinsicSize, inpaintBundle } = options;
+  if (inpaintBundle) {
+    return {
+      artboardId: inpaintBundle.placement.artboardId,
+      layerName: inpaintBundle.placement.layerName,
+      transform: scaleInpaintPlacement(inpaintBundle, intrinsicSize),
+    };
+  }
+
+  const artboard = selection.artboardId
+    ? document.artboards.find((candidate) => candidate.id === selection.artboardId)
+    : document.artboards[0];
+  if (!artboard) throw new Error("Create an artboard before placing generated output.");
+
+  if (settings.mode === "text-to-image") {
+    return {
+      artboardId: artboard.id,
+      layerName: "Generated image",
+      transform: {
+        position: {
+          x: artboard.bounds.x + (artboard.bounds.w - intrinsicSize.w) / 2,
+          y: artboard.bounds.y + (artboard.bounds.h - intrinsicSize.h) / 2,
+        },
+        scale: { x: 1, y: 1 },
+        rotation: 0,
+      },
+    };
+  }
+
+  const target = resolveTarget(document, selection, artboard.id);
+  const sourceScale = {
+    x: target.layer.transform.scale.x * target.asset.intrinsicSize.w / Math.max(1, intrinsicSize.w),
+    y: target.layer.transform.scale.y * target.asset.intrinsicSize.h / Math.max(1, intrinsicSize.h),
+  };
+
+  if (settings.mode === "image-to-image") {
+    return {
+      artboardId: artboard.id,
+      layerName: "Generated image",
+      transform: {
+        position: { ...target.layer.transform.position },
+        scale: sourceScale,
+        rotation: target.layer.transform.rotation,
+      },
+    };
+  }
+
+  if (settings.mode === "outpaint") {
+    const pixelScale = target.layer.transform.scale;
+    return {
+      artboardId: artboard.id,
+      layerName: "Generated image",
+      transform: {
+        position: {
+          x: target.layer.transform.position.x - settings.outpaint.left * pixelScale.x,
+          y: target.layer.transform.position.y - settings.outpaint.top * pixelScale.y,
+        },
+        scale: { ...pixelScale },
+        rotation: target.layer.transform.rotation,
+      },
+    };
+  }
+
+  throw new Error("Inpaint output requires an inpaint placement bundle.");
+}
+
+function resolveTarget(document: ImageDocument, selection: SelectionState, artboardId: ArtboardId) {
+  const layerId = selection.layerIds[0];
+  const index = createDocumentReadIndex(document);
+  const layerInfo = layerId ? index.layerInfoById.get(layerId) : undefined;
+  if (!layerInfo || layerInfo.artboardId !== artboardId || layerInfo.layer.type === "group") {
+    throw new Error("Select one image or raster layer before placing generated output.");
+  }
+  const asset = index.assetById.get(layerInfo.layer.assetId);
+  if (!asset) throw new Error("The selected layer is missing its source image.");
+  return { layer: layerInfo.layer, asset };
+}
+
+function scaleInpaintPlacement(bundle: InpaintBundle, intrinsicSize: Size): Transform {
+  return {
+    position: { ...bundle.placement.transform.position },
+    scale: {
+      x: bundle.placement.transform.scale.x * bundle.width / Math.max(1, intrinsicSize.w),
+      y: bundle.placement.transform.scale.y * bundle.height / Math.max(1, intrinsicSize.h),
+    },
+    rotation: bundle.placement.transform.rotation,
+  };
+}

operations/generation/preconditions.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import type { ImageDocument } from "@core/document";
+import { initialToolState } from "@editor/tools";
+import { checkGenerationPreconditions } from "./preconditions";
+
+describe("generation preconditions", () => {
+  test("allows text-to-image with a prompt and artboard but no layer selection", () => {
+    expect(checkGenerationPreconditions(document(), { artboardId: "artboard", layerIds: [] }, settings("text-to-image"))).toEqual({ ready: true });
+  });
+
+  test("requires exactly one source layer for image-to-image and outpaint", () => {
+    const selection = { artboardId: "artboard", layerIds: [] };
+    expect(checkGenerationPreconditions(document(), selection, settings("image-to-image"))).toEqual({ ready: false, message: "Select exactly one image or raster layer for image-to-image generation." });
+    expect(checkGenerationPreconditions(document(), selection, settings("outpaint"))).toEqual({ ready: false, message: "Select exactly one image or raster layer to outpaint." });
+  });
+
+  test("requires an enabled mask for inpaint", () => {
+    expect(checkGenerationPreconditions(document(), selected(), settings("inpaint"))).toEqual({ ready: false, message: "Add and enable a layer mask on the selected image before inpainting." });
+  });
+
+  test("allows inpaint when the selected source has an aligned enabled mask", () => {
+    expect(checkGenerationPreconditions(document(true), selected(), settings("inpaint"))).toEqual({ ready: true });
+  });
+
+  test("explains prompt and outpaint-padding requirements", () => {
+    expect(checkGenerationPreconditions(document(), selected(), { ...settings("image-to-image"), prompt: "  " })).toEqual({ ready: false, message: "Enter a prompt to generate an image." });
+    expect(checkGenerationPreconditions(document(), selected(), { ...settings("outpaint"), outpaint: { left: 0, top: 0, right: 0, bottom: 0, feathering: 0 } })).toEqual({ ready: false, message: "Add outpaint padding on at least one side." });
+  });
+});
+
+function settings(mode: "text-to-image" | "image-to-image" | "inpaint" | "outpaint") {
+  return { ...initialToolState.generate, mode, prompt: "A lighthouse" };
+}
+
+function selected() {
+  return { artboardId: "artboard" as const, layerIds: ["source"] };
+}
+
+function document(masked = false): ImageDocument {
+  const transform = { position: { x: 0, y: 0 }, scale: { x: 1, y: 1 }, rotation: 0 };
+  return {
+    id: "document",
+    name: "Test",
+    version: 1,
+    assets: [
+      { id: "source-asset", name: "Source", mimeType: "image/png", source: "source", intrinsicSize: { w: 100, h: 100 } },
+      { id: "mask-asset", name: "Mask", mimeType: "image/png", source: "mask", intrinsicSize: { w: 100, h: 100 } },
+    ],
+    artboards: [{
+      id: "artboard",
+      name: "Artboard",
+      bounds: { x: 0, y: 0, w: 100, h: 100 },
+      backgroundColor: "transparent",
+      visible: true,
+      locked: false,
+      layers: [
+        { id: "mask", type: "raster", name: "Mask", visible: true, locked: false, opacity: 1, assetId: "mask-asset", transform },
+        {
+          id: "source",
+          type: "raster",
+          name: "Source",
+          visible: true,
+          locked: false,
+          opacity: 1,
+          assetId: "source-asset",
+          transform,
+          layerMask: masked ? { kind: "raster", maskLayerId: "mask", enabled: true, inverted: false } : undefined,
+        },
+      ],
+    }],
+  };
+}

operations/generation/preconditions.ts

@@ -0,0 +1,78 @@
+import type { ImageDocument } from "@core/document";
+import { getLayerMask } from "@core/layer-mask-utils";
+import { createDocumentReadIndex, resolveIndexedLayerBounds } from "@editor/document-indexes";
+import type { SelectionState } from "@editor/state";
+import type { GenerateSettings } from "@editor/tools";
+
+export type GenerationPrecondition =
+  | { ready: true }
+  | { ready: false; message: string };
+
+export function checkGenerationPreconditions(
+  document: ImageDocument,
+  selection: SelectionState,
+  settings: GenerateSettings,
+): GenerationPrecondition {
+  if (!settings.prompt.trim()) return missing("Enter a prompt to generate an image.");
+
+  const artboard = selection.artboardId
+    ? document.artboards.find((candidate) => candidate.id === selection.artboardId)
+    : document.artboards[0];
+  if (!artboard) return missing("Create an artboard before generating an image.");
+  if (settings.mode === "text-to-image") return { ready: true };
+
+  if (selection.layerIds.length !== 1 || !selection.layerIds[0]) {
+    return missing(modeSelectionMessage(settings.mode));
+  }
+
+  const index = createDocumentReadIndex(document);
+  const layerInfo = index.layerInfoById.get(selection.layerIds[0]);
+  if (!layerInfo || layerInfo.artboardId !== artboard.id || layerInfo.layer.type === "group") {
+    return missing(modeSelectionMessage(settings.mode));
+  }
+
+  const asset = index.assetById.get(layerInfo.layer.assetId);
+  if (!asset) return missing("The selected layer is missing its source image.");
+  if (asset.intrinsicSize.w <= 0 || asset.intrinsicSize.h <= 0) return missing("The selected image has an invalid size.");
+
+  if (settings.mode === "outpaint") {
+    const padding = settings.outpaint;
+    if (padding.left + padding.top + padding.right + padding.bottom <= 0) {
+      return missing("Add outpaint padding on at least one side.");
+    }
+  }
+
+  if (settings.mode !== "inpaint") return { ready: true };
+
+  const layerMask = getLayerMask(layerInfo.layer);
+  if (!layerMask?.enabled) return missing("Add and enable a layer mask on the selected image before inpainting.");
+  const maskLayer = index.layerById.get(layerMask.maskLayerId);
+  if (!maskLayer || maskLayer.type === "group") return missing("The selected layer mask is missing.");
+  const maskAsset = index.assetById.get(maskLayer.assetId);
+  if (!maskAsset) return missing("The selected layer mask is missing its image data.");
+  if (Math.round(asset.intrinsicSize.w) !== Math.round(maskAsset.intrinsicSize.w) || Math.round(asset.intrinsicSize.h) !== Math.round(maskAsset.intrinsicSize.h)) {
+    return missing("The selected layer and mask image sizes must match.");
+  }
+
+  const layerBounds = resolveIndexedLayerBounds(index, layerInfo.layer);
+  const maskBounds = resolveIndexedLayerBounds(index, maskLayer);
+  if (!layerBounds || !maskBounds || !rectsAligned(layerBounds, maskBounds) || Math.abs(layerInfo.layer.transform.rotation - maskLayer.transform.rotation) > 0.001) {
+    return missing("Align the selected layer and its mask before inpainting.");
+  }
+
+  return { ready: true };
+}
+
+function modeSelectionMessage(mode: GenerateSettings["mode"]): string {
+  if (mode === "image-to-image") return "Select exactly one image or raster layer for image-to-image generation.";
+  if (mode === "inpaint") return "Select exactly one masked image or raster layer to inpaint.";
+  return "Select exactly one image or raster layer to outpaint.";
+}
+
+function missing(message: string): GenerationPrecondition {
+  return { ready: false, message };
+}
+
+function rectsAligned(a: { x: number; y: number; w: number; h: number }, b: { x: number; y: number; w: number; h: number }): boolean {
+  return Math.abs(a.x - b.x) <= 0.5 && Math.abs(a.y - b.y) <= 0.5 && Math.abs(a.w - b.w) <= 0.5 && Math.abs(a.h - b.h) <= 0.5;
+}

operations/generation/runGenerate.ts

@@ -1,6 +1,5 @@
 import { commandIds } from "@commands/ids";
 import type { ImageDocument } from "@core/document";
-import type { Transform } from "@core/geometry";
 import type { Layer } from "@core/layer";
 import { getLayerMask } from "@core/layer-mask-utils";
 import type { AppStore } from "@editor/store";
@@ -9,6 +8,8 @@ import type { GenerateSettings } from "@editor/tools";
 import { buildInpaintBundle, type InpaintBundle } from "./inpaintPrep";
 import { imageSourceToDataUrl, loadImageSize } from "@platform/browser/imageRaster";
 import { requestGeneration } from "@platform/comfy/generationClient";
+import { checkGenerationPreconditions } from "./preconditions";
+import { resolveGeneratedOutputPlacement } from "./outputPlacement";
 
 export async function runGenerate(options: {
   document: ImageDocument;
@@ -18,8 +19,10 @@ export async function runGenerate(options: {
   dispatch: AppStore["dispatch"];
 }) {
   const { document, selection, settings, dispatch } = options;
+  const precondition = checkGenerationPreconditions(document, selection, settings);
+  if (!precondition.ready) throw new Error(precondition.message);
   const artboard = selection.artboardId ? document.artboards.find((candidate) => candidate.id === selection.artboardId) : document.artboards[0];
-  if (!artboard) return;
+  if (!artboard) throw new Error("Create an artboard before generating an image.");
 
   const target = resolveSelectedImage(document, selection);
   const inpaintBundle = settings.mode === "inpaint" ? await buildInpaintBundle(document, selection, settings) : undefined;
@@ -38,12 +41,7 @@ export async function runGenerate(options: {
     inpaintBundle,
   });
   const intrinsicSize = await loadImageSize(generated.source);
-  const targetArtboardId = inpaintBundle?.placement.artboardId ?? artboard.id;
+  const placement = resolveGeneratedOutputPlacement({ document, selection, settings, intrinsicSize, inpaintBundle });
-  const placement = {
-    artboardId: targetArtboardId,
-    layerName: inpaintBundle?.placement.layerName ?? "Generated image",
-    transform: generatedLayerTransform(inpaintBundle, intrinsicSize),
-  };
 
   dispatch(commandIds.generationAddCandidate, {
     candidate: createGenerationCandidate({
@@ -199,18 +197,6 @@ function resolveInpaintRequest(inpaintBundle: InpaintBundle | undefined, inpaint
   return settings.inpaint;
 }
 
-function generatedLayerTransform(inpaintBundle: InpaintBundle | undefined, intrinsicSize: { w: number; h: number }): Transform {
-  if (!inpaintBundle) return { position: { x: 0, y: 0 }, scale: { x: 1, y: 1 }, rotation: 0 };
-  return {
-    position: { ...inpaintBundle.placement.transform.position },
-    scale: {
-      x: (inpaintBundle.placement.transform.scale.x * inpaintBundle.width) / Math.max(1, intrinsicSize.w),
-      y: (inpaintBundle.placement.transform.scale.y * inpaintBundle.height) / Math.max(1, intrinsicSize.h),
-    },
-    rotation: inpaintBundle.placement.transform.rotation,
-  };
-}
-
 function resolveSeed(seed: number): number {
   return seed < 0 ? Math.floor(Math.random() * 2 ** 32) : Math.round(seed);
 }

operations/generation/workflow.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import { documentCommands } from "@commands/document";
+import { generationCommands } from "@commands/generation";
+import { commandIds } from "@commands/ids";
+import { createCommandRegistry } from "@commands/registry";
+import { toolCommands } from "@commands/tool";
+import { createInitialAppState } from "@editor/initial-state";
+import { createAppStore } from "@editor/store";
+import { initialToolState } from "@editor/tools";
+import type { GenerationCandidate } from "@editor/state";
+import { createGenerationWorkflow, type GenerationWorkflowDependencies } from "./workflow";
+
+describe("generation workflow", () => {
+  test("reads canonical application state when generation starts", async () => {
+    const app = createTestApp();
+    let prompt = "";
+    const workflow = createGenerationWorkflow(app.store, dependencies({
+      runGenerate: async (options) => { prompt = options.settings.prompt; },
+    }));
+
+    app.store.dispatch(commandIds.toolSetGenerateSettings, { prompt: "Latest prompt" });
+    await workflow.generate();
+
+    expect(prompt).toBe("Latest prompt");
+    expect(app.store.getState().editor.generation.jobs[0]?.status).toBe("succeeded");
+  });
+
+  test("uses one acceptance path to add a candidate as a layer", () => {
+    const app = createTestApp();
+    const artboardId = app.store.getState().document.artboards[0]?.id;
+    if (!artboardId) throw new Error("Expected default artboard");
+    app.store.dispatch(commandIds.generationAddCandidate, { candidate: candidate(artboardId) });
+    const ids = ["asset-new", "layer-new"];
+    const workflow = createGenerationWorkflow(app.store, dependencies({ createId: () => ids.shift() ?? "unused" }));
+
+    workflow.applyCandidateAsLayer("candidate");
+
+    expect(app.store.getState().document.assets.some((asset) => asset.id === "asset-new")).toBe(true);
+    expect(app.store.getState().document.artboards[0]?.layers.some((layer) => layer.id === "layer-new")).toBe(true);
+    expect(app.store.getState().editor.generation.candidates).toHaveLength(0);
+  });
+});
+
+function dependencies(overrides: Partial<GenerationWorkflowDependencies>): GenerationWorkflowDependencies {
+  return {
+    runGenerate: async () => undefined,
+    runGenerateFromCandidate: async () => undefined,
+    createMaskedPixelReplacementSource: async () => "replacement",
+    createRefinementMask: async () => "mask",
+    loadGenerationResources: async () => undefined,
+    createId: () => crypto.randomUUID(),
+    ...overrides,
+  };
+}
+
+function candidate(artboardId: string): GenerationCandidate {
+  return {
+    id: "candidate",
+    source: "generated",
+    mimeType: "image/png",
+    intrinsicSize: { w: 64, h: 64 },
+    mode: "text-to-image",
+    settings: initialToolState.generate,
+    seed: 1,
+    width: 64,
+    height: 64,
+    placement: {
+      artboardId,
+      layerName: "Generated",
+      transform: { position: { x: 0, y: 0 }, scale: { x: 1, y: 1 }, rotation: 0 },
+    },
+  };
+}
+
+function createTestApp() {
+  const state = createInitialAppState("Test");
+  state.document.artboards.push({
+    id: "artboard",
+    name: "Artboard",
+    bounds: { x: 0, y: 0, w: 100, h: 100 },
+    backgroundColor: "transparent",
+    visible: true,
+    locked: false,
+    layers: [],
+  });
+  const registry = createCommandRegistry([...documentCommands, ...toolCommands, ...generationCommands]);
+  return { store: createAppStore(state, registry) };
+}

operations/generation/workflow.ts

@@ -0,0 +1,125 @@
+import { commandIds } from "@commands/ids";
+import type { GenerationCandidate, GenerationJobKind } from "@editor/state";
+import type { AppStore } from "@editor/store";
+import type { GenerateSettings } from "@editor/tools";
+import { createRefinementMask } from "@operations/masks/rasterActions";
+import { createMaskedPixelReplacementSource } from "./candidateActions";
+import { runGenerationJob } from "./generationJob";
+import { loadGenerationResources } from "./loadResources";
+import { runGenerate, runGenerateFromCandidate } from "./runGenerate";
+import { checkGenerationPreconditions } from "./preconditions";
+
+export type GenerationWorkflow = ReturnType<typeof createGenerationWorkflow>;
+
+export type GenerationWorkflowDependencies = {
+  runGenerate: typeof runGenerate;
+  runGenerateFromCandidate: typeof runGenerateFromCandidate;
+  createMaskedPixelReplacementSource: typeof createMaskedPixelReplacementSource;
+  createRefinementMask: typeof createRefinementMask;
+  loadGenerationResources: typeof loadGenerationResources;
+  createId(): string;
+};
+
+const defaultDependencies: GenerationWorkflowDependencies = {
+  runGenerate,
+  runGenerateFromCandidate,
+  createMaskedPixelReplacementSource,
+  createRefinementMask,
+  loadGenerationResources,
+  createId: () => crypto.randomUUID(),
+};
+
+export function createGenerationWorkflow(store: AppStore, dependencies: GenerationWorkflowDependencies = defaultDependencies) {
+  const job = (kind: GenerationJobKind, label: string, task: () => Promise<void>) =>
+    runGenerationJob({ kind, label, dispatch: store.dispatch, task });
+
+  return {
+    precondition: () => {
+      const state = store.getState();
+      return checkGenerationPreconditions(state.document, state.editor.selection, state.editor.tools.generate);
+    },
+
+    loadResources: () => dependencies.loadGenerationResources(store),
+
+    generate: () => job("generate", "Generating", async () => {
+      const state = store.getState();
+      await dependencies.runGenerate({
+        document: state.document,
+        selection: state.editor.selection,
+        viewport: state.editor.viewport,
+        settings: state.editor.tools.generate,
+        dispatch: store.dispatch,
+      });
+    }),
+
+    regenerate: (candidateId: string, settings?: GenerateSettings, label = "Regenerate") =>
+      job("regenerate", label, async () => {
+        const candidate = findCandidate(store, candidateId);
+        const nextSettings = settings ?? candidate.settings;
+        store.dispatch(commandIds.toolSetGenerateSettings, nextSettings);
+        await dependencies.runGenerateFromCandidate({ candidate, settings: nextSettings, dispatch: store.dispatch });
+      }),
+
+    applyCandidateAsLayer: (candidateId: string) => {
+      store.dispatch(commandIds.generationApplyCandidateAsLayer, {
+        candidateId,
+        assetId: dependencies.createId(),
+        layerId: dependencies.createId(),
+      });
+    },
+
+    applyCandidateAsRefinementLayer: (candidateId: string) =>
+      job("refine", "Adding refinement mask", async () => {
+        const candidate = findCandidate(store, candidateId);
+        const layerId = dependencies.createId();
+        const maskAssetId = dependencies.createId();
+        const width = Math.max(1, Math.round(candidate.intrinsicSize.w));
+        const height = Math.max(1, Math.round(candidate.intrinsicSize.h));
+        const source = await dependencies.createRefinementMask(width, height);
+
+        store.dispatch(commandIds.generationApplyCandidateAsLayer, {
+          candidateId,
+          assetId: dependencies.createId(),
+          layerId,
+        });
+        store.dispatch(commandIds.documentAddLayerMask, {
+          layerId,
+          asset: {
+            id: maskAssetId,
+            name: `${candidate.placement.layerName} refinement mask`,
+            mimeType: "image/png",
+            source,
+            intrinsicSize: { w: width, h: height },
+          },
+          maskLayer: {
+            id: dependencies.createId(),
+            type: "raster",
+            name: `${candidate.placement.layerName} refinement mask`,
+            visible: true,
+            locked: false,
+            opacity: 1,
+            assetId: maskAssetId,
+            transform: {
+              position: { ...candidate.placement.transform.position },
+              scale: { ...candidate.placement.transform.scale },
+              rotation: candidate.placement.transform.rotation,
+            },
+          },
+        });
+        store.dispatch(commandIds.toolSetActive, { tool: "eraser" });
+      }),
+
+    replaceCandidatePixels: (candidateId: string) =>
+      job("replace", "Replacing pixels", async () => {
+        const candidate = findCandidate(store, candidateId);
+        const source = await dependencies.createMaskedPixelReplacementSource(store.getState().document, candidate);
+        store.dispatch(commandIds.generationReplaceCandidatePixels, { candidateId, source, mimeType: "image/png" });
+      }),
+  };
+}
+
+function findCandidate(store: AppStore, candidateId: string): GenerationCandidate {
+  const candidate = store.getState().editor.generation.candidates.find((item) => item.id === candidateId);
+  if (!candidate) throw new Error("This generation candidate is no longer available.");
+  return candidate;
+}

operations/project/format.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import type { ImageDocument } from "@core/document";
+import { CURRENT_PROJECT_VERSION, parseProject, projectFileName, serializeProject } from "./format";
+
+describe("project format", () => {
+  test("round-trips a versioned project with embedded assets", () => {
+    const document = projectDocument();
+    const result = parseProject(serializeProject(document, "2026-07-10T12:00:00.000Z"));
+
+    expect(result.version).toBe(CURRENT_PROJECT_VERSION);
+    expect(result.savedAt).toBe("2026-07-10T12:00:00.000Z");
+    expect(result.document).toEqual(document);
+  });
+
+  test("migrates a legacy bare document", () => {
+    const result = parseProject(JSON.stringify(projectDocument()));
+    expect(result.version).toBe(1);
+    expect(result.savedAt).toBe("1970-01-01T00:00:00.000Z");
+  });
+
+  test("rejects unknown versions and invalid JSON", () => {
+    expect(() => parseProject("not json")).toThrow("not valid JSON");
+    expect(() => parseProject(JSON.stringify({ format: "image-studio-project", version: 99, savedAt: "now", document: projectDocument() }))).toThrow("Unsupported project version");
+  });
+
+  test("enforces project-owned embedded assets and valid references", () => {
+    const externalAsset = projectDocument();
+    externalAsset.assets[0]!.source = "blob:https://example.test/asset";
+    expect(() => serializeProject(externalAsset)).toThrow("not embedded");
+
+    const missingAsset = projectDocument();
+    missingAsset.assets = [];
+    expect(() => serializeProject(missingAsset)).toThrow("references missing asset");
+  });
+
+  test("creates safe project file names", () => {
+    expect(projectFileName("  Summer / Study  ")).toBe("Summer-Study.image-studio.json");
+    expect(projectFileName("***")).toBe("untitled.image-studio.json");
+  });
+});
+
+function projectDocument(): ImageDocument {
+  return {
+    id: "document-1",
+    name: "Test Project",
+    version: 1,
+    assets: [{ id: "asset-1", name: "pixels.png", mimeType: "image/png", source: "data:image/png;base64,AA==", intrinsicSize: { w: 10, h: 20 } }],
+    artboards: [{
+      id: "artboard-1",
+      name: "Board",
+      bounds: { x: 0, y: 0, w: 100, h: 100 },
+      backgroundColor: "transparent",
+      visible: true,
+      locked: false,
+      layers: [{ id: "layer-1", type: "image", name: "Pixels", visible: true, locked: false, opacity: 1, assetId: "asset-1", transform: { position: { x: 0, y: 0 }, scale: { x: 1, y: 1 }, rotation: 0 } }],
+    }],
+  };
+}

operations/project/format.ts

@@ -0,0 +1,150 @@
+import type { ImageDocument } from "@core/document";
+import type { Layer } from "@core/layer";
+
+export const PROJECT_FORMAT = "image-studio-project";
+export const CURRENT_PROJECT_VERSION = 1;
+
+export type ProjectFile = {
+  format: typeof PROJECT_FORMAT;
+  version: typeof CURRENT_PROJECT_VERSION;
+  savedAt: string;
+  document: ImageDocument;
+};
+
+export function serializeProject(document: ImageDocument, savedAt = new Date().toISOString()): string {
+  assertDocumentAssetOwnership(document);
+  return JSON.stringify({ format: PROJECT_FORMAT, version: CURRENT_PROJECT_VERSION, savedAt, document } satisfies ProjectFile);
+}
+
+export function parseProject(source: string): ProjectFile {
+  let value: unknown;
+  try {
+    value = JSON.parse(source);
+  } catch {
+    throw new Error("The selected file is not valid JSON.");
+  }
+
+  const migrated = migrateProject(value);
+  assertImageDocument(migrated.document);
+  assertDocumentAssetOwnership(migrated.document);
+  return migrated;
+}
+
+export function projectFileName(documentName: string): string {
+  const base = documentName.trim().replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "untitled";
+  return `${base}.image-studio.json`;
+}
+
+function migrateProject(value: unknown): ProjectFile {
+  if (!isRecord(value)) throw new Error("The project file must contain an object.");
+
+  if (value.format === PROJECT_FORMAT) {
+    if (value.version !== CURRENT_PROJECT_VERSION) {
+      throw new Error(`Unsupported project version: ${String(value.version)}.`);
+    }
+    if (typeof value.savedAt !== "string") throw new Error("The project is missing its save timestamp.");
+    return value as ProjectFile;
+  }
+
+  // Legacy exports stored ImageDocument directly. Loading upgrades them to v1.
+  if (looksLikeDocument(value)) {
+    return {
+      format: PROJECT_FORMAT,
+      version: CURRENT_PROJECT_VERSION,
+      savedAt: new Date(0).toISOString(),
+      document: value as ImageDocument,
+    };
+  }
+
+  throw new Error("This is not an Image Studio project file.");
+}
+
+function assertImageDocument(value: unknown): asserts value is ImageDocument {
+  if (!isRecord(value) || typeof value.id !== "string" || typeof value.name !== "string" || typeof value.version !== "number") {
+    throw new Error("The project contains an invalid document.");
+  }
+  if (!Array.isArray(value.artboards) || !Array.isArray(value.assets)) throw new Error("The project document is incomplete.");
+
+  for (const asset of value.assets) {
+    if (!isRecord(asset) || typeof asset.id !== "string" || typeof asset.name !== "string" || typeof asset.mimeType !== "string" || typeof asset.source !== "string" || !isSize(asset.intrinsicSize)) {
+      throw new Error("The project contains an invalid asset.");
+    }
+  }
+  for (const artboard of value.artboards) {
+    if (!isRecord(artboard) || typeof artboard.id !== "string" || typeof artboard.name !== "string" || !isRect(artboard.bounds) || !Array.isArray(artboard.layers)) {
+      throw new Error("The project contains an invalid artboard.");
+    }
+    assertLayers(artboard.layers);
+  }
+}
+
+export function assertDocumentAssetOwnership(document: ImageDocument): void {
+  const assetIds = new Set<string>();
+  for (const asset of document.assets) {
+    if (assetIds.has(asset.id)) throw new Error(`Duplicate asset id: ${asset.id}.`);
+    assetIds.add(asset.id);
+    if (!isOwnedAssetSource(asset.source)) throw new Error(`Asset ${asset.name} is not embedded in the project.`);
+  }
+
+  const layerIds = new Set<string>();
+  for (const artboard of document.artboards) {
+    walkLayers(artboard.layers, (layer) => {
+      if (layerIds.has(layer.id)) throw new Error(`Duplicate layer id: ${layer.id}.`);
+      layerIds.add(layer.id);
+      if ((layer.type === "image" || layer.type === "raster") && !assetIds.has(layer.assetId)) {
+        throw new Error(`Layer ${layer.name} references missing asset ${layer.assetId}.`);
+      }
+    });
+  }
+}
+
+function isOwnedAssetSource(source: string): boolean {
+  return source.startsWith("data:");
+}
+
+function assertLayers(value: unknown[]): asserts value is Layer[] {
+  for (const layer of value) {
+    if (!isRecord(layer) || typeof layer.id !== "string" || typeof layer.name !== "string" || typeof layer.type !== "string" || typeof layer.visible !== "boolean" || typeof layer.locked !== "boolean" || typeof layer.opacity !== "number" || !isTransform(layer.transform)) {
+      throw new Error("The project contains an invalid layer.");
+    }
+    if (layer.type === "group") {
+      if (!Array.isArray(layer.children)) throw new Error("A project group is missing its children.");
+      assertLayers(layer.children);
+    } else if ((layer.type === "image" || layer.type === "raster") && typeof layer.assetId !== "string") {
+      throw new Error("A project layer is missing its asset reference.");
+    } else if (layer.type !== "image" && layer.type !== "raster") {
+      throw new Error(`Unsupported layer type: ${layer.type}.`);
+    }
+  }
+}
+
+function walkLayers(layers: Layer[], visit: (layer: Layer) => void): void {
+  for (const layer of layers) {
+    visit(layer);
+    if (layer.type === "group") walkLayers(layer.children, visit);
+  }
+}
+
+function looksLikeDocument(value: Record<string, unknown>): boolean {
+  return typeof value.id === "string" && Array.isArray(value.artboards) && Array.isArray(value.assets);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isSize(value: unknown): boolean {
+  return isRecord(value) && isFiniteNumber(value.w) && isFiniteNumber(value.h) && value.w >= 0 && value.h >= 0;
+}
+
+function isRect(value: unknown): boolean {
+  return isRecord(value) && isFiniteNumber(value.x) && isFiniteNumber(value.y) && isFiniteNumber(value.w) && isFiniteNumber(value.h);
+}
+
+function isTransform(value: unknown): boolean {
+  return isRecord(value) && isRecord(value.position) && isFiniteNumber(value.position.x) && isFiniteNumber(value.position.y) && isRecord(value.scale) && isFiniteNumber(value.scale.x) && isFiniteNumber(value.scale.y) && isFiniteNumber(value.rotation);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}

operations/project/lifecycle.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+import { commandIds } from "@commands/ids";
+import { documentAddArtboardCommand, documentRenameArtboardCommand } from "@commands/document";
+import { projectOpenCommand } from "@commands/project";
+import { createCommandRegistry } from "@commands/registry";
+import { createInitialAppState } from "@editor/initial-state";
+import { createAppStore } from "@editor/store";
+import type { RecoveryStorage } from "@platform/projectStorage";
+import { createProjectLifecycle, RECOVERY_STORAGE_KEY } from "./lifecycle";
+import { parseProject, serializeProject } from "./format";
+
+describe("project lifecycle", () => {
+  test("autosaves document changes after the debounce", async () => {
+    const app = createTestApp();
+    const storage = memoryStorage();
+    let scheduled: (() => void) | undefined;
+    const lifecycle = createProjectLifecycle({
+      store: app.store,
+      storage,
+      schedule(callback) {
+        scheduled = callback;
+        return 1 as unknown as ReturnType<typeof setTimeout>;
+      },
+      cancel() {},
+    });
+
+    const artboardId = app.store.getState().document.artboards[0]!.id;
+    app.store.dispatch(commandIds.documentRenameArtboard, { id: artboardId, name: "Recovered board" });
+    expect(await storage.read(RECOVERY_STORAGE_KEY)).toBeNull();
+    scheduled?.();
+    await Promise.resolve();
+    expect(parseProject((await storage.read(RECOVERY_STORAGE_KEY))!).document.artboards[0]!.name).toBe("Recovered board");
+    lifecycle.dispose();
+  });
+
+  test("recovers a document through the project command and clears history", async () => {
+    const app = createTestApp();
+    const recovered = createTestApp("Recovered").store.getState().document;
+    const storage = memoryStorage([[RECOVERY_STORAGE_KEY, serializeProject(recovered)]]);
+    const lifecycle = createProjectLifecycle({ store: app.store, storage });
+
+    expect((await lifecycle.recover())?.document.name).toBe("Recovered");
+    expect(app.store.getState().document.name).toBe("Recovered");
+    expect(app.store.getState().history).toEqual({ past: [], future: [] });
+    lifecycle.dispose();
+  });
+
+  test("discards corrupted recovery and clears recovery after explicit save", async () => {
+    const app = createTestApp();
+    const storage = memoryStorage([[RECOVERY_STORAGE_KEY, "broken"]]);
+    const lifecycle = createProjectLifecycle({ store: app.store, storage });
+
+    expect(await lifecycle.recover()).toBeUndefined();
+    expect(await storage.read(RECOVERY_STORAGE_KEY)).toBeNull();
+    await storage.write(RECOVERY_STORAGE_KEY, lifecycle.snapshot());
+    await lifecycle.markSaved();
+    expect(await storage.read(RECOVERY_STORAGE_KEY)).toBeNull();
+    lifecycle.dispose();
+  });
+
+  test("explicit save cancels a pending recovery write", async () => {
+    const app = createTestApp();
+    const storage = memoryStorage();
+    let scheduled: (() => void) | undefined;
+    let cancelled = false;
+    const lifecycle = createProjectLifecycle({
+      store: app.store,
+      storage,
+      schedule(callback) {
+        scheduled = callback;
+        return 1;
+      },
+      cancel() { cancelled = true; },
+    });
+
+    const artboardId = app.store.getState().document.artboards[0]!.id;
+    app.store.dispatch(commandIds.documentRenameArtboard, { id: artboardId, name: "Saved" });
+    await lifecycle.markSaved();
+    expect(cancelled).toBe(true);
+    expect(await storage.read(RECOVERY_STORAGE_KEY)).toBeNull();
+    expect(scheduled).toBeDefined();
+    lifecycle.dispose();
+  });
+});
+
+function memoryStorage(entries: [string, string][] = []): RecoveryStorage {
+  const values = new Map(entries);
+  return {
+    read: async (key) => values.get(key) ?? null,
+    write: async (key, value) => { values.set(key, value); },
+    remove: async (key) => { values.delete(key); },
+  };
+}
+
+function createTestApp(name = "Test") {
+  const store = createAppStore(createInitialAppState(name), createCommandRegistry([projectOpenCommand, documentAddArtboardCommand, documentRenameArtboardCommand]));
+  store.dispatch(commandIds.documentAddArtboard, { id: `${name}-artboard`, name: "Board", bounds: { x: 0, y: 0, w: 100, h: 100 } });
+  return { store };
+}

operations/project/lifecycle.ts

@@ -0,0 +1,86 @@
+import { commandIds } from "@commands/ids";
+import type { AppStore } from "@editor/store";
+import type { ProjectFile } from "./format";
+import { parseProject, serializeProject } from "./format";
+import type { RecoveryStorage } from "@platform/projectStorage";
+
+export const RECOVERY_STORAGE_KEY = "image-studio.recovery.v1";
+
+type TimerHandle = number | ReturnType<typeof setTimeout>;
+
+export type ProjectLifecycle = {
+  recover(): Promise<ProjectFile | undefined>;
+  open(source: string): Promise<ProjectFile>;
+  snapshot(): string;
+  markSaved(): Promise<void>;
+  dispose(): void;
+};
+
+export function createProjectLifecycle(options: {
+  store: AppStore;
+  storage: RecoveryStorage;
+  debounceMs?: number;
+  schedule?: (callback: () => void, delay: number) => TimerHandle;
+  cancel?: (handle: TimerHandle) => void;
+}): ProjectLifecycle {
+  const debounceMs = options.debounceMs ?? 750;
+  const schedule = options.schedule ?? setTimeout;
+  const cancel = options.cancel ?? ((handle: TimerHandle) => clearTimeout(handle));
+  let observedDocument = options.store.getState().document;
+  let pending: TimerHandle | undefined;
+  let disposed = false;
+
+  const cancelPending = () => {
+    if (pending === undefined) return;
+    cancel(pending);
+    pending = undefined;
+  };
+
+  const unsubscribe = options.store.subscribe((state) => {
+    if (state.document === observedDocument) return;
+    observedDocument = state.document;
+    cancelPending();
+    pending = schedule(() => {
+      pending = undefined;
+      void options.storage.write(RECOVERY_STORAGE_KEY, serializeProject(options.store.getState().document)).catch(() => undefined);
+    }, debounceMs);
+  });
+
+  const replace = (project: ProjectFile) => {
+    options.store.dispatch(commandIds.projectOpen, { document: project.document });
+    cancelPending();
+    observedDocument = options.store.getState().document;
+    return project;
+  };
+
+  return {
+    async recover() {
+      const source = await options.storage.read(RECOVERY_STORAGE_KEY);
+      if (!source || disposed) return undefined;
+      try {
+        return replace(parseProject(source));
+      } catch {
+        await options.storage.remove(RECOVERY_STORAGE_KEY);
+        return undefined;
+      }
+    },
+    async open(source) {
+      const project = replace(parseProject(source));
+      await options.storage.remove(RECOVERY_STORAGE_KEY);
+      return project;
+    },
+    snapshot() {
+      return serializeProject(options.store.getState().document);
+    },
+    async markSaved() {
+      cancelPending();
+      observedDocument = options.store.getState().document;
+      await options.storage.remove(RECOVERY_STORAGE_KEY);
+    },
+    dispose() {
+      disposed = true;
+      unsubscribe();
+      cancelPending();
+    },
+  };
+}

platform/browser/projectFiles.ts

@@ -0,0 +1,55 @@
+import type { RecoveryStorage } from "@platform/projectStorage";
+
+export const browserRecoveryStorage: RecoveryStorage = {
+  async read(key) {
+    return request<string | undefined>("readonly", (store) => store.get(key)).then((value) => value ?? null);
+  },
+  async write(key, value) {
+    await request("readwrite", (store) => store.put(value, key));
+  },
+  async remove(key) {
+    await request("readwrite", (store) => store.delete(key));
+  },
+};
+
+const RECOVERY_DATABASE = "image-studio";
+const RECOVERY_STORE = "recovery";
+
+function openRecoveryDatabase(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const open = indexedDB.open(RECOVERY_DATABASE, 1);
+    open.onupgradeneeded = () => {
+      if (!open.result.objectStoreNames.contains(RECOVERY_STORE)) open.result.createObjectStore(RECOVERY_STORE);
+    };
+    open.onsuccess = () => resolve(open.result);
+    open.onerror = () => reject(open.error ?? new Error("Could not open recovery storage."));
+  });
+}
+
+async function request<T>(mode: IDBTransactionMode, operation: (store: IDBObjectStore) => IDBRequest<T>): Promise<T> {
+  const database = await openRecoveryDatabase();
+  return new Promise((resolve, reject) => {
+    const transaction = database.transaction(RECOVERY_STORE, mode);
+    const databaseRequest = operation(transaction.objectStore(RECOVERY_STORE));
+    databaseRequest.onsuccess = () => resolve(databaseRequest.result);
+    databaseRequest.onerror = () => reject(databaseRequest.error ?? new Error("Recovery storage operation failed."));
+    transaction.oncomplete = () => database.close();
+    transaction.onerror = () => {
+      database.close();
+      reject(transaction.error ?? new Error("Recovery storage transaction failed."));
+    };
+  });
+}
+
+export function downloadProjectFile(source: string, fileName: string): void {
+  const url = URL.createObjectURL(new Blob([source], { type: "application/json" }));
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = fileName;
+  link.click();
+  URL.revokeObjectURL(url);
+}
+
+export function readProjectFile(file: File): Promise<string> {
+  return file.text();
+}

platform/projectStorage.ts

@@ -0,0 +1,5 @@
+export type RecoveryStorage = {
+  read(key: string): Promise<string | null>;
+  write(key: string, value: string): Promise<void>;
+  remove(key: string): Promise<void>;
+};

view/App.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect } from "react";
-import { DownloadSimple, FolderOpen, Sparkle, Stack } from "@phosphor-icons/react";
+import { DownloadSimple, FloppyDisk, FolderOpen, FolderSimple, Sparkle, Stack } from "@phosphor-icons/react";
 import type { ImageStudioApp } from "@app/app";
 import { commandIds } from "@commands/ids";
 import { BottomControlsIsland } from "./BottomControlsIsland";
@@ -18,7 +18,7 @@ import { shallowEqual, useAppState } from "./useAppState";
 import { downloadArtboardPng } from "@operations/export/downloadArtboard";
 import { useImageImport } from "./useImageImport";
 import { useViewportActivityIsland } from "./useViewportActivityIsland";
-import { loadGenerationResources } from "@operations/generation/loadResources";
+import { useProjectLifecycle } from "./useProjectLifecycle";
 import "./index.css";
 
 export type AppProps = {
@@ -30,14 +30,15 @@ export function App({ app }: AppProps) {
   const { document, selection, viewport, tools, generation, commandPalette, transformSession, maskEdit, workspace } = shellState;
   const viewportActivityIsland = useViewportActivityIsland(viewport);
   const imageImport = useImageImport(app.store);
+  const project = useProjectLifecycle(app.store);
   const transformTarget = transformSession?.target ?? selectedTransformTarget(document, selection);
   const activeArtboard = document.artboards.find((artboard) => artboard.id === selection.artboardId) ?? document.artboards[0];
   const generateOpen = workspace.panel === "generate";
   const layersOpen = workspace.panel === "layers";
 
   useEffect(() => {
-    if (generateOpen) void loadGenerationResources(app.store);
+    if (generateOpen) void app.workflows.generation.loadResources();
-  }, [app.store, generateOpen]);
+  }, [app.workflows.generation, generateOpen]);
 
   const openGenerate = useCallback(() => {
     app.store.dispatch(commandIds.workspaceSetPanel, { panel: "generate" });
@@ -133,6 +134,7 @@ export function App({ app }: AppProps) {
   return (
     <main className="relative h-full overflow-hidden bg-[radial-gradient(circle_at_20%_18%,rgba(148,163,184,0.18),transparent_34%),radial-gradient(circle_at_82%_22%,rgba(71,85,105,0.22),transparent_36%),radial-gradient(circle_at_48%_88%,rgba(30,41,59,0.28),transparent_40%),linear-gradient(135deg,#020617_0%,#0f172a_46%,#111827_100%)] text-foreground">
       {imageImport.input}
+      {project.input}
       <CommandPalette
         state={commandPalette}
         document={document}
@@ -156,6 +158,12 @@ export function App({ app }: AppProps) {
           <button type="button" className={topBarButtonClass()} onClick={imageImport.openFilePicker}>
             <FolderOpen size={24} />
           </button>
+          <button type="button" className={topBarButtonClass()} onClick={project.openFilePicker} title="Open project (Cmd/Ctrl+Shift+O)">
+            <FolderSimple size={24} />
+          </button>
+          <button type="button" className={topBarButtonClass()} onClick={project.save} title="Save project (Cmd/Ctrl+S)">
+            <FloppyDisk size={24} />
+          </button>
           <button type="button" className={topBarButtonClass(generateOpen)} aria-pressed={generateOpen} onClick={toggleGenerate}>
             <Sparkle size={24} weight={generateOpen ? "fill" : "regular"} />
           </button>
@@ -206,6 +214,7 @@ export function App({ app }: AppProps) {
           transformBounds={viewportActivityIsland.visible ? undefined : transformBounds}
           transformTarget={viewportActivityIsland.visible ? undefined : transformTarget}
           dispatch={app.store.dispatch}
+          generationWorkflow={app.workflows.generation}
         />
       </div>
       <div className="absolute bottom-4 left-4 z-10">

view/BottomControlsIsland.tsx

@@ -11,6 +11,7 @@ import { TransformControls } from "./bottom-controls/TransformControls";
 import { ZoomControls } from "./bottom-controls/ZoomControls";
 import type { Rect } from "@core/geometry";
 import type { TransformTarget } from "@editor/transform";
+import type { GenerationWorkflow } from "@operations/generation/workflow";
 export type BottomControlsAction = "pan" | "zoom";
 
 export type BottomControlsIslandProps = {
@@ -31,9 +32,10 @@ export type BottomControlsIslandProps = {
   transformTarget?: TransformTarget;
   brushHint?: string;
   dispatch: AppStore["dispatch"]; 
+  generationWorkflow: GenerationWorkflow;
 };
 
-export function BottomControlsIsland({ document, selection, viewport, visible, action, activeTool, brushSettings, generateSettings, generation, chromaKeySettings, magicWandSettings, editingMask = false, maskViewMode = "composite", transformBounds, transformTarget, brushHint, dispatch }: BottomControlsIslandProps) {
+export function BottomControlsIsland({ document, selection, viewport, visible, action, activeTool, brushSettings, generateSettings, generation, chromaKeySettings, magicWandSettings, editingMask = false, maskViewMode = "composite", transformBounds, transformTarget, brushHint, dispatch, generationWorkflow }: BottomControlsIslandProps) {
   const zoomPercent = Math.round(viewport.zoom * 100);
   const x = Math.round(viewport.center.x);
   const y = Math.round(viewport.center.y);
@@ -46,7 +48,7 @@ export function BottomControlsIsland({ document, selection, viewport, visible, a
       }`}
     >
       {activeTool === "generate" ? (
-        <GenerateActionControls document={document} selection={selection} viewport={viewport} settings={generateSettings} generation={generation} dispatch={dispatch} />
+        <GenerateActionControls settings={generateSettings} generation={generation} dispatch={dispatch} workflow={generationWorkflow} />
       ) : (activeTool === "brush" || activeTool === "eraser") && brushHint ? (
         <BrushHint tool={activeTool} hint={brushHint} />
       ) : activeTool === "brush" || activeTool === "eraser" ? (

view/bottom-controls/GenerateActionControls.tsx

@@ -1,28 +1,24 @@
 import { commandIds } from "@commands/ids";
-import type { ImageDocument } from "@core/document";
+import type { GenerationCandidate, GenerationCompareMode, GenerationState } from "@editor/state";
-import type { GenerationCandidate, GenerationCompareMode, GenerationState, SelectionState, ViewportState } from "@editor/state";
 import type { GenerateSettings } from "@editor/tools";
 import type { AppStore } from "@editor/store";
-import { createMaskedPixelReplacementSource } from "@operations/generation/candidateActions";
+import type { GenerationWorkflow } from "@operations/generation/workflow";
-import { runGenerate, runGenerateFromCandidate } from "@operations/generation/runGenerate";
-import { runGenerationJob } from "@operations/generation/generationJob";
 import { currentGenerationJob, GenerationJobStatus } from "../GenerationJobStatus";
-import { createRefinementMask } from "@operations/masks/rasterActions";
 
 export type GenerateActionControlsProps = {
-  document: ImageDocument;
-  selection: SelectionState;
-  viewport: ViewportState;
   settings: GenerateSettings;
   generation: GenerationState;
   dispatch: AppStore["dispatch"];
+  workflow: GenerationWorkflow;
 };
 
-export function GenerateActionControls({ document, selection, viewport, settings, generation, dispatch }: GenerateActionControlsProps) {
+export function GenerateActionControls({ settings, generation, dispatch, workflow }: GenerateActionControlsProps) {
   const job = currentGenerationJob(generation);
   const busy = job?.status === "running";
   const candidate = selectedCandidate(generation);
-  const canGenerate = Boolean(settings.prompt.trim()) && !busy;
+  const precondition = workflow.precondition();
+  const canGenerate = precondition.ready && !busy;
+  const preconditionMessage = precondition.ready ? undefined : precondition.message;
 
   return (
     <div className="flex max-w-[calc(100vw-2rem)] flex-wrap items-center justify-center gap-2 px-2">
@@ -30,24 +26,25 @@ export function GenerateActionControls({ document, selection, viewport, settings
         type="button"
         disabled={!canGenerate}
         className="h-12 rounded-full bg-white px-7 text-base font-semibold !text-black transition hover:bg-white/90 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/40 disabled:pointer-events-none disabled:opacity-35"
-        title={job?.status === "failed" ? job.error : "Generate with ComfyUI"}
+        title={job?.status === "failed" ? job.error : preconditionMessage ?? "Generate with ComfyUI"}
         onClick={() => {
-          void runGenerationJob({ kind: "generate", label: "Generating", dispatch, task: () => runGenerate({ document, selection, viewport, settings, dispatch }) });
+          void workflow.generate();
         }}
       >
         {busy && job?.kind === "generate" ? "Generating..." : "Generate"}
       </button>
+      {preconditionMessage ? <span className="max-w-72 text-xs text-white/55" role="status">{preconditionMessage}</span> : null}
       <GenerationJobStatus generation={generation} />
       {candidate ? (
         <>
           <CandidatePicker generation={generation} dispatch={dispatch} />
           <CandidateControls
-            document={document}
             candidate={candidate}
             compareMode={generation.compareMode ?? "result"}
             settings={settings}
             busy={busy}
             dispatch={dispatch}
+            workflow={workflow}
           />
         </>
       ) : null}
@@ -78,23 +75,22 @@ function CandidatePicker({ generation, dispatch }: { generation: GenerationState
 }
 
 function CandidateControls({
-  document,
   candidate,
   compareMode,
   settings,
   busy,
   dispatch,
+  workflow,
 }: {
-  document: ImageDocument;
   candidate: GenerationCandidate;
   compareMode: GenerationCompareMode;
   settings: GenerateSettings;
   busy: boolean;
   dispatch: AppStore["dispatch"];
+  workflow: GenerationWorkflow;
 }) {
   const rerun = (label: string, nextSettings: GenerateSettings) => {
-    dispatch(commandIds.toolSetGenerateSettings, nextSettings);
+    void workflow.regenerate(candidate.id, nextSettings, label);
-    void runGenerationJob({ kind: "regenerate", label, dispatch, task: () => runGenerateFromCandidate({ candidate, settings: nextSettings, dispatch }) });
   };
   const disabled = busy;
 
@@ -112,13 +108,13 @@ function CandidateControls({
       />
       <CandidateButton disabled={disabled} label="Reuse seed" title="Regenerate with the same seed" onClick={() => rerun("Reuse seed", { ...candidate.settings, seed: candidate.seed })} />
       <CandidateButton disabled={disabled} label="New seed" title="Regenerate with a new seed" onClick={() => rerun("New seed", { ...candidate.settings, seed: -1 })} />
-      <CandidateButton disabled={disabled} label="Add as layer" title="Add candidate to the document as a layer" onClick={() => applyCandidateAsLayer(candidate, dispatch)} />
+      <CandidateButton disabled={disabled} label="Add as layer" title="Add candidate to the document as a layer" onClick={() => workflow.applyCandidateAsLayer(candidate.id)} />
       <CandidateButton
         disabled={disabled}
         label="Add + mask"
         title="Add candidate as a layer with a fresh refinement mask"
         onClick={() => {
-          void runGenerationJob({ kind: "refine", label: "Adding refinement mask", dispatch, task: () => applyCandidateAsRefinementLayer(candidate, dispatch) });
+          void workflow.applyCandidateAsRefinementLayer(candidate.id);
         }}
       />
       <CandidateButton
@@ -126,10 +122,7 @@ function CandidateControls({
         label="Replace pixels"
         title={candidate.inpaint ? "Replace masked pixels and preserve unmasked pixels" : "Only inpaint candidates can replace masked pixels"}
         onClick={() => {
-          void runGenerationJob({ kind: "replace", label: "Replacing pixels", dispatch, task: async () => {
+          void workflow.replaceCandidatePixels(candidate.id);
-            const source = await createMaskedPixelReplacementSource(document, candidate);
-            dispatch(commandIds.generationReplaceCandidatePixels, { candidateId: candidate.id, source, mimeType: "image/png" });
-          } });
         }}
       />
       <CandidateButton
@@ -209,51 +202,3 @@ function CandidateButton({ label, title, disabled, busy, onClick }: { label: str
 function selectedCandidate(generation: GenerationState): GenerationCandidate | undefined {
   return generation.candidates.find((candidate) => candidate.id === generation.selectedCandidateId) ?? generation.candidates[0];
 }
-
-function applyCandidateAsLayer(candidate: GenerationCandidate, dispatch: AppStore["dispatch"]) {
-  applyCandidateAsLayerWithIds(candidate, { layerId: crypto.randomUUID(), assetId: crypto.randomUUID() }, dispatch);
-}
-
-async function applyCandidateAsRefinementLayer(candidate: GenerationCandidate, dispatch: AppStore["dispatch"]) {
-  const layerId = crypto.randomUUID();
-  const maskLayerId = crypto.randomUUID();
-  const maskAssetId = crypto.randomUUID();
-  applyCandidateAsLayerWithIds(candidate, { layerId, assetId: crypto.randomUUID() }, dispatch);
-  const width = Math.max(1, Math.round(candidate.intrinsicSize.w));
-  const height = Math.max(1, Math.round(candidate.intrinsicSize.h));
-  const source = await createRefinementMask(width, height);
-
-  dispatch(commandIds.documentAddLayerMask, {
-    layerId,
-    asset: {
-      id: maskAssetId,
-      name: `${candidate.placement.layerName} refinement mask`,
-      mimeType: "image/png",
-      source,
-      intrinsicSize: { w: width, h: height },
-    },
-    maskLayer: {
-      id: maskLayerId,
-      type: "raster",
-      name: `${candidate.placement.layerName} refinement mask`,
-      visible: true,
-      locked: false,
-      opacity: 1,
-      assetId: maskAssetId,
-      transform: {
-        position: { ...candidate.placement.transform.position },
-        scale: { ...candidate.placement.transform.scale },
-        rotation: candidate.placement.transform.rotation,
-      },
-    },
-  });
-  dispatch(commandIds.toolSetActive, { tool: "eraser" });
-}
-
-function applyCandidateAsLayerWithIds(candidate: GenerationCandidate, ids: { layerId: string; assetId: string }, dispatch: AppStore["dispatch"]) {
-  dispatch(commandIds.generationApplyCandidateAsLayer, {
-    candidateId: candidate.id,
-    assetId: ids.assetId,
-    layerId: ids.layerId,
-  });
-}

view/bottom-controls/GenerateControls.tsx

@@ -2,9 +2,9 @@ import { useEffect, useRef, useState, type RefObject } from "react";
 import { CaretDown, CaretUp } from "@phosphor-icons/react";
 import { commandIds } from "@commands/ids";
 import type { AppStore } from "@editor/store";
-import type { GenerationOptions, GenerationResourcesState } from "@editor/state";
+import type { GenerationResourcesState } from "@editor/state";
-import { generateArchitectureDefaults } from "@editor/tools";
+import type { GenerateArchitecture, GenerateMode, GenerateSettings } from "@editor/tools";
-import type { GenerateArchitecture, GenerateMode, GenerateModel, GenerateSettings } from "@editor/tools";
+import { resolveGenerationModeOptions, resolveGenerationModelOptions, resolveGenerationStringOptions, resolveGenerationSupportOptions } from "@operations/generation/options";
 import { BottomControlSelectMenu, type BottomControlSelectOption } from "./SelectMenu";
 import { BottomControlSlider } from "./Slider";
 
@@ -55,11 +55,11 @@ export function GenerateControls({ settings, resources, dispatch }: GenerateCont
   const [inpaintOpen, setInpaintOpen] = useState(false);
   const [sizeOpen, setSizeOpen] = useState(false);
   const sizeRef = useRef<HTMLDivElement>(null);
-  const modelOptions = resolveModelOptions(settings, comfyOptions);
+  const modelOptions = resolveGenerationModelOptions(settings, comfyOptions);
-  const supportOptions = resolveSupportOptions(settings, comfyOptions);
+  const supportOptions = resolveGenerationSupportOptions(settings, comfyOptions);
-  const samplerOptions = resolveStringOptions(comfyOptions?.samplers, settings.sampler);
+  const samplerOptions = resolveGenerationStringOptions(comfyOptions?.samplers, settings.sampler);
-  const schedulerOptions = resolveStringOptions(comfyOptions?.schedulers, settings.scheduler);
+  const schedulerOptions = resolveGenerationStringOptions(comfyOptions?.schedulers, settings.scheduler);
-  const modeOptions = resolveModeOptions(settings, comfyOptions);
+  const modeOptions = resolveGenerationModeOptions(settings, comfyOptions, modes);
 
   useEffect(() => {
     if (!sizeOpen) return;
@@ -197,38 +197,6 @@ export function GenerateControls({ settings, resources, dispatch }: GenerateCont
   );
 }
 
-function resolveModelOptions(settings: GenerateSettings, comfyOptions: GenerationOptions | undefined): readonly BottomControlSelectOption<GenerateModel>[] {
-  const architecture = comfyOptions?.architectures?.find((option) => option.value === settings.architecture);
-  const models = architecture?.models ?? (settings.architecture === "sdxl" ? comfyOptions?.models : undefined) ?? [];
-  const fallbackModel = architecture?.defaultModel ?? generateArchitectureDefaults[settings.architecture].model;
-  const values = unique(["auto", ...models, ...(models.length === 0 && fallbackModel !== "auto" ? [fallbackModel] : []), settings.model]);
-  return values.map((model) => ({ value: model, label: model === "auto" ? "Auto" : model }));
-}
-
-function resolveSupportOptions(settings: GenerateSettings, comfyOptions: GenerationOptions | undefined) {
-  const defaults = generateArchitectureDefaults[settings.architecture];
-  return {
-    textEncoders: resolveStringOptions([...(comfyOptions?.textEncoders ?? []), defaults.textEncoder].filter((value) => value !== "auto"), settings.textEncoder),
-    vaes: resolveStringOptions([...(comfyOptions?.vaes ?? []), defaults.vae].filter((value) => value !== "auto"), settings.vae),
-  };
-}
-
-function resolveStringOptions(values: string[] | undefined, current: string): readonly BottomControlSelectOption<string>[] {
-  return unique([...(values ?? []), current]).map((value) => ({ value, label: value }));
-}
-
-function resolveModeOptions(settings: GenerateSettings, comfyOptions: GenerationOptions | undefined): readonly BottomControlSelectOption<GenerateMode>[] {
-  const architecture = comfyOptions?.architectures?.find((option) => option.value === settings.architecture);
-  const supportedModes = architecture?.supportedModes?.length ? architecture.supportedModes : generateArchitectureDefaults[settings.architecture].supportedModes;
-  const availableModes = modes.filter((mode) => supportedModes.includes(mode.value));
-  if (availableModes.some((mode) => mode.value === settings.mode)) return availableModes;
-  return [modes.find((mode) => mode.value === settings.mode), ...availableModes].filter((mode): mode is BottomControlSelectOption<GenerateMode> => Boolean(mode));
-}
-
-function unique<T>(values: T[]): T[] {
-  return Array.from(new Set(values));
-}
-
 function SectionTitle({ title }: { title: string }) {
   return <div className="px-1 text-xs font-semibold uppercase tracking-[0.18em] text-white/35">{title}</div>;
 }

view/useProjectLifecycle.tsx

@@ -0,0 +1,71 @@
+import { useCallback, useEffect, useRef } from "react";
+import type { AppStore } from "@editor/store";
+import { createProjectLifecycle } from "@operations/project/lifecycle";
+import { projectFileName } from "@operations/project/format";
+import { browserRecoveryStorage, downloadProjectFile, readProjectFile } from "@platform/browser/projectFiles";
+
+export function useProjectLifecycle(store: AppStore) {
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const lifecycleRef = useRef<ReturnType<typeof createProjectLifecycle> | null>(null);
+
+  useEffect(() => {
+    const lifecycle = createProjectLifecycle({ store, storage: browserRecoveryStorage });
+    lifecycleRef.current = lifecycle;
+    void lifecycle.recover();
+    return () => {
+      lifecycle.dispose();
+      lifecycleRef.current = null;
+    };
+  }, [store]);
+
+  const save = useCallback(() => {
+    const lifecycle = lifecycleRef.current;
+    if (!lifecycle) return;
+    const document = store.getState().document;
+    downloadProjectFile(lifecycle.snapshot(), projectFileName(document.name));
+    void lifecycle.markSaved();
+  }, [store]);
+
+  const openFilePicker = useCallback(() => inputRef.current?.click(), []);
+
+  const openFile = useCallback(async (file: File) => {
+    const lifecycle = lifecycleRef.current;
+    if (!lifecycle) return;
+    try {
+      await lifecycle.open(await readProjectFile(file));
+    } catch (error) {
+      window.alert(error instanceof Error ? error.message : "The project could not be opened.");
+    }
+  }, []);
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.defaultPrevented || (!event.metaKey && !event.ctrlKey)) return;
+      if (event.key.toLowerCase() === "s") {
+        event.preventDefault();
+        save();
+      } else if (event.shiftKey && event.key.toLowerCase() === "o") {
+        event.preventDefault();
+        openFilePicker();
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [openFilePicker, save]);
+
+  const input = (
+    <input
+      ref={inputRef}
+      type="file"
+      accept=".json,.image-studio.json,application/json"
+      className="hidden"
+      onChange={(event) => {
+        const file = event.currentTarget.files?.[0];
+        event.currentTarget.value = "";
+        if (file) void openFile(file);
+      }}
+    />
+  );
+
+  return { input, save, openFilePicker };
+}