lcode-cli 0.41.0__tar.gz → 0.42.0__tar.gz

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/CHANGELOG.md

@@ -6,6 +6,23 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.42.0] - 2026-10-24
+
+### Added
+
+- **Image mode's options, results and follow-ups** (#151). See
+  [Image mode](https://nasser1941.github.io/lcode/modes/#image-mode).
+  - **Options in a request** (`a red fox --n 4 --ar 16:9 --seed 42 --quality best --style photo`)
+    or for the session (`/options n=4 ar=16:9`): how many images, the shape, the seed (counting up
+    over several images), a quality preset (0.5, 1 or 2 megapixels), ten style presets, and a
+    negative prompt for models that use one.
+  - **Numbered results, shown in the terminal:** the picture itself in kitty, Ghostty, iTerm2 and
+    WezTerm, and a half-block colour preview elsewhere (the `preview` setting).
+  - **Follow-ups:** `/again` (new seeds), `/vary 3` (four variations of image #3), `/gallery` and
+    `/open 3`. The gallery and options are saved with the session.
+  - `lcode --mode image -p "… --n 2"` reports every image's file and seed.
+  - One image is now named `<time>-<prompt>.png` (no `-1`).
+
 ## [0.41.0] - 2026-10-23
 
 ### Added
@@ -923,7 +940,8 @@ First public release.
 - `AGENTS.md` project instructions and `/init` to generate them.
 - One-line installer for Linux and macOS.
 
-[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.41.0...HEAD
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.42.0...HEAD
+[0.42.0]: https://github.com/nasser1941/lcode/compare/v0.41.0...v0.42.0
 [0.41.0]: https://github.com/nasser1941/lcode/compare/v0.40.0...v0.41.0
 [0.40.0]: https://github.com/nasser1941/lcode/compare/v0.39.0...v0.40.0
 [0.39.0]: https://github.com/nasser1941/lcode/compare/v0.38.0...v0.39.0

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.41.0
+Version: 0.42.0
 Summary: A local-first terminal coding agent powered by open-weight models on your own GPU or Mac, via Ollama.
 Project-URL: Homepage, https://nasser1941.github.io/lcode/
 Project-URL: Documentation, https://nasser1941.github.io/lcode/

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/docs/configuration.md

@@ -27,6 +27,7 @@ lcode config path                      # print the file location
 | `comfyui_url` | `http://127.0.0.1:8188` | ComfyUI's address, for image and video mode |
 | `comfyui_path` | (found) | Your ComfyUI folder, if lcode doesn't find it; lcode starts it when needed ([ComfyUI](modes.md#comfyui)) |
 | `media_dir` | `.lcode/media` | Where images and videos go: a folder in the project, or an absolute path |
+| `preview` | `auto` | Images in the terminal: `auto`, `kitty`, `iterm`, `blocks` (colour text) or `off` ([results](modes.md#results)) |
 | `image_model` | `flux2-klein-4b` | The model image mode uses: a key from `lcode media` ([image models](modes.md#image-models)) |
 | `think` | `true` | Let the model reason before answering |
 | `web` | `on` | Web search and page fetching: `on`, `ask` (before each search/website) or `off` |

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/docs/modes.md

@@ -15,7 +15,7 @@ Unloaded qwen3.6-35b to free the GPU for images.
 Starting ComfyUI (~/comfy/ComfyUI) in the background.
 Describe an image and press Enter: FLUX.2 klein 4B makes it on your GPU, into .lcode/media.
 image ❯ a red fox sitting in fresh snow at dusk
-◆ .lcode/media/20261023-184531-a-red-fox-sitting-in-fresh-snow-at-dusk-1.png  1024×1024 · FLUX.2 klein 4B · seed 3714779554 · 8.0 s
+◆ #1 .lcode/media/20261023-184531-a-red-fox-sitting-in-fresh-snow-at-dusk.png  1024×1024 · FLUX.2 klein 4B · seed 3714779554 · 8.0 s
 ```
 
 - **Switching:** `/mode code`, `/mode image` and `/mode video` switch in a session. `lcode --mode image`
@@ -33,9 +33,53 @@ in code mode even if they're still in your `mcp.json`. It says so once.
 ## Image mode
 
 In image mode, what you type is a description, and lcode makes the picture. No language model is
-involved: lcode fills in its own ComfyUI workflow for the image model and follows the job itself.
-For now that's one image per request, 1024×1024, with the image model you choose (see
-[Image models](#image-models)). Sizes, seeds and variations come next (#151).
+involved: lcode fills in its own ComfyUI workflow for the image model and follows the job itself,
+with the image model you choose (see [Image models](#image-models)).
+
+```text
+image ❯ a red fox in fresh snow --n 2 --ar 16:9 --seed 7
+◆ #1 .lcode/media/20261023-194019-a-red-fox-in-fresh-snow.png  1360×768 · FLUX.2 klein 4B · seed 7 · 4.9 s
+▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀   (the picture, in colour)
+◆ #2 .lcode/media/20261023-194024-a-red-fox-in-fresh-snow.png  1360×768 · FLUX.2 klein 4B · seed 8 · 2.7 s
+image ❯ /vary 1 --n 2
+Variations of #1: a red fox in fresh snow
+◆ #3 …
+```
+
+### Options
+
+Add them to a request, or set them for the session with `/options` (`/options n=4 ar=16:9
+quality=best style=photo`). A flag in a request wins over `/options` for that request. `/options`
+alone shows them.
+
+| Flag | `/options` | What it does |
+|---|---|---|
+| `--n 4` | `n=4` | How many images: 1 to 8. Each gets its own seed. |
+| `--ar 16:9` | `ar=16:9` | The shape: a ratio (`3:2`, `9:16`, up to 4:1), a name (`square`, `portrait`, `landscape`, `wide`, `tall`, `photo`, `cinema`), or pixels (`--size 1344x768`). |
+| `--seed 42` | `seed=42` | The same seed and settings make the same image. With `--n`, the seeds count up (42, 43, …). `seed=random` goes back to a new one each time. |
+| `--quality best` | `quality=best` | `fast` (about 0.5 megapixels, fewer steps for models that allow it), `balanced` (1 megapixel, the default), `best` (2 megapixels, more steps where they help). |
+| `--style photo` | `style=photo` | Adds a style to the description: `photo`, `cinematic`, `anime`, `watercolor`, `oil`, `pixel`, `3d`, `sketch`, `comic`, `flat`. `style=none` takes it off. |
+| `--no "text, people"` | `no="text"` | A negative prompt, for models that use one. FLUX.2 klein and Z-Image Turbo don't (they're distilled), and lcode says so: describe what you want instead. |
+
+### Results
+
+- **Numbered:** every image in the session gets a number (`#3`), shown with its file, size, model,
+  seed and time.
+- **Shown in the terminal:** in kitty, Ghostty, iTerm2 and WezTerm the picture itself appears
+  under its line. Other terminals get a small colour preview drawn with half blocks. The
+  `preview` setting chooses: `auto`, `kitty`, `iterm`, `blocks` or `off`. Inside tmux or screen,
+  lcode draws the half-block preview.
+- **Follow-ups:**
+
+| Command | What it does |
+|---|---|
+| `/again` | The last request again with new seeds; flags change it (`/again --n 4 --ar 9:16`) |
+| `/vary 3` | Four variations of image #3: its prompt and options, new seeds (`/vary 3 --n 2`; the last image without a number) |
+| `/gallery` | The session's images with their prompt, size, model and seed; `/gallery all` lists the latest 50 in the media folder |
+| `/open 3` | Opens image #3 in your image viewer (the last one without a number) |
+
+- **Sessions:** the gallery and `/options` are saved with the session, so `lcode -c` or `/resume`
+  brings them back. An image session is listed under its first prompt.
 
 - **Progress:** the status line says what ComfyUI is doing (loading the model, reading the
   prompt, drawing, decoding), the step, the time left and the time so far. If other jobs are ahead
@@ -43,14 +87,15 @@ For now that's one image per request, 1024×1024, with the image model you choos
 - **Cancel** with Esc or Ctrl+C: lcode cancels the job in ComfyUI too, so it stops using the GPU.
 - **Type ahead:** what you type while an image is being made waits in the next prompt.
 - **Files:** each image goes to `.lcode/media/` in the project (the `media_dir` setting), named
-  after the time and the prompt, with a `.json` next to it holding the prompt, model, seed, size and
-  steps. PNGs carry the same in their own metadata (an `lcode` text chunk), and ComfyUI's workflow
+  after the time and the prompt, with a `.json` next to it holding the prompt, model, seed, size,
+  steps, quality and style. PNGs carry the same in their own metadata (an `lcode` text chunk), and ComfyUI's workflow
   as well. `.lcode/media/` keeps itself out of git; a folder of your own (`lcode config set
   media_dir assets/generated`) doesn't.
 - **Nothing is lost:** lcode writes each job down while it runs. If lcode crashes or the terminal
   closes before an image arrives, the next request in image mode saves it.
-- **From scripts:** `lcode --mode image -p "a red fox in the snow"` makes one image and exits;
-  with `--output json` it prints a result with the file paths, model, seed, size and time.
+- **From scripts:** `lcode --mode image -p "a red fox in the snow --n 2"` makes the images and
+  exits; with `--output json` it prints a result with the file paths, the model, the seeds, the size
+  and the time.
 - **No Ollama needed:** `lcode --mode image` starts even when Ollama isn't running or the coding
   model isn't installed; `/mode code` then says what's missing.
 
@@ -123,6 +168,10 @@ lcode media install z-image-turbo  # download what's missing (asks first; --yes
 
 ### Measured
 
+On an RTX 4080 Laptop GPU (12 GB), FLUX.2 klein 4B makes a 1360×768 image in 2.6 to 2.8 s and a
+`--quality fast` image (720×720) in 1.3 to 2.0 s once it's loaded.
+
+
 On an RTX 4080 Laptop GPU (12 GB) with 32 GB of RAM, ComfyUI 0.38, 1024×1024, four different
 prompts each:
 

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/docs/quickstart.md

@@ -12,7 +12,7 @@ lcode
 
 ```text
 ╭──────────────────────────────────────────────╮
-│ lcode v0.41.0 — local coding agent           │
+│ lcode v0.42.0 — local coding agent           │
 │                                              │
 │ model    lcode-qwen3.6-35b                   │
 │ context  256K tokens                         │

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/docs/usage.md

@@ -81,6 +81,7 @@ reasoning is on.
 | `/think [on\|off]` | Toggle reasoning |
 | `/verbose` | Toggle showing the reasoning text |
 | `/mode [code\|image\|video]` | Switch what lcode makes: [code, images or videos](modes.md) |
+| `/options`, `/again`, `/vary N`, `/gallery`, `/open N` | Image mode: [options for the session, follow-ups on results](modes.md#results) |
 | `/permissions [ask\|plan\|auto-edit\|yolo]` | Set the permission mode |
 | `/cd DIR` | Change the working directory |
 | `/todos` | Show the model's task list |

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/src/lcode/__init__.py

@@ -3,7 +3,7 @@
 From a program: `from lcode import Session` (see lcode.api).
 """
 
-__version__ = "0.41.0"
+__version__ = "0.42.0"
 
 API = ("Session", "Result", "Options", "SetupError")
 

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/src/lcode/agent.py

@@ -309,6 +309,7 @@ class Settings:
     comfyui_path: str | None = None  # a ComfyUI install lcode doesn't find by itself (lcode.comfy)
     media_dir: str = ".lcode/media"  # where image and video mode save their files (lcode.media)
     image_model: str = "flux2-klein-4b"  # the media catalog's model image mode uses (lcode.media_catalog)
+    preview: str = "auto"  # images in the terminal: auto, kitty, iterm, blocks or off (lcode.preview)
     num_batch: int | None = None
     keep_alive: str = "30m"
     think: bool = True
@@ -375,6 +376,11 @@ class Agent:
         self.interactive = True  # False for `lcode -p`: no end-of-session questions
         self.comfy_process = None  # the ComfyUI lcode started for image and video mode, stopped when it exits
         self.no_coding_model = ""  # why there's no coding model, when lcode started in image or video mode without
+        from lcode.imageopts import Options as ImageOptions
+
+        self.image_options = ImageOptions()  # image mode's defaults for this session (/options)
+        self.media_results: list[dict] = []  # the session's images, numbered (/gallery, /vary, /open)
+        self.last_request: tuple[str, ImageOptions] | None = None  # for /again
         self.reflected = 0  # messages before this index were already checked for notes to remember
         self._memory: memory_notes.Memory | None = None
         self._agent_types: tuple[Path, dict[str, subagents.AgentType], list[str]] | None = None
@@ -679,8 +685,10 @@ class Agent:
         return any(m.get("role") == "user" for m in self.messages)
 
     def save(self) -> None:
-        if not (self.has_conversation() or self.session_name):
+        if not (self.has_conversation() or self.session_name or self.media_results):
             return  # nothing worth resuming
+        if not self.session_title and not self.has_conversation() and self.media_results:
+            self.session_title = " ".join(self.media_results[0]["prompt"].split())[:60]  # an image session
         self.session_title = self.session_title or sessions.title_from(self.messages)
         f = self.session_file()
         f.parent.mkdir(parents=True, exist_ok=True)
@@ -689,6 +697,7 @@ class Agent:
             "model": self.settings.model,
             "mode": self.settings.mode,
             "image_model": self.settings.image_model,
+            "media": {"results": self.media_results, "options": self.image_options.to_json()},
             "name": self.session_name,
             "title": self.session_title,
             "messages": self.messages,
@@ -739,6 +748,9 @@ class Agent:
             self.settings.mode = data["mode"]  # a session belongs to the mode it was made in
         if isinstance(data.get("image_model"), str):
             self.settings.image_model = data["image_model"]
+        media = data.get("media") or {}
+        self.media_results = [r for r in media.get("results") or [] if isinstance(r, dict) and "path" in r]
+        self.image_options = type(self.image_options).from_json(media.get("options") or {})
         self.session_title = data.get("title") or sessions.title_from(self.messages)
         self.tools.read_mtimes.clear()  # files may have changed since; the model must read them again
         self.tools.todos = list(data.get("todos") or [])

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/src/lcode/api.py

@@ -201,6 +201,7 @@ def open_agent(cwd: Path, options: Options, console: Console, hw: Hardware | Non
         comfyui_path=cfg["comfyui_path"],
         media_dir=cfg["media_dir"],
         image_model=cfg["image_model"],
+        preview=cfg["preview"],
         web=switch(options.web, cfg["web"], "on"),
         search_backend=cfg["search_backend"],
         searxng_url=cfg["searxng_url"],

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/src/lcode/cli.py

@@ -812,7 +812,7 @@ def media_request(agent, prompt: str, out: Console, quiet: bool) -> None:
         api.close_agent(agent)
         sys.exit(2)
     try:
-        made = media.generate_image(agent, prompt)
+        made = media.request(agent, prompt)
     except (media.MediaError, KeyboardInterrupt) as e:
         message = str(e) or "Cancelled."
         if quiet:
@@ -826,12 +826,13 @@ def media_request(agent, prompt: str, out: Console, quiet: bool) -> None:
             "type": "result",
             "status": "success",
             "mode": "image",
-            "files": [str(path) for path in made.files],
-            "model": made.model,
-            "seed": made.seed,
-            "width": made.width,
-            "height": made.height,
-            "seconds": round(made.seconds, 1),
+            "files": [str(path) for one in made for path in one.files],
+            "model": made[0].model,
+            "seed": made[0].seed,
+            "seeds": [one.seed for one in made],
+            "width": made[0].width,
+            "height": made[0].height,
+            "seconds": round(sum(one.seconds for one in made), 1),
         }
         print(json.dumps(result, ensure_ascii=False), flush=True)
     api.close_agent(agent)

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/src/lcode/comfy.py

@@ -560,13 +560,15 @@ def describe_history_error(entry: dict) -> str:
 
 
 def save(server: Server, outputs: dict, folder: Path, stem: str, meta: dict) -> list[Path]:
-    """Fetch the job's files into `folder`: stem-1.png, … with stem-1.json next to each."""
+    """Fetch the job's files into `folder`: stem.png (stem-2.png if that's taken), or stem-1.png, … for several,
+    each with its settings in a .json next to it."""
     folder.mkdir(parents=True, exist_ok=True)
     items = [item for node in outputs.values() for kind in OUTPUT_KINDS for item in node.get(kind, [])]
+    items = [it for it in items if it.get("type", "output") == "output"]
     saved = []
-    for i, item in enumerate((it for it in items if it.get("type", "output") == "output"), 1):
+    for i, item in enumerate(items, 1):
         ext = Path(item["filename"]).suffix or ".png"
-        path = unique(folder / f"{stem}-{i}{ext}")
+        path = unique(folder / (f"{stem}{ext}" if len(items) == 1 else f"{stem}-{i}{ext}"))
         data = server.fetch(item)
         if ext.lower() == ".png":
             data = with_text(data, "lcode", json.dumps(meta, ensure_ascii=False))

{lcode_cli-0.41.0 → lcode_cli-0.42.0}/src/lcode/config.py

@@ -46,6 +46,7 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "comfyui_path": (None, str, "your ComfyUI folder, if lcode doesn't find it (lcode starts it when needed)"),
     "media_dir": (".lcode/media", str, "where images and videos go: a folder in the project, or an absolute path"),
     "image_model": ("flux2-klein-4b", str, "the model image mode uses: a key from `lcode media`"),
+    "preview": ("auto", str, "images in the terminal: auto | kitty | iterm | blocks (colour text) | off"),
     "think": (True, bool, "let the model reason before answering (slower, better)"),
     "web": ("on", str, "web search and page fetching for the model: on | ask | off"),
     "search_backend": ("auto", str, "auto | ollama | brave | tavily | searxng (keys come from environment variables)"),
@@ -211,6 +212,11 @@ def coerce(key: str, value: object) -> object:
         raise ConfigError(f"permission_mode must be one of {', '.join(PERMISSION_MODES)}")
     if key == "mode" and value not in WORK_MODES:
         raise ConfigError(f"mode must be one of {', '.join(WORK_MODES)}")
+    if key == "preview":
+        from lcode.preview import PROTOCOLS
+
+        if value not in PROTOCOLS:
+            raise ConfigError(f"preview must be one of {', '.join(PROTOCOLS)}")
     if key == "image_model":
         from lcode import media_catalog
 

lcode_cli-0.42.0/src/lcode/imageopts.py

@@ -0,0 +1,207 @@
+"""Image options: how many, what shape, which seed, how good, what to avoid, which style.
+
+They're typed in the request (`a red fox --n 4 --ar 16:9 --seed 42 --quality best --style photo --no "people"`), or
+set for the session with `/options n=4 ar=16:9`. Flags in a request win over the session's options for that request.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import shlex
+from dataclasses import asdict, dataclass, replace
+
+QUALITIES = ("fast", "balanced", "best")
+MAX_COUNT = 8
+SIZES = {  # names for aspect ratios
+    "square": "1:1",
+    "portrait": "3:4",
+    "landscape": "4:3",
+    "wide": "16:9",
+    "tall": "9:16",
+    "photo": "3:2",
+    "cinema": "21:9",
+}
+STYLES = {
+    "photo": "professional photograph, natural light, sharp focus, 35mm lens",
+    "cinematic": "cinematic film still, dramatic lighting, shallow depth of field, color graded",
+    "anime": "anime illustration, clean line art, vibrant cel shading",
+    "watercolor": "watercolor painting, soft washes, visible paper texture",
+    "oil": "oil painting, visible brush strokes, rich colors",
+    "pixel": "pixel art, 16-bit, crisp pixels, limited palette",
+    "3d": "3D render, soft global illumination, studio lighting",
+    "sketch": "pencil sketch, graphite, cross-hatching, on paper",
+    "comic": "comic book art, bold ink outlines, halftone shading",
+    "flat": "flat vector illustration, minimal, bold shapes",
+}
+ALIASES = {
+    "n": "n",
+    "count": "n",
+    "ar": "size",
+    "aspect": "size",
+    "size": "size",
+    "seed": "seed",
+    "quality": "quality",
+    "q": "quality",
+    "no": "negative",
+    "negative": "negative",
+    "style": "style",
+}
+FLAG = re.compile(r"(?:^|\s)--?(" + "|".join(sorted(ALIASES, key=len, reverse=True)) + r")\b(?=[\s=]|$)")
+DIMENSIONS = re.compile(r"^(\d{2,4})\s*[x×]\s*(\d{2,4})$")
+RATIO = re.compile(r"^(\d{1,2})\s*:\s*(\d{1,2})$")
+
+
+class OptionError(ValueError):
+    pass
+
+
+@dataclass
+class Options:
+    n: int = 1
+    size: str = "1:1"  # an aspect ratio (16:9), a name (wide) or pixels (1344x768)
+    seed: int | None = None  # None: a new random seed for each image
+    quality: str = "balanced"
+    negative: str = ""
+    style: str = ""
+
+    def describe(self) -> str:
+        seed = "random" if self.seed is None else str(self.seed)
+        parts = [f"n={self.n}", f"size={self.size}", f"seed={seed}", f"quality={self.quality}"]
+        if self.style:
+            parts.append(f"style={self.style}")
+        if self.negative:
+            parts.append(f"no={self.negative!r}")
+        return " ".join(parts)
+
+    def to_json(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_json(cls, data: dict) -> Options:
+        known = {k: v for k, v in (data or {}).items() if k in cls.__dataclass_fields__}
+        try:
+            return set_values(cls(), known)
+        except OptionError:
+            return cls()
+
+
+def set_values(options: Options, values: dict[str, object]) -> Options:
+    """A copy of `options` with `values` (by name or alias) applied. Raises OptionError saying what's wrong."""
+    out = replace(options)
+    for raw_key, raw in values.items():
+        key = ALIASES.get(str(raw_key).lower().lstrip("-"))
+        if key is None:
+            raise OptionError(f"unknown option {raw_key!r}: use n, ar (or size), seed, quality, style or no")
+        value = str(raw).strip() if raw is not None else ""
+        if key == "n":
+            if not value.isdigit() or not 1 <= int(value) <= MAX_COUNT:
+                raise OptionError(f"n is how many images: 1 to {MAX_COUNT}")
+            out.n = int(value)
+        elif key == "size":
+            out.size = check_size(value)
+        elif key == "seed":
+            if value.lower() in ("random", "none", ""):
+                out.seed = None
+            elif value.isdigit() and int(value) < 2**63:
+                out.seed = int(value)
+            else:
+                raise OptionError("seed is a whole number, or random")
+        elif key == "quality":
+            if value.lower() not in QUALITIES:
+                raise OptionError(f"quality is {', '.join(QUALITIES)}")
+            out.quality = value.lower()
+        elif key == "style":
+            if value.lower() in ("none", "off", ""):
+                out.style = ""
+            elif value.lower() in STYLES:
+                out.style = value.lower()
+            else:
+                raise OptionError(f"style is one of {', '.join(STYLES)} (or none)")
+        elif key == "negative":
+            out.negative = "" if value.lower() in ("none", "off") else value
+    return out
+
+
+def check_size(value: str) -> str:
+    v = value.lower().replace(" ", "")
+    if v in SIZES:
+        return v
+    if RATIO.match(v):
+        w, h = (int(x) for x in RATIO.match(v).groups())
+        if w and h and 1 / 4 <= w / h <= 4:
+            return f"{w}:{h}"
+    m = DIMENSIONS.match(v)
+    if m:
+        w, h = (int(x) for x in m.groups())
+        if 256 <= w <= 2048 and 256 <= h <= 2048:
+            return f"{w}x{h}"
+        raise OptionError("a size in pixels is 256 to 2048 on each side, e.g. 1344x768")
+    raise OptionError(f"size is a ratio (16:9), pixels (1344x768) or one of {', '.join(SIZES)}")
+
+
+def parse(text: str, defaults: Options) -> tuple[str, Options]:
+    """The prompt without its flags, and the options for this request. Raises OptionError."""
+    matches = list(FLAG.finditer(text))
+    if not matches:
+        return text.strip(), defaults
+    prompt = text[: matches[0].start()]
+    values: dict[str, str] = {}
+    for i, m in enumerate(matches):
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        rest = text[m.end() : end].strip().lstrip("=").strip()
+        try:
+            words = shlex.split(rest)
+        except ValueError:
+            words = rest.split()
+        key = ALIASES[m.group(1).lower()]
+        if key == "negative":
+            values[key] = " ".join(words)
+        else:
+            if not words:
+                raise OptionError(f"--{m.group(1)} needs a value")
+            values[key] = words[0]
+            if len(words) > 1:  # words after a flag's value belong to the prompt
+                prompt += " " + " ".join(words[1:])
+    return prompt.strip(), set_values(defaults, values)
+
+
+def parse_assignments(text: str) -> dict[str, str]:
+    """`n=4 ar=16:9 no="blurry, text"` -> {"n": "4", "ar": "16:9", "no": "blurry, text"}."""
+    try:
+        words = shlex.split(text)
+    except ValueError as e:
+        raise OptionError(f"can't read {text!r}: {e}") from e
+    out = {}
+    for word in words:
+        key, sep, value = word.partition("=")
+        if not sep:
+            raise OptionError(f"write options as name=value, e.g. n=4 ar=16:9 (not {word!r})")
+        out[key] = value
+    return out
+
+
+def dimensions(size: str, megapixels: float, multiple: int = 16) -> tuple[int, int]:
+    """Width and height in pixels: from a ratio and the quality's megapixels, or exact pixels as given."""
+    m = DIMENSIONS.match(size)
+    if m:
+        w, h = (int(x) for x in m.groups())
+        return round_to(w, multiple), round_to(h, multiple)
+    ratio = SIZES.get(size, size)
+    w, h = (int(x) for x in ratio.split(":"))
+    area = megapixels * 1024 * 1024
+    width = math.sqrt(area * w / h)
+    return round_to(width, multiple), round_to(width * h / w, multiple)
+
+
+def round_to(value: float, multiple: int) -> int:
+    return max(multiple, round(value / multiple) * multiple)
+
+
+def replace_seed(options: Options, n: int | None = None) -> Options:
+    """The options with a random seed again (for /again and /vary), and optionally another count."""
+    return replace(options, seed=None, n=n or options.n)
+
+
+def styled(prompt: str, style: str) -> str:
+    return f"{prompt}, {STYLES[style]}" if style else prompt