A text box is an attractive interface for generative AI because it looks universal. Give the model an instruction, wait for a result, and repeat. The problem is that an image editor is not actually stateless. The user is not asking the system to create an arbitrary next image. They are usually asking for a transition from this particular image to a slightly different image while preserving a set of important invariants.

That distinction sounds small, but it changes how I think about the product architecture of AI image editors.

When I look at workflows in ClipLumi and similar tools, the interesting engineering problem is not “How large should the prompt field be?” It is “How do we represent the user’s current visual state, intended change, preservation constraints, references, model capabilities, and previous result without making the interface feel like a control panel?”

Here are the design principles I would carry into any AI image editing product.

1. Treat an edit as a state transition

A generation request can often be represented as:

prompt -> image

An edit request is closer to:

current image + requested delta + invariants + optional references -> next image

The current image matters because it contains decisions the user has already accepted. Composition, identity, product geometry, camera angle, lighting, background, and small details may all have value.

If the UI only exposes a prompt box, it hides this structure. The model receives instructions, but the product does not help the user distinguish between “what should change” and “what must remain stable.”

That is why a useful editing interface should make the transition explicit even if the visual UI remains simple.

A minimal edit-session data model

If I were implementing the product state explicitly, I would start with something closer to this than a single prompt string:

type Invariant = {
  key: string;
  description: string;
  severity: "hard" | "soft";
};

type EditSession = {
  sourceAssetId: string;
  currentAssetId: string;
  requestedDelta: string;
  invariants: Invariant[];
  references: Array<{
    assetId: string;
    role: "style" | "color" | "composition" | "identity" | "material";
  }>;
  modelId: string;
  options: {
    aspectRatio?: string;
    outputCount?: number;
    quality?: string;
  };
  status:
    | "ready"
    | "generating"
    | "reviewing"
    | "accepted"
    | "repairing"
    | "failed";
  parentVersionId?: string;
};

The important part is not the exact TypeScript. It is that the system can answer basic questions without reconstructing them from prose:

• Which asset is authoritative right now?
• What is the requested delta?
• Which constraints are hard failures versus preferences?
• What role does each reference play?
• Which version is this edit branching from?
• Is the user exploring, reviewing, repairing, or done?

Once those concepts exist as product state, prompt assembly becomes an adapter concern instead of the source of truth.

Use a small state machine for the edit lifecycle

The edit lifecycle is also easier to reason about if it has named states:

ready
  -> generating
  -> reviewing
      -> accepted
      -> repairing -> generating
      -> ready      (revert / branch)
  -> failed

This prevents several UI bugs that otherwise look unrelated. For example, if the user can change the model while a request is generating, which model should a retry use? If the user reverts to an earlier asset, do the current preservation constraints still apply? If an output is accepted and then repaired, should the repair branch from the accepted result or from the original source?

A state machine forces those questions to have explicit answers.

2. Model “change” and “preserve” separately

Many failed edits are not failures to understand the requested change. They are failures to protect the rest of the image.

Consider a product-photo request:

Replace the background with a clean studio setting.

That describes the delta but not the invariants. A more complete product intent is:

• change: background and surrounding surface;
• preserve: product silhouette, logo, label, perspective, scale, and shadow direction.

Those are different data concepts even if they eventually become one model prompt.

This suggests an architectural separation between intent capture and model prompt assembly. The UI can collect or infer a small number of structured constraints, while the backend converts them into the model-specific representation required by the selected provider.

The user should not need to understand provider syntax to express invariants.

3. References need roles, not just attachment slots

An image reference is not self-explanatory.

A user might attach a reference because they want its color palette, clothing style, background material, lighting mood, composition, or object shape. If the product treats every reference as “make it like this,” the model gets more visual information but less semantic clarity.

A stronger design asks the product layer to understand the role of each reference.

Even if you do not expose a dropdown for every reference, the prompt pipeline can benefit from language such as:

Use reference 1 only for the background color and surface texture. Preserve the subject and composition from the source image.

This is especially useful when an editor supports multiple reference images. More files are not automatically more context. Unlabeled references can become competing instructions.

4. Model capability is part of product state

One of the easiest mistakes in a multi-model AI product is to make every control visible for every model.

That creates a UI contract the backend cannot always keep.

If model A supports a certain editing mode, model B supports reference images, and model C is optimized mainly for generation, the interface should derive available controls from a capability map rather than from a global form definition.

Conceptually:

model -> capabilities -> visible controls -> validation -> request adapter

The capability map becomes a useful source of truth for both frontend behavior and backend validation.

It also prevents a common observability problem: requests that look valid in the UI but are silently ignored or degraded by the selected model.

5. Preserve a reversible history

AI editing is probabilistic, so users need a way to compare states rather than merely replace them.

A good editing loop looks like:

source -> edit A -> edit B -> revert to A -> branch into edit C

You do not necessarily need a full Photoshop-style history tree, but the product should at least preserve enough context to let the user recover a previous useful state.

This is more important than it sounds. Without reversibility, every edit feels risky. Users compensate by downloading intermediate images, opening duplicate tabs, or repeatedly regenerating from memory.

Reversibility is not only a convenience feature. It increases the user’s willingness to make narrower, more experimental changes.

A practical implementation detail is to store edits as a graph of versions rather than a mutable “current image” pointer with no provenance:

type ImageVersion = {
  id: string;
  parentId?: string;
  assetId: string;
  requestedDelta?: string;
  invariantKeys: string[];
  createdAt: string;
  decision?: "accepted" | "rejected" | "repair";
};

You do not need to expose the graph in the UI. But keeping the parent relationship makes revert, compare, branch, audit, and “repair from the last accepted version” much easier.

6. Acceptance criteria can improve the UI without becoming a form

Users often know how they will judge an edit, even if they do not call those checks “acceptance criteria.”

For a headshot:

• face still looks like the same person;
• hairline is intact;
• clothing changed correctly;
• background looks natural.

For a product image:

• label is readable;
• shape is unchanged;
• new background fits the brand;
• shadow still makes physical sense.

A product does not need four mandatory fields to capture this. It can surface lightweight reminders, example prompt structures, or contextual suggestions.

The important point is that the interface should help users evaluate continuity, not only generate novelty.

7. Observability should record product decisions, not just provider errors

When an edit goes wrong, “request failed” is rarely enough information for debugging.

For an AI image editor, useful operational records may include:

• selected model;
• editing mode;
• whether a source image was present;
• number of references;
• whether prompt enhancement was applied;
• the final assembled prompt sent to the provider;
• output dimensions or aspect ratio;
• provider latency;
• success/failure state;
• which product-level options were ignored or transformed.

This does not mean logging private user assets carelessly. It means recording the decisions made by your own product pipeline so failures are explainable.

If an “AI Enhance” layer rewrites a prompt before it reaches the image model, for example, the monitoring surface should make that transformation visible. Otherwise a developer may blame the image model for a regression introduced by the application layer.

I would also separate the event log from the visual assets themselves. A minimal event record can be small:

{
  "event": "edit_requested",
  "sessionId": "...",
  "sourceVersionId": "...",
  "modelId": "...",
  "referenceCount": 1,
  "invariantCount": 4,
  "promptEnhanced": false,
  "requestShapeVersion": "v3"
}

That is usually enough to debug product behavior without dumping user images or sensitive raw content into logs. Store only what you actually need, and treat private assets and full prompts according to your privacy model rather than assuming observability justifies indefinite retention.

8. Prompt enhancement needs a stop condition

Automatic prompt enhancement sounds universally helpful until it starts overriding clear user intent.

A short prompt such as “change the wall to blue” may benefit from contextual expansion. A long, carefully constrained instruction may not.

That suggests a rule-based or confidence-based enhancement policy rather than “always enhance.”

Possible signals include:

• prompt length;
• presence of explicit preservation language;
• number of referenced entities;
• whether the request is generation or editing;
• whether the selected model already performs its own prompt interpretation.

The important architectural point is that prompt enhancement is a transformer in the request pipeline, not a magical quality switch. It should be observable, bypassable, and testable.

9. Image editing benefits from a smaller default action

Generative interfaces often encourage maximal prompts because novelty is the product. Editing interfaces benefit from the opposite default: make the smallest change that satisfies the intent.

That reduces unintended drift and makes failure easier to diagnose.

For example, an old-photo restoration request is inherently preservation-sensitive. A system that aggressively “improves” faces, clothing, and scenery may produce a prettier result while failing the actual task.

The better product question is not “Can the model make this more impressive?” It is “Can the model repair the requested defect without damaging trusted information?”

10. The backend adapter should absorb provider differences

A product with multiple image models should avoid leaking provider-specific request shapes into the rest of the application.

A useful boundary is:

Product Intent
  -> normalized edit request
  -> provider adapter
  -> provider-specific payload
  -> normalized result

The normalized request can include source image, references, edit text, aspect ratio, output size, and product-level flags. Each adapter decides how those concepts map to the provider.

This keeps the frontend stable while models change underneath it.

It also makes A/B testing and fallback logic less painful because the product is comparing normalized intents rather than unrelated API payloads.

A useful repair concept: shrink the repair radius

A production editor also needs a concept of repair radius: how much of the accepted state is allowed to reopen during the next pass.

Early in exploration, the radius can be wide. After the user accepts composition, subject, and lighting, the radius should shrink. If only a contact shadow is wrong, the next request should not implicitly reopen the face, product geometry, background, crop, and color grade.

You can model this explicitly or simply assemble stronger preservation language as confidence increases. Either way, the product should behave as if accepted state becomes progressively more expensive to disturb.

This gives the UI a useful default: the closer the user is to done, the more conservative the next action should be.

Do not let an old request overwrite a newer edit

Async image jobs add one more state problem: results do not necessarily finish in the order the user started them. Imagine edit A starts from version 12, then the user changes direction and starts edit B from version 13. If B finishes first and becomes the accepted canvas, a late completion from A must not silently replace it just because its provider response arrived last.

Bind each attempt to an application-level request ID and the source version it started from. When a result returns, compare that identity with the active version before moving the current pointer. A stale result can still be useful in history, but it should not overwrite currentAssetId without an explicit user action. Cancellation can save compute; the stale-response guard is what protects correctness.

Timeouts need the same discipline. A client timeout does not prove that the provider rejected the job. The provider may still be generating or may already have accepted a paid request. Treat that state as status_unknown, recover the existing provider task ID or idempotency key when the API supports one, and reconcile that attempt before creating another paid job.

A compact rule is:

• every attempt has a request ID and source version;
• only a result that still matches the active intent may advance the current canvas automatically;
• cancelled or stale completions may enter history but cannot seize the current pointer;
• timeout means uncertain until reconciled, not confirmed failure;
• retry the same logical attempt when possible instead of blindly paying for a duplicate.

This turns race conditions and retries into explicit product state instead of timing accidents.

The prompt box should be the surface, not the architecture

Natural language is still the best interface for many AI image edits. I am not arguing for replacing it with dozens of controls.

The point is that the product behind the prompt box needs a stronger model of the task.

A reliable editor has to know what image is current, what change is requested, what must be preserved, what references mean, which model capabilities are available, what transformation happened to the prompt, and how the user can recover if the result is worse.

That is a state-management problem, a capability-management problem, and an observability problem before it is a text-box problem.

If you are building an AI image product, try mapping one real workflow as a state transition rather than a single prompt request. Then inspect a live editor such as ClipLumi and ask which parts of that state are explicit, inferred, hidden, or missing. Also ask what your version graph and event log would need in order to explain a bad second-pass edit six hours later.

That exercise usually reveals more useful product work than adding another adjective to the prompt template.

Disclosure: I work on ClipLumi. I am using it here as a concrete product example; the state model, version graph, and repair-radius ideas are general architecture patterns.

That description is correct, but it hides the difficult part. The PDF file is only the final container. Before generating it, the application must make image pixels, physical paper, printable margins, page overlap, preview geometry, and browser memory limits agree with one another.

I ran into these problems while building Rasterbator.app, a browser-based tool that converts a local image into a multi-page poster PDF. This article explains the layout model behind the tool and several implementation decisions that mattered more than the export button.

Start with physical units, not canvas pixels

The browser preview is useful, but it should not be the source of truth. A user is ultimately printing sheets measured in millimetres or inches, while a PDF library expects points.

The conversion is:

const MM_TO_PTS = 72 / 25.4;

Every paper, margin, overlap, and final-poster calculation can then use PDF points. The canvas becomes a visual projection of that model rather than an independent layout system.

For a page with a margin on every side:

const printableWidth = paperWidth - 2 * margin;
const printableHeight = paperHeight - 2 * margin;

Overlap changes the distance between neighbouring pages. If two sheets share an overlap strip, the next tile does not start one complete printable width away.

const logicalWidth = printableWidth - overlap;
const logicalHeight = printableHeight - overlap;

For a poster that is pagesWide × pagesHigh, the physical dimensions become:

const posterWidth = pagesWide * logicalWidth + overlap;
const posterHeight = pagesHigh * logicalHeight + overlap;

The final + overlap matters. There are n - 1 shared transitions across n sheets, not n completely separate overlap deductions.

Preserve image aspect ratio before rounding page counts

Users may specify the page width, page height, or both. When only one dimension is fixed, calculate the poster's continuous physical size first and round the resulting page count afterward.

Suppose the user chooses a width of four pages. The continuous poster width is known. The image aspect ratio determines its physical height, and the logical page height determines the fractional page count.

const imageAspect = imageHeight / imageWidth;

const posterWidth = pagesWide * logicalWidth + overlap;
const posterHeight = posterWidth * imageAspect;
const pagesHighFloat = (posterHeight - overlap) / logicalHeight;
const pagesHigh = Math.ceil(pagesHighFloat);

Rounding too early changes the image ratio or silently stretches the result. After rounding, the page grid may be slightly larger than the intended physical poster. That extra area must be treated as an offset or crop region rather than as permission to distort the image.

In Rasterbator.app, the grid is centred horizontally while retaining the intended vertical alignment. The key is that the image dimensions and the sheet grid remain two related but distinct rectangles.

A tile needs source and destination geometry

For each output page, the application needs more than a row and column number. It needs to know:

1. which part of the poster belongs on the sheet;
2. which part of the source image maps to that poster rectangle;
3. where the result sits inside the printable area;
4. whether overlap, crop marks, or page labels extend beyond the main image region.

A useful mental model is:

source image pixels
        ↓ crop/fit mapping
poster-space physical coordinates
        ↓ page-window intersection
page-space PDF coordinates

Keeping these stages separate avoids a common bug: using preview-canvas coordinates as though they were physical output coordinates. Preview dimensions change with the viewport. The PDF must not.

Halftone effects create another grid

The tool optionally renders circles, squares, or lines rather than copying the source image directly. That introduces a second grid: the halftone sampling grid.

A nominal grid size rarely divides the final poster dimensions perfectly. If the application blindly steps by the requested size, the last row or column may be clipped or visibly narrower. One solution is to calculate the number of complete cells and derive a corrected cell size that fits the poster.

const columns = Math.floor(posterWidth / requestedCellSize);
const rows = Math.floor(posterHeight / requestedCellSize);

const exactCellWidth = posterWidth / Math.max(columns, 1);
const exactCellHeight = posterHeight / Math.max(rows, 1);
const cellSize = Math.min(exactCellWidth, exactCellHeight);

The remaining space can then be centred as an offset. This makes the halftone pattern look intentional instead of leaving a small accidental strip at an edge.

Browser memory is part of the product design

A compressed phone photo may be only a few megabytes on disk but much larger after decoding. A 6000 × 4000 RGBA image occupies roughly 96 MB before considering canvas buffers, cropped images, encoded JPEG or PNG data, PDF objects, previews, and temporary copies.

A browser-only workflow therefore needs product limits, not just exception handling.

The application should estimate work before export and communicate when a job is unreasonable. Desktop and mobile limits should differ because their memory ceilings and process-killing behaviour differ. It is better to explain that a 100-page job is too large on a phone than to let the tab disappear at 78%.

Other practical choices include:

• dynamically importing the PDF library only when needed;
• processing pages sequentially rather than creating every canvas at once;
• releasing temporary canvas references promptly;
• avoiding multiple full-resolution image copies;
• reporting page-by-page progress;
• keeping the preview lower resolution than the final source data.

Printing requires trust, not only correctness

Even mathematically correct output can feel unsafe to print. The user is spending paper, ink, tape, and time, so the interface should answer physical questions before export:

• What will the assembled width and height be?
• Is the preview showing the full sheet or only the printable area?
• Where will pages overlap?
• Will the image be cropped, fitted, or stretched?
• Are crop marks and page-position labels included?
• Which printer setting preserves the intended scale?

This is why Rasterbator.app exposes the page grid, margins, overlap, final dimensions, crop marks, and labels instead of hiding them behind a single “make poster” button.

The larger lesson

Small browser utilities often look simple because their complexity is compressed into a narrow workflow. The hardest engineering work may sit between familiar APIs: image decoding, canvas rendering, PDF generation, and printing are each manageable, but the coordinate contracts between them determine whether the result is usable.

For file-based tools, define one authoritative model, convert units explicitly, preserve continuous geometry before rounding, and treat resource limits as part of the interface. The export library should be the last step, not the architecture.

The live tool is available at Rasterbator.app. I am currently improving the first-run explanations, particularly around overlap and final physical size, and would value feedback from anyone who has built browser-based image or printing workflows.