@ahmedalbarghouti/farq 0.0.2 → 0.0.3

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,7 +91,7 @@ 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).
+- Visuals come from the diff only. A cheap model groups summary items into **up to 5** visual topics by intent (same feature → one image; truly unrelated domains → separate). File-overlap is the fallback if that grouping fails. UI markup gets a mockup attempt; everything else gets a small concept flowchart/diagram. Screenshots are capped at **1280×720** so content must fit the frame (no tall cut-off pages). If a topic is infeasible, it is skipped (still exit 0).
 - Generated compositions include 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).
@@ -141,22 +141,11 @@ If both `claude` and `opencode` are installed and nothing is configured, farq us
 
 Progress → **stderr**. Artifact → **stdout**.
 
-## Publishing notes (maintainers)
-
-Tag-triggered publish via GitHub Actions (npm provenance):
-
-```bash
-git tag v0.0.2
-git push origin v0.0.2
-```
-
-Requires repo secret `NPM_TOKEN`. Package name: `@ahmedalbarghouti/farq`.
-
 ## 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/index.js

@@ -87,6 +87,7 @@ async function run(type, opts) {
             : undefined;
     let imagePath = null;
     let images = [];
+    let imageMeta = [];
     if (imagesEnabled || (opts.before && opts.after)) {
         const visSpin = ui.stage("visual", provider.name);
         try {
@@ -105,6 +106,7 @@ async function run(type, opts) {
             });
             imagePath = visual.imagePath;
             images = visual.images;
+            imageMeta = visual.imageMeta;
             if (visual.warning) {
                 visSpin.succeed("visuals skipped");
                 ui.note(visual.warning);
@@ -126,10 +128,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 +149,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);
@@ -186,7 +190,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[]>;

package/dist/open-pr.js

@@ -1,5 +1,5 @@
 import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { tmpdir } from "node:os";
 import { execa } from "execa";
 import { fillPrTemplate, findPrTemplate } from "./template.js";
@@ -104,14 +104,19 @@ export async function openPullRequest(options) {
             reason: `Already on ${defaultBranch} — skipping PR create`,
         };
     }
-    let imageUrl = null;
+    const paths = options.imagePaths && options.imagePaths.length > 0
+        ? options.imagePaths
+        : options.imagePath
+            ? [options.imagePath]
+            : [];
+    let imageUrls = [];
     let warning;
-    if (options.imagePath) {
+    if (paths.length > 0) {
         try {
-            imageUrl = await uploadPrImage(cwd, options.imagePath, branch);
+            imageUrls = await uploadPrImages(cwd, paths, branch);
         }
         catch (err) {
-            warning = `Image upload failed — attach manually: ${options.imagePath} (${err instanceof Error ? err.message : String(err)})`;
+            warning = `Image upload failed — attach manually: ${paths.join(", ")} (${err instanceof Error ? err.message : String(err)})`;
         }
     }
     const template = findPrTemplate(cwd);
@@ -119,7 +124,11 @@ export async function openPullRequest(options) {
         template,
         summary: options.summary,
         bodyMarkdown: options.bodyMarkdown,
-        imageUrl,
+        imageUrl: imageUrls[0] ?? null,
+        images: imageUrls.map((url, i) => ({
+            url,
+            title: options.imageTitles?.[i],
+        })),
     });
     const dir = mkdtempSync(join(tmpdir(), "farq-pr-"));
     const bodyFile = join(dir, "body.md");
@@ -149,7 +158,8 @@ export async function openPullRequest(options) {
                 warning,
                 title,
                 body,
-                imageUrl,
+                imageUrl: imageUrls[0] ?? null,
+                imageUrls,
             };
         }
         const created = await gh(cwd, [
@@ -173,7 +183,8 @@ export async function openPullRequest(options) {
             warning,
             title,
             body,
-            imageUrl,
+            imageUrl: imageUrls[0] ?? null,
+            imageUrls,
         };
     }
     catch (err) {
@@ -225,8 +236,18 @@ export async function pruneOrphanedFarqAssets(cwd, keepTag) {
     }
     return deleted;
 }
-/** Best-effort: prerelease asset URL for the PNG. */
+/** Best-effort: prerelease asset URL for one PNG. */
 export async function uploadPrImage(cwd, imagePath, branch) {
+    const urls = await uploadPrImages(cwd, [imagePath], branch);
+    const url = urls[0];
+    if (!url)
+        throw new Error("no asset URL returned");
+    return url;
+}
+/** Best-effort: upload many PNGs to one prerelease; URLs in input order. */
+export async function uploadPrImages(cwd, imagePaths, branch) {
+    if (imagePaths.length === 0)
+        return [];
     const tag = assetTagForBranch(branch);
     try {
         await gh(cwd, ["release", "delete", tag, "--yes", "--cleanup-tag"], {
@@ -240,7 +261,7 @@ export async function uploadPrImage(cwd, imagePath, branch) {
         "release",
         "create",
         tag,
-        imagePath,
+        ...imagePaths,
         "--title",
         `farq assets (${branch})`,
         "--notes",
@@ -253,12 +274,17 @@ export async function uploadPrImage(cwd, imagePath, branch) {
         tag,
         "--json",
         "assets",
-        "--jq",
-        ".assets[0].url",
     ]);
-    const url = stdout.trim();
-    if (!url)
-        throw new Error("no asset URL returned");
+    const parsed = JSON.parse(stdout);
+    const assets = parsed.assets ?? [];
+    const urls = imagePaths.map((p) => {
+        const name = basename(p);
+        const hit = assets.find((a) => a.name === name);
+        if (!hit?.url) {
+            throw new Error(`no asset URL for ${name}`);
+        }
+        return hit.url;
+    });
     await pruneOrphanedFarqAssets(cwd, tag);
-    return url;
+    return urls;
 }

package/dist/render/pr.d.ts

@@ -1,7 +1,13 @@
 import type { ChangeSummary } from "../schema.js";
+export type PrImage = {
+    path: string;
+    title?: string;
+};
 export type RenderPrOptions = {
     summary: ChangeSummary;
+    /** @deprecated prefer images */
     imagePath?: string | null;
     imageAlt?: string;
+    images?: PrImage[];
 };
 export declare function renderPr(options: RenderPrOptions): string;

package/dist/render/pr.js

@@ -18,13 +18,27 @@ export function renderPr(options) {
         out.push("");
         out.push(overflow);
     }
-    if (options.imagePath) {
-        out.push("");
-        out.push("### Before / After");
-        out.push("");
-        const alt = options.imageAlt ?? "before / after";
-        out.push(`![${alt}](${options.imagePath})`);
-        if (!isHostedImageUrl(options.imagePath)) {
+    const images = normalizeImages(options);
+    if (images.length > 0) {
+        const anyLocal = images.some((img) => !isHostedImageUrl(img.path));
+        if (images.length === 1) {
+            out.push("");
+            out.push("### Before / After");
+            out.push("");
+            const alt = images[0].title ?? options.imageAlt ?? "before / after";
+            out.push(`![${alt}](${images[0].path})`);
+        }
+        else {
+            out.push("");
+            out.push("### Visuals");
+            for (const img of images) {
+                out.push("");
+                out.push(`#### ${img.title ?? "Before / After"}`);
+                out.push("");
+                out.push(`![${img.title ?? "before / after"}](${img.path})`);
+            }
+        }
+        if (anyLocal) {
             out.push("");
             out.push(LOCAL_IMAGE_NOTE);
         }
@@ -49,3 +63,11 @@ export function renderPr(options) {
     }
     return `${title}\n\n${out.join("\n").trim()}\n`;
 }
+function normalizeImages(options) {
+    if (options.images && options.images.length > 0)
+        return options.images;
+    if (options.imagePath) {
+        return [{ path: options.imagePath, title: options.imageAlt }];
+    }
+    return [];
+}

package/dist/template.d.ts

@@ -1,10 +1,16 @@
 import type { ChangeSummary } from "./schema.js";
 export declare function findPrTemplate(cwd: string): string | null;
+export type TemplateImage = {
+    url: string;
+    title?: string;
+};
 export declare function fillPrTemplate(options: {
     template: string | null;
     summary: ChangeSummary;
     bodyMarkdown: string;
+    /** @deprecated prefer images */
     imageUrl?: string | null;
+    images?: TemplateImage[];
 }): {
     title: string;
     body: string;

package/dist/template.js

@@ -19,23 +19,16 @@ export function findPrTemplate(cwd) {
 }
 export function fillPrTemplate(options) {
     const { title, overflow } = truncateTitle(options.summary.headline, GITHUB_TITLE_MAX);
+    const images = normalizeTemplateImages(options);
     let body = options.template?.trim() || "";
     if (!body) {
         body = options.bodyMarkdown;
         if (overflow)
             body = overflow + "\n\n" + body;
-        if (options.imageUrl) {
-            // Swap any non-http(s) image target (cache path, .farq/, etc.).
-            const re = /!\[([^\]]*)\]\((?!https?:\/\/)[^)]+\)/;
-            if (re.test(body)) {
-                body = body.replace(re, "![$1](" + options.imageUrl + ")");
-            }
-            else {
-                body =
-                    "### Before / After\n\n![before / after](" +
-                        options.imageUrl +
-                        ")\n\n" +
-                        body;
+        if (images.length > 0) {
+            body = replaceLocalImages(body, images);
+            if (!hasMarkdownImage(body)) {
+                body = renderImageMarkdown(images) + "\n\n" + body;
             }
             body = stripLocalImageNote(body);
         }
@@ -51,20 +44,48 @@ export function fillPrTemplate(options) {
     body = fillSection(body, /test\s*plan|testing|how to test/i, testPlan);
     if (overflow)
         body = overflow + "\n\n" + body;
-    if (options.imageUrl) {
-        if (/before\s*\/\s*after|screenshots?/i.test(body)) {
-            body = fillSection(body, /before\s*\/\s*after|screenshots?/i, "![before / after](" + options.imageUrl + ")");
+    if (images.length > 0) {
+        const md = renderImageMarkdown(images);
+        if (/before\s*\/\s*after|screenshots?|visuals?/i.test(body)) {
+            body = fillSection(body, /before\s*\/\s*after|screenshots?|visuals?/i, md.replace(/^###[^\n]+\n+/, "").trim());
         }
         else {
-            body +=
-                "\n\n### Before / After\n\n![before / after](" +
-                    options.imageUrl +
-                    ")\n";
+            body += "\n\n" + md + "\n";
         }
         body = stripLocalImageNote(body);
     }
     return { title, body };
 }
+function normalizeTemplateImages(options) {
+    if (options.images && options.images.length > 0)
+        return options.images;
+    if (options.imageUrl)
+        return [{ url: options.imageUrl }];
+    return [];
+}
+function hasMarkdownImage(body) {
+    return /!\[[^\]]*\]\([^)]+\)/.test(body);
+}
+function replaceLocalImages(body, images) {
+    let i = 0;
+    return body.replace(/!\[([^\]]*)\]\((?!https?:\/\/)[^)]+\)/g, (_m, alt) => {
+        const img = images[Math.min(i, images.length - 1)];
+        i += 1;
+        return `![${alt || img.title || "before / after"}](${img.url})`;
+    });
+}
+function renderImageMarkdown(images) {
+    if (images.length === 1) {
+        const alt = images[0].title ?? "before / after";
+        return `### Before / After\n\n![${alt}](${images[0].url})`;
+    }
+    const parts = ["### Visuals"];
+    for (const img of images) {
+        const alt = img.title ?? "before / after";
+        parts.push("", `#### ${alt}`, "", `![${alt}](${img.url})`);
+    }
+    return parts.join("\n");
+}
 function fillSection(template, heading, content) {
     const lines = template.split("\n");
     let inSection = false;

package/dist/visual/chrome.js

@@ -2,6 +2,7 @@ import { execa } from "execa";
 import { platform } from "node:os";
 import { join } from "node:path";
 import { resolveExecutable, ToolNotFoundError, } from "../tools.js";
+import { clampViewport } from "./viewport.js";
 const TIMEOUT_MS = 30_000;
 export class ChromeError extends Error {
     constructor(message) {
@@ -55,8 +56,10 @@ export function resolveChrome(env = process.env) {
 }
 export async function screenshotHtml(options) {
     const chrome = options.chromePath ?? resolveChrome();
-    const width = options.width ?? 1280;
-    const height = options.height ?? 900;
+    const { width, height } = clampViewport({
+        width: options.width,
+        height: options.height,
+    });
     try {
         await execa(chrome, [
             "--headless=new",

package/dist/visual/cluster.d.ts

@@ -0,0 +1,23 @@
+import type { ChangeItem, ChangeSummary } from "../schema.js";
+import type { Provider } from "../providers/index.js";
+export declare const MAX_VISUAL_TOPICS = 5;
+export type VisualTopic = {
+    id: number;
+    title: string;
+    items: ChangeItem[];
+    files: string[];
+};
+/**
+ * Prefer intent clustering via the cheap model; fall back to file-overlap.
+ * Same-theme items (one feature across many files) → one topic.
+ * Truly unrelated domains → separate topics (cap 5).
+ */
+export declare function clusterVisualTopics(summary: ChangeSummary, options?: {
+    provider?: Provider;
+    model?: string;
+    log?: (msg: string) => void;
+}): Promise<VisualTopic[]>;
+/** File-overlap union-find (fallback). Exported for tests. */
+export declare function clusterByFileOverlap(summary: ChangeSummary): VisualTopic[];
+/** Build topics from model JSON; null if invalid. Exported for tests. */
+export declare function topicsFromIntentJson(summary: ChangeSummary, raw: unknown): VisualTopic[] | null;

package/dist/visual/cluster.js

@@ -0,0 +1,180 @@
+import { extractJson } from "../extract-json.js";
+export const MAX_VISUAL_TOPICS = 5;
+/**
+ * Prefer intent clustering via the cheap model; fall back to file-overlap.
+ * Same-theme items (one feature across many files) → one topic.
+ * Truly unrelated domains → separate topics (cap 5).
+ */
+export async function clusterVisualTopics(summary, options) {
+    const items = summary.items;
+    if (items.length === 0)
+        return [];
+    if (items.length === 1) {
+        return [
+            {
+                id: 1,
+                title: items[0].title.slice(0, 80),
+                items,
+                files: uniqueFiles(items),
+            },
+        ];
+    }
+    if (options?.provider) {
+        try {
+            const ai = await clusterByIntent(summary, options.provider, options.model);
+            if (ai) {
+                options.log?.(`visual topics (intent): ${ai.length} — ${ai.map((t) => t.title).join("; ")}`);
+                return ai;
+            }
+            options.log?.("visual topic intent clustering failed; using file overlap");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            options.log?.(`visual topic intent clustering error: ${msg}`);
+        }
+    }
+    return clusterByFileOverlap(summary);
+}
+/** File-overlap union-find (fallback). Exported for tests. */
+export function clusterByFileOverlap(summary) {
+    const items = summary.items;
+    if (items.length === 0)
+        return [];
+    const parent = items.map((_, i) => i);
+    const find = (i) => parent[i] === i ? i : (parent[i] = find(parent[i]));
+    const union = (a, b) => {
+        parent[find(a)] = find(b);
+    };
+    for (let i = 0; i < items.length; i++) {
+        for (let j = i + 1; j < items.length; j++) {
+            const a = items[i];
+            const b = items[j];
+            if (a.files.length > 0 &&
+                b.files.length > 0 &&
+                filesOverlap(a.files, b.files)) {
+                union(i, j);
+            }
+        }
+    }
+    const groups = new Map();
+    for (let i = 0; i < items.length; i++) {
+        const root = find(i);
+        const list = groups.get(root) ?? [];
+        list.push(items[i]);
+        groups.set(root, list);
+    }
+    let clusters = [...groups.values()].map((groupItems, idx) => ({
+        id: idx + 1,
+        title: topicTitle(groupItems),
+        items: groupItems,
+        files: uniqueFiles(groupItems),
+    }));
+    while (clusters.length > MAX_VISUAL_TOPICS) {
+        clusters.sort((a, b) => a.items.length - b.items.length || a.files.length - b.files.length);
+        const smallest = clusters[0];
+        const next = clusters[1];
+        const rest = clusters.slice(2);
+        clusters = [
+            {
+                id: 0,
+                title: topicTitle([...smallest.items, ...next.items]),
+                items: [...smallest.items, ...next.items],
+                files: uniqueFiles([...smallest.items, ...next.items]),
+            },
+            ...rest,
+        ];
+    }
+    return finalizeTopics(clusters);
+}
+/** Build topics from model JSON; null if invalid. Exported for tests. */
+export function topicsFromIntentJson(summary, raw) {
+    const items = summary.items;
+    if (!raw || typeof raw !== "object")
+        return null;
+    const topics = raw.topics;
+    if (!Array.isArray(topics) || topics.length === 0)
+        return null;
+    if (topics.length > MAX_VISUAL_TOPICS)
+        return null;
+    const used = new Set();
+    const built = [];
+    for (const t of topics) {
+        if (!t || typeof t !== "object")
+            return null;
+        const title = String(t.title ?? "").trim();
+        const indices = t.item_indices;
+        if (!title || !Array.isArray(indices) || indices.length === 0)
+            return null;
+        const groupItems = [];
+        for (const idx of indices) {
+            if (typeof idx !== "number" || !Number.isInteger(idx))
+                return null;
+            if (idx < 0 || idx >= items.length || used.has(idx))
+                return null;
+            used.add(idx);
+            groupItems.push(items[idx]);
+        }
+        built.push({
+            id: built.length + 1,
+            title: title.slice(0, 80),
+            items: groupItems,
+            files: uniqueFiles(groupItems),
+        });
+    }
+    // Every item must appear exactly once.
+    if (used.size !== items.length)
+        return null;
+    return finalizeTopics(built);
+}
+async function clusterByIntent(summary, provider, model) {
+    const listed = summary.items
+        .map((item, i) => `${i}. [${item.category}] ${item.title} — ${item.description} (files: ${item.files.join(", ") || "none"})`)
+        .join("\n");
+    const prompt = `You group change-summary items into visual topics for before/after diagrams.
+
+Rules:
+- If items all advance the SAME headline/feature/story, return EXACTLY ONE topic with every item index — even across many files, docs, prompts, tests, and upload plumbing.
+- Example: clustering + pipeline + PR render + asset upload + README + prompt polish for "multi-image visuals" → one topic.
+- Only create multiple topics when a reviewer would treat them as separate product changes (e.g. a UI redesign AND an unrelated billing API).
+- Prompt/style tweaks, tests, and docs for a feature stay in that feature's topic.
+- Maximum ${MAX_VISUAL_TOPICS} topics. Prefer fewer; one is best when unsure.
+- Every item index must appear in exactly one topic. Use 0-based indices.
+- Topic titles: short, human, <=80 chars.
+
+Return JSON only:
+{"topics":[{"title":"...","item_indices":[0,1,2]}]}
+
+Headline: ${summary.headline}
+Overview: ${summary.overview}
+
+Items:
+${listed}
+`;
+    const raw = await provider.complete(prompt, { model });
+    const json = extractJson(raw);
+    return topicsFromIntentJson(summary, json);
+}
+function finalizeTopics(clusters) {
+    return clusters.map((c, i) => ({
+        ...c,
+        id: i + 1,
+        title: c.title.slice(0, 80),
+    }));
+}
+function topicTitle(items) {
+    if (items.length === 1)
+        return items[0].title;
+    if (items.length === 2)
+        return `${items[0].title}; ${items[1].title}`;
+    return `${items[0].title} (+${items.length - 1} more)`;
+}
+function uniqueFiles(items) {
+    return [...new Set(items.flatMap((i) => i.files))];
+}
+function filesOverlap(a, b) {
+    const set = new Set(a.map(normalizePath));
+    return b.some((f) => set.has(normalizePath(f)));
+}
+function normalizePath(p) {
+    return p.replaceAll("\\", "/").replace(/^\.\//, "");
+}

package/dist/visual/compose.d.ts

@@ -6,6 +6,8 @@ export type ComposeOptions = {
     afterPath: string;
     badge?: "generated preview" | "before / after";
     chromePath?: string;
+    /** Output PNG basename (default before-after.png). */
+    outFileName?: string;
 };
 export declare function buildComposeHtml(options: {
     beforeBase64: string;

package/dist/visual/compose.js

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { defaultOutDir } from "../paths.js";
 import { resolveChrome, screenshotHtml, ChromeError } from "./chrome.js";
+import { DEFAULT_VIEWPORT } from "./viewport.js";
 export function buildComposeHtml(options) {
     const { beforeBase64, afterBase64, badge } = options;
     return `<!doctype html>
@@ -43,16 +44,17 @@ export async function composeBeforeAfter(options) {
         afterBase64: after.toString("base64"),
         badge,
     });
-    const composePath = join(outDir, "compose.html");
+    const stem = (options.outFileName ?? "before-after.png").replace(/\.png$/i, "");
+    const composePath = join(outDir, `${stem}-compose.html`);
     writeFileSync(composePath, html, "utf8");
-    const outPng = join(outDir, "before-after.png");
+    const outPng = join(outDir, `${stem}.png`);
     const chromePath = options.chromePath ?? resolveChrome();
     await screenshotHtml({
         chromePath,
         url: pathToFileURL(composePath).href,
         outPath: outPng,
-        width: 1400,
-        height: 900,
+        width: DEFAULT_VIEWPORT.width,
+        height: DEFAULT_VIEWPORT.height,
     });
     return outPng;
 }

package/dist/visual/diagram.d.ts

@@ -14,4 +14,5 @@ export declare function generateDiagram(options: {
     outDir: string;
     model?: string;
     log?: (msg: string) => void;
+    filePrefix?: string;
 }): Promise<DiagramResult>;

package/dist/visual/diagram.js

@@ -1,15 +1,18 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { extractJson } from "../extract-json.js";
+import { VIEWPORT_MAX_HEIGHT, VIEWPORT_MAX_WIDTH } from "./viewport.js";
 export async function generateDiagram(options) {
     const prompt = `You create a conceptual before/after flowchart as one self-contained HTML document.
 
 This is the fallback visual when a pixel UI mockup is not appropriate (API, logic, docs, config, etc.). Prefer a small flowchart or labeled before/after boxes that explain the change at a glance.
 
 Rules:
-- Pure HTML/CSS, no libraries, no external requests, system fonts.
+- Pure HTML/CSS, no libraries, no external requests except optional @import fonts from fonts.googleapis.com or fonts.bunny.net.
 - Two labeled columns (Before / After) with simple boxes/arrows (flowchart style).
 - Concept-level only: field/endpoint/step names OK. NO code, NO syntax, NO JSON dumps, NO walls of text.
+- FRAME LIMIT (hard): the screenshot is exactly ${VIEWPORT_MAX_WIDTH}x${VIEWPORT_MAX_HEIGHT}px. Set html,body { margin:0; width:100%; height:100%; overflow:hidden }. The entire flowchart must fit in that frame with no scrolling and no clipped boxes or footer text. Prefer fewer/shorter steps over a tall diagram.
+- Visual craft: one clear composition, expressive typography, subtle atmospheric background (gradient or soft pattern), high contrast. Avoid purple-gradient clichés, neon glow, and cluttered sticker UI.
 - Include a small corner badge text: generated preview
 - If you truly cannot produce a faithful conceptual visual from the diff alone, return {"feasible": false, "reason": "..."}. Prefer a simple flowchart over declining.
 
@@ -30,7 +33,8 @@ ${options.diffText}
         return { feasible: false, reason: json.reason ?? "not feasible" };
     }
     mkdirSync(options.outDir, { recursive: true });
-    const htmlPath = join(options.outDir, "diagram.html");
+    const prefix = options.filePrefix ?? "";
+    const htmlPath = join(options.outDir, `${prefix}diagram.html`);
     writeFileSync(htmlPath, json.html, "utf8");
     return { feasible: true, htmlPath };
 }

package/dist/visual/mockup.d.ts

@@ -23,4 +23,6 @@ export declare function generateMockup(options: {
     outDir: string;
     model?: string;
     log?: (msg: string) => void;
+    /** Prefix for written HTML files (e.g. visual-1-). */
+    filePrefix?: string;
 }): Promise<MockupResult>;

package/dist/visual/mockup.js

@@ -1,18 +1,21 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { extractJson } from "../extract-json.js";
+import { DEFAULT_VIEWPORT, VIEWPORT_MAX_HEIGHT, VIEWPORT_MAX_WIDTH, clampViewport, } from "./viewport.js";
 export async function generateMockup(options) {
     const prompt = `You create faithful before/after HTML mockups from a git diff.
 
 Rules:
-- The diff contains exact before/after markup/styles. Emit two fully self-contained HTML documents (inline CSS, no external requests, system fonts) that render this exact markup with these exact styles.
+- The diff contains exact before/after markup/styles. Emit two fully self-contained HTML documents (inline CSS, no external requests) that render this exact markup with these exact styles.
 - Stub only the minimum: container width, placeholder text where dynamic props appear (realistic neutral placeholders).
 - Do not invent UI that is not present in the code.
 - Never show raw code listings.
+- FRAME LIMIT (hard): design for exactly ${VIEWPORT_MAX_WIDTH}x${VIEWPORT_MAX_HEIGHT}px. html/body must be width/height 100% with overflow:hidden. All content must fit in that single screen — no scrolling, no content cut off at the bottom. Prefer denser layout over tall pages.
+- Visual craft: one clear composition, strong typographic hierarchy, purposeful (non-default) web fonts via @import from fonts.googleapis.com or fonts.bunny.net if helpful, atmospheric background (subtle gradient or pattern — not flat single-color), high contrast for text. No purple-on-white clichés, no glow spam, no floating badge stickers on the mockup itself.
 - If you cannot render faithfully, return {"feasible": false, "reason": "..."}.
 
 Return JSON only:
-{"feasible": true, "before_html": "...", "after_html": "...", "viewport": {"width":1280,"height":900}}
+{"feasible": true, "before_html": "...", "after_html": "...", "viewport": {"width":${DEFAULT_VIEWPORT.width},"height":${DEFAULT_VIEWPORT.height}}}
 or {"feasible": false, "reason": "..."}
 
 Change summary context:
@@ -33,14 +36,15 @@ ${options.files
         return { feasible: false, reason: "missing before_html/after_html" };
     }
     mkdirSync(options.outDir, { recursive: true });
-    const beforePath = join(options.outDir, "before.html");
-    const afterPath = join(options.outDir, "after.html");
+    const prefix = options.filePrefix ?? "";
+    const beforePath = join(options.outDir, `${prefix}before.html`);
+    const afterPath = join(options.outDir, `${prefix}after.html`);
     writeFileSync(beforePath, json.before_html, "utf8");
     writeFileSync(afterPath, json.after_html, "utf8");
     return {
         feasible: true,
         beforePath,
         afterPath,
-        viewport: json.viewport,
+        viewport: clampViewport(json.viewport),
     };
 }

package/dist/visual/pipeline.d.ts

@@ -1,9 +1,14 @@
 import type { ChangeSummary } from "../schema.js";
 import type { Provider } from "../providers/index.js";
 import type { GatherDiffResult } from "../git.js";
+export type VisualImage = {
+    path: string;
+    title: string;
+};
 export type VisualPipelineResult = {
     imagePath: string | null;
     images: string[];
+    imageMeta: VisualImage[];
     softDegraded: boolean;
     warning?: string;
 };

package/dist/visual/pipeline.js

@@ -1,13 +1,15 @@
 import { copyFileSync, mkdirSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { gatherVisualFileContents } from "../git.js";
 import { decideGate } from "./gate.js";
 import { generateMockup } from "./mockup.js";
 import { generateDiagram } from "./diagram.js";
+import { clusterVisualTopics } from "./cluster.js";
 import { defaultOutDir } from "../paths.js";
 import { composeBeforeAfter, ChromeError } from "./compose.js";
 import { screenshotHtml, resolveChrome } from "./chrome.js";
+import { DEFAULT_VIEWPORT, clampViewport } from "./viewport.js";
 export async function runVisualPipeline(options) {
     const cwd = options.cwd ?? process.cwd();
     const outDir = resolve(cwd, options.outDir ?? defaultOutDir(cwd));
@@ -17,9 +19,8 @@ export async function runVisualPipeline(options) {
             log(msg);
     };
     if (options.noImages) {
-        return { imagePath: null, images: [], softDegraded: false };
+        return emptyResult(false);
     }
-    // Manual screenshots skip generation
     if (options.before && options.after) {
         try {
             mkdirSync(outDir, { recursive: true });
@@ -33,95 +34,180 @@ export async function runVisualPipeline(options) {
                 beforePath: beforeCopy,
                 afterPath: afterCopy,
                 badge: "before / after",
+                outFileName: "visual-1.png",
             });
-            return { imagePath: composed, images: [composed], softDegraded: false };
+            return singleResult(composed, "before / after");
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             throw new ChromeError(msg);
         }
     }
-    const gate = decideGate(options.diff.files);
-    vlog(`visual gate: ${gate}`);
-    if (gate === "none") {
-        return { imagePath: null, images: [], softDegraded: false };
-    }
     try {
         resolveChrome();
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         return {
-            imagePath: null,
-            images: [],
-            softDegraded: true,
+            ...emptyResult(true),
             warning: msg,
         };
     }
-    try {
-        if (gate === "mockup") {
-            const files = await gatherVisualFileContents(cwd, options.diff.files, options.diff.baseRef);
-            const mockup = await generateMockup({
-                provider: options.provider,
-                summary: options.summary,
-                files,
+    const topics = await clusterVisualTopics(options.summary, {
+        provider: options.provider,
+        model: options.modelCheap,
+        log: vlog,
+    });
+    vlog(`visual topics: ${topics.length}`);
+    if (topics.length === 0) {
+        return emptyResult(false);
+    }
+    const imageMeta = [];
+    const warnings = [];
+    for (const topic of topics) {
+        try {
+            const path = await renderTopic({
+                topic,
+                cwd,
                 outDir,
-                model: options.modelCheap,
-                log: vlog,
+                summary: options.summary,
+                diff: options.diff,
+                provider: options.provider,
+                modelCheap: options.modelCheap,
+                vlog,
             });
-            if (mockup.feasible) {
-                const beforePng = join(outDir, "before.png");
-                const afterPng = join(outDir, "after.png");
-                await screenshotHtml({
-                    url: pathToFileURL(mockup.beforePath).href,
-                    outPath: beforePng,
-                    width: mockup.viewport?.width,
-                    height: mockup.viewport?.height,
-                });
-                await screenshotHtml({
-                    url: pathToFileURL(mockup.afterPath).href,
-                    outPath: afterPng,
-                    width: mockup.viewport?.width,
-                    height: mockup.viewport?.height,
-                });
-                const composed = await composeBeforeAfter({
-                    cwd,
-                    outDir,
-                    beforePath: beforePng,
-                    afterPath: afterPng,
-                    badge: "generated preview",
-                });
-                return { imagePath: composed, images: [composed], softDegraded: false };
+            if (path) {
+                imageMeta.push({ path, title: topic.title });
             }
-            vlog(`mockup infeasible: ${mockup.reason}; trying diagram`);
         }
-        // diagram path (gate=diagram or mockup downgrade)
-        const diagram = await generateDiagram({
-            provider: options.provider,
-            summary: options.summary,
-            diffText: options.diff.diffText,
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            warnings.push(`topic "${topic.title}": ${msg}`);
+            vlog(`topic failed: ${msg}`);
+        }
+    }
+    if (imageMeta.length === 0) {
+        return {
+            ...emptyResult(warnings.length > 0),
+            warning: warnings[0],
+        };
+    }
+    return {
+        imagePath: imageMeta[0].path,
+        images: imageMeta.map((i) => i.path),
+        imageMeta,
+        softDegraded: warnings.length > 0,
+        warning: warnings.length > 0 ? warnings.join("; ") : undefined,
+    };
+}
+async function renderTopic(options) {
+    const { topic, cwd, outDir, provider, modelCheap, vlog } = options;
+    const prefix = `visual-${topic.id}-`;
+    const stem = `visual-${topic.id}`;
+    const topicSummary = scopeSummary(options.summary, topic);
+    const topicFiles = filterDiffFiles(options.diff.files, topic.files);
+    const gate = topicFiles.length > 0
+        ? decideGate(topicFiles)
+        : decideGate(options.diff.files);
+    vlog(`visual gate [${topic.id} ${topic.title}]: ${gate}`);
+    if (gate === "none")
+        return null;
+    if (gate === "mockup") {
+        const files = await gatherVisualFileContents(cwd, topicFiles.length > 0 ? topicFiles : options.diff.files, options.diff.baseRef);
+        const mockup = await generateMockup({
+            provider,
+            summary: topicSummary,
+            files,
             outDir,
-            model: options.modelCheap,
+            model: modelCheap,
             log: vlog,
+            filePrefix: prefix,
         });
-        if (!diagram.feasible) {
-            vlog(`diagram infeasible: ${diagram.reason}`);
-            return { imagePath: null, images: [], softDegraded: false };
+        if (mockup.feasible) {
+            const beforePng = join(outDir, `${prefix}before.png`);
+            const afterPng = join(outDir, `${prefix}after.png`);
+            const vp = clampViewport(mockup.viewport);
+            await screenshotHtml({
+                url: pathToFileURL(mockup.beforePath).href,
+                outPath: beforePng,
+                width: vp.width,
+                height: vp.height,
+            });
+            await screenshotHtml({
+                url: pathToFileURL(mockup.afterPath).href,
+                outPath: afterPng,
+                width: vp.width,
+                height: vp.height,
+            });
+            return composeBeforeAfter({
+                cwd,
+                outDir,
+                beforePath: beforePng,
+                afterPath: afterPng,
+                badge: "generated preview",
+                outFileName: `${stem}.png`,
+            });
         }
-        const outPng = join(outDir, "before-after.png");
-        await screenshotHtml({
-            url: pathToFileURL(diagram.htmlPath).href,
-            outPath: outPng,
-        });
-        return { imagePath: outPng, images: [outPng], softDegraded: false };
+        vlog(`mockup infeasible [${topic.id}]: ${mockup.reason}; trying diagram`);
     }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-            imagePath: null,
-            images: [],
-            softDegraded: true,
-            warning: msg,
-        };
+    const diagram = await generateDiagram({
+        provider,
+        summary: topicSummary,
+        diffText: scopeDiffText(options.diff.diffText, topic.files),
+        outDir,
+        model: modelCheap,
+        log: vlog,
+        filePrefix: prefix,
+    });
+    if (!diagram.feasible) {
+        vlog(`diagram infeasible [${topic.id}]: ${diagram.reason}`);
+        return null;
     }
+    const outPng = join(outDir, `${stem}.png`);
+    await screenshotHtml({
+        url: pathToFileURL(diagram.htmlPath).href,
+        outPath: outPng,
+        width: DEFAULT_VIEWPORT.width,
+        height: DEFAULT_VIEWPORT.height,
+    });
+    return outPng;
+}
+function scopeSummary(summary, topic) {
+    return {
+        ...summary,
+        headline: topic.title.slice(0, 140),
+        overview: topic.items.map((i) => i.description).join(" "),
+        items: topic.items,
+    };
+}
+function filterDiffFiles(files, topicFiles) {
+    if (topicFiles.length === 0)
+        return files;
+    const set = new Set(topicFiles.map((f) => f.replaceAll("\\", "/")));
+    return files.filter((f) => set.has(f.path.replaceAll("\\", "/")));
+}
+function scopeDiffText(diffText, topicFiles) {
+    if (topicFiles.length === 0 || !diffText)
+        return diffText;
+    // Keep hunks whose path header mentions a topic file; else full diff.
+    const norms = topicFiles.map((f) => f.replaceAll("\\", "/"));
+    const parts = diffText.split(/(?=^diff --git )/m);
+    const kept = parts.filter((p) => norms.some((f) => p.includes(f) || p.includes(basename(f))));
+    return kept.length > 0 ? kept.join("") : diffText;
+}
+function emptyResult(soft) {
+    return {
+        imagePath: null,
+        images: [],
+        imageMeta: [],
+        softDegraded: soft,
+    };
+}
+function singleResult(path, title) {
+    return {
+        imagePath: path,
+        images: [path],
+        imageMeta: [{ path, title }],
+        softDegraded: false,
+    };
 }

package/dist/visual/viewport.d.ts

@@ -0,0 +1,16 @@
+/** Hard screenshot frame — Chrome captures the window only, so HTML must fit. */
+export declare const VIEWPORT_MAX_WIDTH = 1280;
+export declare const VIEWPORT_MAX_HEIGHT = 720;
+export declare const DEFAULT_VIEWPORT: {
+    readonly width: 1280;
+    readonly height: 720;
+};
+export type ViewportSize = {
+    width: number;
+    height: number;
+};
+/** Clamp to max frame; invalid/missing values fall back to defaults. */
+export declare function clampViewport(input?: {
+    width?: number;
+    height?: number;
+} | null): ViewportSize;

package/dist/visual/viewport.js

@@ -0,0 +1,19 @@
+/** Hard screenshot frame — Chrome captures the window only, so HTML must fit. */
+export const VIEWPORT_MAX_WIDTH = 1280;
+export const VIEWPORT_MAX_HEIGHT = 720;
+export const DEFAULT_VIEWPORT = {
+    width: VIEWPORT_MAX_WIDTH,
+    height: VIEWPORT_MAX_HEIGHT,
+};
+/** Clamp to max frame; invalid/missing values fall back to defaults. */
+export function clampViewport(input) {
+    const width = clampDim(input?.width, VIEWPORT_MAX_WIDTH);
+    const height = clampDim(input?.height, VIEWPORT_MAX_HEIGHT);
+    return { width, height };
+}
+function clampDim(value, max) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return max;
+    }
+    return Math.min(Math.round(value), max);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmedalbarghouti/farq",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Turn git branch changes into paste-ready PR/Slack updates with optional before/after visuals",
   "type": "module",
   "engines": {