@ahmedalbarghouti/farq 0.0.2 → 0.1.0

package/README.md

@@ -5,13 +5,13 @@
 One command. No servers. No API keys. Auth stays with your local `claude` or `opencode` CLI.
 
 ```bash
-npx @ahmedalbarghouti/farq@0.0.2 pr           # title + markdown body (+ image when feasible)
+npx @ahmedalbarghouti/farq@0.0.3 pr           # title + markdown body (+ image when feasible)
 npx farq slack              # Slack mrkdwn daily update
 npx farq json               # structured JSON
 npx farq pr --open          # fill PR template + create with gh
 ```
 
-> **0.0.2** — PATH/`gh`/Chrome resolution, hosted-image PR body cleanup, orphaned asset prune. CLI surface (`pr` / `slack` / `json`) is the stable bit.
+> **0.0.3** — PATH/`gh`/Chrome resolution, hosted-image PR body cleanup, orphaned asset prune. CLI surface (`pr` / `slack` / `json`) is the stable bit.
 
 ## Install
 
@@ -23,7 +23,7 @@ farq --help
 Or run without installing:
 
 ```bash
-npx @ahmedalbarghouti/farq@0.0.2 --help
+npx @ahmedalbarghouti/farq@0.0.3 --help
 ```
 
 Generated images land in a **user cache directory outside the repo** by default (no `.gitignore` change needed). Use `--out .farq` if you want them in-tree.
@@ -76,7 +76,7 @@ farq pr --open
 
 1. Reads `.github` PR template if present and fills known sections  
 2. Infers title style from recent merged PR titles when `gh` works  
-3. Best-effort uploads the composed image as a prerelease asset and embeds the URL  
+3. Best-effort uploads composed image(s) as prerelease assets and embeds the URL(s)  
 4. Creates the PR with `gh pr create`, or **updates** title/body with `gh pr edit` if one already exists for the branch, then opens it in the browser  
 
 On the default branch (`main` / `master` / repo default), `--open` skips create and still prints the artifact. Titles are capped at GitHub's **256** character limit (overflow goes into the body).
@@ -91,12 +91,25 @@ Validated change summary plus an `images` array of produced file paths.
 
 ## Images (honesty policy)
 
-- Visuals come from the diff only. UI markup gets a mockup attempt; everything else gets a small concept flowchart/diagram. If the model cannot produce a faithful preview, **no image** is produced (still exit 0).
-- Generated compositions include a small **generated preview** badge.
+- Visuals come from the diff only. The summarize call also returns the grouping of items into **up to 5** visual topics by intent (same feature → one image; truly unrelated domains → separate), so no extra model round-trip is spent on it. A dedicated grouping call, then file-overlap, are the fallbacks. UI markup gets a mockup attempt; everything else gets a small concept flowchart. If a topic is infeasible, it is skipped (still exit 0).
+- Every visual is **1280×720** and carries a small **generated preview** badge.
 - Diagrams stay conceptual — no code dumps.
 - Missing Chrome / visual failure **soft-degrades** to text-only with a stderr warning (exit 0), unless you passed `--before`/`--after` (then hard-fail).
 - A local image path will not render on GitHub until the file is attached or uploaded. `--open` tries a best-effort upload (and rewrites stdout to the hosted URL).
 
+### Consistent visual style
+
+farq owns the page frame — background, header, Before/After labels, badge, typography and the colour palette. The model only fills in the two panel interiors, and it must draw every colour, font and radius from a fixed set of CSS custom properties (`--fq-accent`, `--fq-text-muted`, `--fq-surface`, …). The only literals it may use are colours the diff states outright. That is what keeps two runs on two branches looking like the same product.
+
+Two palettes ship today, `midnight` (default) and `daylight`:
+
+```bash
+farq pr --theme daylight
+farq pr --accent "#ff5722"
+```
+
+Content is measured and scaled to fit the frame after rendering, so a tall mockup shrinks instead of getting clipped, and the model is not asked to guess at pixel budgets.
+
 ## Config
 
 Precedence: **flags → project → global**.
@@ -111,10 +124,18 @@ Precedence: **flags → project → global**.
   "models": {
     "claudeCheap": "haiku",
     "opencodeCheap": "provider/model"
+  },
+  "visual": {
+    "theme": "midnight",
+    "accent": "#4dd0e1",
+    "maxTopics": 3,
+    "concurrency": 3
   }
 }
 ```
 
+`visual.maxTopics` caps how many images a run may generate (each costs one model call), and `visual.concurrency` is how many are generated at once. `visual.fontImport` can point at a webfont stylesheet; leaving it unset keeps rendering offline and fast.
+
 If both `claude` and `opencode` are installed and nothing is configured, farq uses **claude** and prints how to override (no interactive prompt).
 
 ## Flags
@@ -128,6 +149,9 @@ If both `claude` and `opencode` are installed and nothing is configured, farq us
 | `--no-images` | skip visuals |
 | `-o, --out` | image output dir (default: OS user cache, outside the repo) |
 | `--model-cheap` | cheap model id for visuals |
+| `--theme` | visual palette: `midnight` \| `daylight` |
+| `--accent` | override the theme accent colour |
+| `--max-visuals` | cap generated visuals (1–5) |
 | `-v, --verbose` | verbose logs (incl. `feasible: false` reasons) |
 | `--open` | (`pr` only) create PR with `gh` |
 
@@ -141,22 +165,36 @@ If both `claude` and `opencode` are installed and nothing is configured, farq us
 
 Progress → **stderr**. Artifact → **stdout**.
 
-## Publishing notes (maintainers)
+## Progress output
 
-Tag-triggered publish via GitHub Actions (npm provenance):
+Each stage is numbered, names what it is doing, and reports how long it took:
 
-```bash
-git tag v0.0.2
-git push origin v0.0.2
 ```
+farq ⠹ [2/3] summary · claude is naming things (hard part)… · 11s
+farq ✓ summarized with claude 12.4s
+farq ⠸ [3/3] visuals · claude is sketching the after… · 1/3 · Refund status badge · 8s
+farq ✓ 3 visuals ready 41.2s
+```
+
+Non-interactive terminals (CI, pipes) get one plain line per stage transition instead of a spinner.
+
+## Speed
+
+A `farq pr` run makes as few model calls as it can, and overlaps everything that does not depend on the model:
+
+- Provider detection, the diff and the `gh` title lookup all start at once.
+- Topic grouping rides along on the summarize response instead of being its own request.
+- File contents for the visuals are read while the summary is still being written.
+- Each visual is a **single** HTML document with one shared stylesheet — roughly half the tokens of emitting two standalone pages, and one Chrome screenshot instead of three.
+- Visuals for different topics are generated in parallel (`visual.concurrency`).
 
-Requires repo secret `NPM_TOKEN`. Package name: `@ahmedalbarghouti/farq`.
+If a run still feels slow, the lever with the most travel is `--model-cheap` (for example `haiku`), followed by `--max-visuals 1`.
 
 ## Repository ops
 
 - **CI** runs on every PR and on pushes to `main` (test + build + `--help` smoke).
 - **`main` is protected** — changes go through PRs; the `CI / test` check must pass.
-- **Releases** are tag-triggered: create `v0.0.2` (or later) after merge; the publish workflow needs a repo secret named `NPM_TOKEN` (npm automation/granular token with publish rights).
+- **Releases** are tag-triggered: create `v0.0.3` (or later) after merge; the publish workflow needs a repo secret named `NPM_TOKEN` (npm automation/granular token with publish rights).
 - **`--open` image assets:** uploaded as `farq-assets-<branch>` prereleases; farq deletes orphaned tags whose branch no longer has an open PR.
 
 ## Roadmap

package/dist/concurrency.d.ts

@@ -0,0 +1,2 @@
+/** Map over items with a bounded number of in-flight tasks, preserving order. */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/concurrency.js

@@ -0,0 +1,16 @@
+/** Map over items with a bounded number of in-flight tasks, preserving order. */
+export async function mapWithConcurrency(items, limit, fn) {
+    const max = Math.max(1, Math.floor(limit));
+    const results = new Array(items.length);
+    let cursor = 0;
+    async function worker() {
+        while (true) {
+            const index = cursor++;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(max, items.length) }, () => worker()));
+    return results;
+}

package/dist/config.d.ts

@@ -1,5 +1,20 @@
+import { type ThemeName } from "./visual/design.js";
 export type ProviderName = "claude" | "opencode" | "fake";
 export type ToneName = "technical" | "client";
+export type VisualConfig = {
+    /** Palette used by every generated mockup and diagram. */
+    theme?: ThemeName;
+    /** Override the single accent color within the chosen theme. */
+    accent?: string;
+    /** Optional webfont stylesheet; omitted keeps renders offline and fast. */
+    fontImport?: string;
+    fontSans?: string;
+    fontDisplay?: string;
+    /** Upper bound on generated visuals (each one costs a model call). */
+    maxTopics?: number;
+    /** How many visuals to generate at once. */
+    concurrency?: number;
+};
 export type FarqConfig = {
     provider?: ProviderName;
     tone?: ToneName;
@@ -7,6 +22,7 @@ export type FarqConfig = {
         claudeCheap?: string;
         opencodeCheap?: string;
     };
+    visual?: VisualConfig;
 };
 export type LoadConfigOptions = {
     cwd?: string;

package/dist/config.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { isThemeName } from "./visual/design.js";
 export function defaultGlobalDir() {
     return join(homedir(), ".config", "farq");
 }
@@ -21,12 +22,18 @@ export function mergeConfig(base, override) {
         ...base.models,
         ...stripUndefined(override.models ?? {}),
     };
+    const visual = {
+        ...base.visual,
+        ...stripUndefined(override.visual ?? {}),
+    };
     if (provider !== undefined)
         out.provider = provider;
     if (tone !== undefined)
         out.tone = tone;
     if (Object.keys(models).length > 0)
         out.models = models;
+    if (Object.keys(visual).length > 0)
+        out.visual = visual;
     return out;
 }
 function stripUndefined(obj) {
@@ -70,5 +77,23 @@ function sanitize(data) {
         if (Object.keys(models).length > 0)
             out.models = models;
     }
+    if (data.visual && typeof data.visual === "object") {
+        const visual = {};
+        if (isThemeName(data.visual.theme))
+            visual.theme = data.visual.theme;
+        for (const key of ["accent", "fontImport", "fontSans", "fontDisplay"]) {
+            const value = data.visual[key];
+            if (typeof value === "string" && value.trim())
+                visual[key] = value.trim();
+        }
+        for (const key of ["maxTopics", "concurrency"]) {
+            const value = data.visual[key];
+            if (typeof value === "number" && Number.isFinite(value) && value >= 1) {
+                visual[key] = Math.floor(value);
+            }
+        }
+        if (Object.keys(visual).length > 0)
+            out.visual = visual;
+    }
     return out;
 }

package/dist/git.d.ts

@@ -28,9 +28,13 @@ export type GatherDiffOptions = {
 };
 export declare function gatherDiff(options?: GatherDiffOptions): Promise<GatherDiffResult>;
 export declare function getFileAtRef(cwd: string, ref: string, filePath: string): Promise<string | null>;
-/** Size-capped before/after pairs for visual generation. */
-export declare function gatherVisualFileContents(cwd: string, files: DiffFile[], baseRef: string | null, budget?: number): Promise<Array<{
+export type VisualFile = {
     path: string;
     before: string;
     after: string;
-}>>;
+};
+/** Size-capped before/after pairs for visual generation. */
+export declare function gatherVisualFileContents(cwd: string, files: DiffFile[], baseRef: string | null, options?: {
+    budget?: number;
+    mode?: GatherDiffResult["mode"];
+}): Promise<VisualFile[]>;

package/dist/git.js

@@ -1,4 +1,7 @@
 import { execa } from "execa";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { mapWithConcurrency } from "./concurrency.js";
 export const SUMMARY_DIFF_BUDGET = 150_000;
 export const VISUAL_DIFF_BUDGET = 60_000;
 const GIT_TIMEOUT_MS = 30_000;
@@ -47,26 +50,40 @@ export async function getFileAtRef(cwd, ref, filePath) {
         return null;
     }
 }
+/** Cap on git subprocesses spawned to build visual context. */
+const MAX_VISUAL_FILES = 40;
+const VISUAL_READ_CONCURRENCY = 8;
 /** Size-capped before/after pairs for visual generation. */
-export async function gatherVisualFileContents(cwd, files, baseRef, budget = VISUAL_DIFF_BUDGET) {
+export async function gatherVisualFileContents(cwd, files, baseRef, options = {}) {
+    const budget = options.budget ?? VISUAL_DIFF_BUDGET;
+    const worktree = options.mode === "worktree";
+    const targets = files.slice(0, MAX_VISUAL_FILES);
+    const fetched = await mapWithConcurrency(targets, VISUAL_READ_CONCURRENCY, async (file) => {
+        const [before, after] = await Promise.all([
+            baseRef ? getFileAtRef(cwd, baseRef, file.path) : Promise.resolve(""),
+            // In worktree mode HEAD still holds the *old* content, so read from disk.
+            worktree
+                ? readWorktreeFile(cwd, file.path)
+                : getFileAtRef(cwd, "HEAD", file.path),
+        ]);
+        return {
+            path: file.path,
+            before: before ?? "",
+            after: after ?? (await readWorktreeFile(cwd, file.path)) ?? "",
+        };
+    });
     const out = [];
     let used = 0;
-    for (const file of files) {
+    for (const file of fetched) {
         if (used >= budget)
             break;
-        const before = baseRef
-            ? ((await getFileAtRef(cwd, baseRef, file.path)) ?? "")
-            : "";
-        const after = (await getFileAtRef(cwd, "HEAD", file.path)) ??
-            (await readWorktreeFile(cwd, file.path)) ??
-            "";
-        const chunk = before.length + after.length;
+        const chunk = file.before.length + file.after.length;
         if (used + chunk > budget && out.length > 0)
             break;
         out.push({
             path: file.path,
-            before: before.slice(0, budget - used),
-            after: after.slice(0, Math.max(0, budget - used - before.length)),
+            before: file.before.slice(0, budget - used),
+            after: file.after.slice(0, Math.max(0, budget - used - file.before.length)),
         });
         used += Math.min(chunk, budget - used);
     }
@@ -74,14 +91,11 @@ export async function gatherVisualFileContents(cwd, files, baseRef, budget = VIS
 }
 async function gatherRangeDiff(cwd, range, budget) {
     const [baseRef, headRef] = splitRange(range);
-    const nameStatus = await git(cwd, [
-        "diff",
-        "--name-status",
-        "--find-renames",
-        range,
+    const [nameStatus, patch, commits] = await Promise.all([
+        git(cwd, ["diff", "--name-status", "--find-renames", range]),
+        git(cwd, ["diff", "--find-renames", "--unified=5", range]),
+        listCommits(cwd, range),
     ]);
-    const patch = await git(cwd, ["diff", "--find-renames", "--unified=5", range]);
-    const commits = await listCommits(cwd, range);
     const files = parseNameStatus(nameStatus.stdout, patch.stdout);
     const { text, truncated } = capText(patch.stdout, budget);
     return {
@@ -96,14 +110,11 @@ async function gatherRangeDiff(cwd, range, budget) {
     };
 }
 async function gatherWorktreeDiff(cwd, budget) {
-    const nameStatus = await git(cwd, [
-        "diff",
-        "HEAD",
-        "--name-status",
-        "--find-renames",
+    const [nameStatus, patch, untracked] = await Promise.all([
+        git(cwd, ["diff", "HEAD", "--name-status", "--find-renames"]),
+        git(cwd, ["diff", "HEAD", "--find-renames", "--unified=5"]),
+        listUntracked(cwd),
     ]);
-    const patch = await git(cwd, ["diff", "HEAD", "--find-renames", "--unified=5"]);
-    const untracked = await listUntracked(cwd);
     const files = parseNameStatus(nameStatus.stdout, patch.stdout);
     let diffText = patch.stdout;
     for (const path of untracked) {
@@ -190,8 +201,6 @@ async function listUntracked(cwd) {
 }
 async function readWorktreeFile(cwd, filePath) {
     try {
-        const { readFileSync } = await import("node:fs");
-        const { join } = await import("node:path");
         return readFileSync(join(cwd, filePath), "utf8");
     }
     catch {

package/dist/index.js

@@ -1,22 +1,27 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { loadConfig, mergeConfig, } from "./config.js";
-import { gatherDiff } from "./git.js";
+import { gatherDiff, gatherVisualFileContents } from "./git.js";
 import { resolveProvider } from "./providers/index.js";
 import { summarize } from "./summarize.js";
 import { inferTitleConvention } from "./title.js";
 import { fetchRecentPrTitles, openPullRequest } from "./open-pr.js";
 import { runVisualPipeline } from "./visual/pipeline.js";
 import { ChromeError } from "./visual/chrome.js";
+import { DEFAULT_THEME, THEME_NAMES, isThemeName, resolveTheme, } from "./visual/design.js";
 import { renderPr } from "./render/pr.js";
 import { renderSlack } from "./render/slack.js";
 import { renderJson } from "./render/json.js";
-import { createUi } from "./ui/index.js";
+import { createUi, linesFor } from "./ui/index.js";
 import { defaultOutDir, displayImageRef } from "./paths.js";
 async function run(type, opts) {
     const cwd = process.cwd();
     const ui = createUi();
     const fileConfig = loadConfig({ cwd });
+    if (opts.theme && !isThemeName(opts.theme)) {
+        ui.note(`unknown theme "${opts.theme}" — using ${DEFAULT_THEME} (options: ${THEME_NAMES.join(", ")})`);
+    }
+    const maxVisuals = Number(opts.maxVisuals);
     const flagConfig = {
         provider: opts.provider,
         tone: opts.tone,
@@ -26,44 +31,60 @@ async function run(type, opts) {
                 opencodeCheap: opts.modelCheap,
             }
             : undefined,
+        visual: {
+            theme: isThemeName(opts.theme) ? opts.theme : undefined,
+            accent: opts.accent,
+            maxTopics: Number.isFinite(maxVisuals) && maxVisuals >= 1
+                ? Math.floor(maxVisuals)
+                : undefined,
+        },
     };
     const config = mergeConfig(fileConfig, flagConfig);
-    let provider;
-    try {
-        provider = await resolveProvider({
-            flag: config.provider,
-            config,
-            log: (msg) => ui.note(msg),
-        });
-    }
-    catch (err) {
-        ui.error(err instanceof Error ? err.message : String(err));
-        return 1;
-    }
     const tone = config.tone ?? "technical";
     const noImages = opts.noImages === true || opts.images === false;
+    const manualShots = Boolean(opts.before && opts.after);
     const imagesEnabled = type === "pr" ? !noImages : false;
+    const willVisual = imagesEnabled || manualShots;
+    ui.plan(2 + (willVisual ? 1 : 0) + (type === "pr" && opts.open ? 1 : 0));
+    // Provider detection, the diff and the `gh` title lookup are independent —
+    // start them together so the first model call is not waiting on subprocesses.
+    const providerNotes = [];
+    const providerPromise = resolveProvider({
+        flag: config.provider,
+        config,
+        log: (msg) => providerNotes.push(msg),
+    }).then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
+    const titlesPromise = type === "pr" ? fetchRecentPrTitles(cwd).catch(() => []) : null;
     let diff;
     const diffSpin = ui.stage("diff");
     try {
         diff = await gatherDiff({ cwd, range: opts.range });
-        diffSpin.succeed("diff ready");
+        diffSpin.succeed(`diff ready — ${describeDiff(diff.files.length)}`);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         diffSpin.fail(msg);
         return 1;
     }
-    let titleBlurb = "";
-    if (type === "pr") {
-        try {
-            const titles = await fetchRecentPrTitles(cwd);
-            titleBlurb = inferTitleConvention(titles).blurb;
-        }
-        catch {
-            // optional
-        }
+    const resolved = await providerPromise;
+    for (const note of providerNotes)
+        ui.note(note);
+    if (!resolved.ok) {
+        ui.error(resolved.error instanceof Error
+            ? resolved.error.message
+            : String(resolved.error));
+        return 1;
     }
+    const provider = resolved.value;
+    // Read the before/after file bodies while the model writes the summary.
+    const visualFiles = imagesEnabled && !manualShots
+        ? gatherVisualFileContents(cwd, diff.files, diff.baseRef, {
+            mode: diff.mode,
+        }).catch(() => [])
+        : undefined;
+    const titleBlurb = titlesPromise
+        ? inferTitleConvention(await titlesPromise).blurb
+        : "";
     let summary;
     const sumSpin = ui.stage("summarize", provider.name);
     try {
@@ -87,8 +108,50 @@ async function run(type, opts) {
             : undefined;
     let imagePath = null;
     let images = [];
-    if (imagesEnabled || (opts.before && opts.after)) {
-        const visSpin = ui.stage("visual", provider.name);
+    let imageMeta = [];
+    if (willVisual) {
+        const visSpin = ui.stage("topics", {
+            provider: provider.name,
+            label: "visuals",
+        });
+        const track = { total: 0, done: 0, current: "" };
+        const refresh = () => {
+            const parts = [];
+            if (track.total > 1)
+                parts.push(`${track.done}/${track.total}`);
+            if (track.current)
+                parts.push(track.current);
+            visSpin.detail(parts.join(" · ") || null);
+        };
+        const onProgress = (event) => {
+            switch (event.kind) {
+                case "topics":
+                    track.total = event.total;
+                    visSpin.setLines(linesFor("visual", provider.name));
+                    break;
+                // The rotating line already names the activity; the detail names the
+                // topic being worked on, plus a counter once there is more than one.
+                case "topic-start":
+                    track.current = shorten(event.title);
+                    visSpin.setLines(linesFor(event.mode, provider.name));
+                    break;
+                case "topic-fallback":
+                    track.current = shorten(event.title);
+                    visSpin.setLines(linesFor("diagram", provider.name));
+                    break;
+                case "topic-shot":
+                    track.current = shorten(event.title);
+                    visSpin.setLines(linesFor("shoot", provider.name));
+                    break;
+                case "topic-done":
+                    track.done = event.done;
+                    track.total = event.total;
+                    if (event.done === event.total)
+                        track.current = "";
+                    break;
+            }
+            refresh();
+        };
         try {
             const visual = await runVisualPipeline({
                 cwd,
@@ -97,20 +160,28 @@ async function run(type, opts) {
                 diff,
                 provider,
                 modelCheap: cheapModel,
-                noImages: noImages && !(opts.before && opts.after),
+                noImages: noImages && !manualShots,
                 before: opts.before,
                 after: opts.after,
+                theme: resolveTheme(config.visual ?? {}),
+                maxTopics: config.visual?.maxTopics,
+                concurrency: config.visual?.concurrency,
+                visualFiles,
                 verbose: opts.verbose,
                 log: opts.verbose ? (msg) => ui.note(msg) : () => undefined,
+                onProgress,
             });
             imagePath = visual.imagePath;
             images = visual.images;
-            if (visual.warning) {
+            imageMeta = visual.imageMeta;
+            if (visual.warning && images.length === 0) {
                 visSpin.succeed("visuals skipped");
                 ui.note(visual.warning);
             }
             else if (imagePath) {
-                visSpin.succeed("visuals ready");
+                visSpin.succeed(`${images.length} visual${images.length === 1 ? "" : "s"} ready`);
+                if (visual.warning)
+                    ui.note(visual.warning);
             }
             else {
                 visSpin.succeed("no visual (ok)");
@@ -118,7 +189,7 @@ async function run(type, opts) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            if (err instanceof ChromeError && opts.before && opts.after) {
+            if (err instanceof ChromeError && manualShots) {
                 visSpin.fail(msg);
                 return 1;
             }
@@ -126,10 +197,10 @@ async function run(type, opts) {
             ui.note(`${msg} (continuing without image)`);
         }
     }
-    const relImage = imagePath != null ? displayImageRef(cwd, imagePath) : null;
+    const prImages = (imageMeta.length > 0 ? imageMeta : images.map((p) => ({ path: p, title: "before / after" }))).map((img) => ({ path: displayImageRef(cwd, img.path), title: img.title }));
     let artifact = "";
     if (type === "pr") {
-        artifact = renderPr({ summary, imagePath: relImage });
+        artifact = renderPr({ summary, images: prImages });
     }
     else if (type === "slack") {
         artifact = renderSlack(summary);
@@ -147,6 +218,8 @@ async function run(type, opts) {
                     ? artifact.split("\n\n").slice(1).join("\n\n")
                     : artifact,
                 imagePath,
+                imagePaths: images,
+                imageTitles: imageMeta.map((m) => m.title),
             });
             if (result.skipped) {
                 openSpin.succeed(result.reason);
@@ -169,6 +242,13 @@ async function run(type, opts) {
     process.stdout.write(artifact);
     return 0;
 }
+function describeDiff(fileCount) {
+    return `${fileCount} file${fileCount === 1 ? "" : "s"}`;
+}
+function shorten(text, max = 28) {
+    const clean = text.replace(/\s+/g, " ").trim();
+    return clean.length <= max ? clean : `${clean.slice(0, max - 1)}…`;
+}
 function addShared(cmd) {
     return cmd
         .option("-r, --range <range>", "git range, e.g. main..feature")
@@ -179,6 +259,9 @@ function addShared(cmd) {
         .option("--no-images", "skip image generation/composition")
         .option("-o, --out <dir>", "output dir for images (default: user cache, outside the repo)")
         .option("--model-cheap <id>", "model for visual generation")
+        .option("--theme <name>", "visual palette: midnight | daylight")
+        .option("--accent <color>", "override the theme accent color")
+        .option("--max-visuals <n>", "cap generated visuals (1-5)")
         .option("-v, --verbose", "verbose logging", false);
 }
 async function main() {
@@ -186,7 +269,7 @@ async function main() {
     program
         .name("farq")
         .description("Turn git branch changes into paste-ready PR/Slack updates with optional before/after visuals")
-        .version("0.0.2");
+        .version("0.0.3");
     addShared(program
         .command("pr", { isDefault: true })
         .description("PR title + body markdown")

package/dist/open-pr.d.ts

@@ -10,6 +10,7 @@ export type OpenPrResult = {
     title: string;
     body: string;
     imageUrl?: string | null;
+    imageUrls?: string[];
 };
 /** Prerelease tag used to host a branch's composed PNG. */
 export declare function assetTagForBranch(branch: string): string;
@@ -26,11 +27,15 @@ export declare function openPullRequest(options: {
     summary: ChangeSummary;
     bodyMarkdown: string;
     imagePath?: string | null;
+    imagePaths?: string[];
+    imageTitles?: string[];
 }): Promise<OpenPrResult>;
 /**
  * Delete `farq-assets-*` prereleases whose branch no longer has an open PR.
  * Always keeps `keepTag` (the just-uploaded asset).
  */
 export declare function pruneOrphanedFarqAssets(cwd: string, keepTag: string): Promise<string[]>;
-/** Best-effort: prerelease asset URL for the PNG. */
+/** Best-effort: prerelease asset URL for one PNG. */
 export declare function uploadPrImage(cwd: string, imagePath: string, branch: string): Promise<string>;
+/** Best-effort: upload many PNGs to one prerelease; URLs in input order. */
+export declare function uploadPrImages(cwd: string, imagePaths: string[], branch: string): Promise<string[]>;