@ahmedalbarghouti/farq 0.0.2 → 0.1.0

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/providers/claude.d.ts

@@ -1,3 +1,4 @@
 import type { CompleteOptions } from "./fake.js";
+export declare const UNSUPPORTED_FLAG: RegExp;
 export declare function complete(prompt: string, options?: CompleteOptions): Promise<string>;
 export declare function isInstalled(): Promise<boolean>;

package/dist/providers/claude.js

@@ -1,58 +1,75 @@
 import { execa } from "execa";
 const TIMEOUT_MS = 120_000;
+/**
+ * farq only ever asks for JSON back, so the user's MCP servers, skills, hooks
+ * and project CLAUDE.md are pure startup cost — and a source of drift in the
+ * output. Skipping them roughly halves per-call latency.
+ */
+const FAST_ARGS = ["--strict-mcp-config", "--setting-sources", ""];
+/** Tried in order; each falls back to the next when the CLI rejects a flag. */
+const ARG_VARIANTS = [
+    FAST_ARGS,
+    [],
+    // Empty allowedTools hangs on some versions, so it stays the last resort.
+    ["--allowedTools", ""],
+];
+export const UNSUPPORTED_FLAG = /unknown option|unknown argument|unrecognized|allowedTools|setting-sources|strict-mcp-config/i;
 export async function complete(prompt, options = {}) {
     const baseArgs = ["-p", "--output-format", "json", "--max-turns", "1"];
     if (options.model)
         baseArgs.push("--model", options.model);
-    // Prefer without allowedTools first — empty allowedTools hangs/fails on some versions.
-    const attempts = [[...baseArgs], [...baseArgs, "--allowedTools", ""]];
     let lastErr;
-    for (const args of attempts) {
+    for (let i = 0; i < ARG_VARIANTS.length; i++) {
+        const canRetry = i < ARG_VARIANTS.length - 1;
+        const args = [...baseArgs, ...ARG_VARIANTS[i]];
+        let result;
         try {
-            const result = await execa("claude", args, {
+            result = await execa("claude", args, {
                 input: prompt,
                 timeout: TIMEOUT_MS,
                 reject: false,
                 stdout: "pipe",
                 stderr: "pipe",
             });
-            if (result.timedOut) {
-                throw new Error("claude did not respond — check that it's authenticated (`claude` login)");
-            }
-            const text = (result.stdout || result.stderr || "").trim();
-            if (!text && result.exitCode !== 0) {
-                throw new Error(`claude failed (exit ${result.exitCode}): ${(result.stderr || "no output").trim()}`);
-            }
-            try {
-                return parseClaudeOutput(text);
-            }
-            catch (parseErr) {
-                // Retry next arg set only when allowedTools looks unsupported
-                if (args.includes("--allowedTools") &&
-                    /allowedTools|unknown option|unexpected/i.test(`${result.stderr ?? ""} ${text}`)) {
-                    lastErr = parseErr;
-                    continue;
-                }
-                throw parseErr;
-            }
         }
         catch (err) {
             const e = err;
-            if (e.timedOut || /did not respond/i.test(e.message ?? "")) {
-                throw new Error("claude did not respond — check that it's authenticated (`claude` login)");
+            if (e.timedOut)
+                throw notResponding();
+            if (canRetry && UNSUPPORTED_FLAG.test(e.message ?? "")) {
+                lastErr = err;
+                continue;
             }
-            lastErr = err;
-            if (!args.includes("--allowedTools")) {
-                // try with allowedTools only if first attempt was a flag-related failure
-                const msg = e.message ?? "";
-                if (/unknown option|allowedTools/i.test(msg))
-                    continue;
-                throw err instanceof Error ? err : new Error(String(err));
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+        if (result.timedOut)
+            throw notResponding();
+        const text = (result.stdout || result.stderr || "").trim();
+        const diagnostics = `${result.stderr ?? ""} ${text}`;
+        if (!text && result.exitCode !== 0) {
+            const err = new Error(`claude failed (exit ${result.exitCode}): ${(result.stderr || "no output").trim()}`);
+            if (canRetry && UNSUPPORTED_FLAG.test(diagnostics)) {
+                lastErr = err;
+                continue;
             }
+            throw err;
+        }
+        try {
+            return parseClaudeOutput(text);
+        }
+        catch (parseErr) {
+            if (canRetry && UNSUPPORTED_FLAG.test(diagnostics)) {
+                lastErr = parseErr;
+                continue;
+            }
+            throw parseErr;
         }
     }
     throw lastErr instanceof Error ? lastErr : new Error("claude failed");
 }
+function notResponding() {
+    return new Error("claude did not respond — check that it's authenticated (`claude` login)");
+}
 function parseClaudeOutput(stdout) {
     try {
         const envelope = JSON.parse(stdout);

package/dist/providers/fake.d.ts

@@ -1,7 +1,10 @@
 import type { ChangeSummary } from "../schema.js";
 export declare const FAKE_SUMMARY: ChangeSummary;
-export declare const FAKE_BEFORE_HTML = "<!doctype html><html><body style=\"font-family:system-ui;padding:24px;background:#f6f6f6\">\n<main style=\"max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd\">\n  <h1 style=\"font-size:18px;margin:0 0 8px\">Order #1042</h1>\n  <p style=\"margin:0;color:#444\">Total: $48.00</p>\n</main></body></html>";
-export declare const FAKE_AFTER_HTML = "<!doctype html><html><body style=\"font-family:system-ui;padding:24px;background:#f6f6f6\">\n<main style=\"max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd\">\n  <h1 style=\"font-size:18px;margin:0 0 8px\">Order #1042</h1>\n  <p style=\"margin:0 0 8px;color:#444\">Total: $48.00</p>\n  <p style=\"margin:0;color:#0a7\">Refund status: pending</p>\n</main></body></html>";
+export declare const FAKE_MOCKUP_CSS = ".page{padding:32px;background:var(--fq-surface)}\n.card{max-width:340px;padding:24px;background:var(--fq-surface-alt);border:1px solid var(--fq-border);border-radius:var(--fq-radius)}\n.card h1{margin:0 0 8px;font-family:var(--fq-font-display);font-size:20px}\n.card p{margin:0 0 8px;color:var(--fq-text-muted)}\n.card p.status{margin:0;color:var(--fq-positive)}";
+export declare const FAKE_BEFORE_BODY = "<div class=\"page\"><div class=\"card\"><h1>Order #1042</h1><p>Total: $48.00</p></div></div>";
+export declare const FAKE_AFTER_BODY = "<div class=\"page\"><div class=\"card\"><h1>Order #1042</h1><p>Total: $48.00</p><p class=\"status\">Refund status: pending</p></div></div>";
+export declare const FAKE_DIAGRAM_CSS = ".cols{display:flex;gap:24px}\n.col{flex:1;padding:16px;border:1px solid var(--fq-border);border-radius:var(--fq-radius)}\n.step{padding:8px 12px;margin-bottom:8px;background:var(--fq-surface-alt);border-radius:var(--fq-radius-sm)}\n.step--new{background:var(--fq-accent-soft);color:var(--fq-accent)}";
+export declare const FAKE_DIAGRAM_BODY = "<div class=\"cols\"><div class=\"col\"><div class=\"step\">Fetch order</div><div class=\"step\">Return payload</div></div><div class=\"col\"><div class=\"step\">Fetch order</div><div class=\"step step--new\">Attach refund status</div><div class=\"step\">Return payload</div></div></div>";
 export type CompleteOptions = {
     model?: string;
 };

package/dist/providers/fake.js

@@ -18,25 +18,36 @@ export const FAKE_SUMMARY = {
     ],
     breaking_changes: [],
     visual_notes: "Show a simple status badge on the order card.",
+    visual_topics: [{ title: "Refund status on orders", item_indices: [0, 1] }],
 };
-export const FAKE_BEFORE_HTML = `<!doctype html><html><body style="font-family:system-ui;padding:24px;background:#f6f6f6">
-<main style="max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd">
-  <h1 style="font-size:18px;margin:0 0 8px">Order #1042</h1>
-  <p style="margin:0;color:#444">Total: $48.00</p>
-</main></body></html>`;
-export const FAKE_AFTER_HTML = `<!doctype html><html><body style="font-family:system-ui;padding:24px;background:#f6f6f6">
-<main style="max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd">
-  <h1 style="font-size:18px;margin:0 0 8px">Order #1042</h1>
-  <p style="margin:0 0 8px;color:#444">Total: $48.00</p>
-  <p style="margin:0;color:#0a7">Refund status: pending</p>
-</main></body></html>`;
+export const FAKE_MOCKUP_CSS = `.page{padding:32px;background:var(--fq-surface)}
+.card{max-width:340px;padding:24px;background:var(--fq-surface-alt);border:1px solid var(--fq-border);border-radius:var(--fq-radius)}
+.card h1{margin:0 0 8px;font-family:var(--fq-font-display);font-size:20px}
+.card p{margin:0 0 8px;color:var(--fq-text-muted)}
+.card p.status{margin:0;color:var(--fq-positive)}`;
+export const FAKE_BEFORE_BODY = `<div class="page"><div class="card"><h1>Order #1042</h1><p>Total: $48.00</p></div></div>`;
+export const FAKE_AFTER_BODY = `<div class="page"><div class="card"><h1>Order #1042</h1><p>Total: $48.00</p><p class="status">Refund status: pending</p></div></div>`;
+export const FAKE_DIAGRAM_CSS = `.cols{display:flex;gap:24px}
+.col{flex:1;padding:16px;border:1px solid var(--fq-border);border-radius:var(--fq-radius)}
+.step{padding:8px 12px;margin-bottom:8px;background:var(--fq-surface-alt);border-radius:var(--fq-radius-sm)}
+.step--new{background:var(--fq-accent-soft);color:var(--fq-accent)}`;
+export const FAKE_DIAGRAM_BODY = `<div class="cols"><div class="col"><div class="step">Fetch order</div><div class="step">Return payload</div></div><div class="col"><div class="step">Fetch order</div><div class="step step--new">Attach refund status</div><div class="step">Return payload</div></div></div>`;
 export async function complete(prompt, _options = {}) {
-    if (prompt.includes("before_html") || prompt.includes("feasible")) {
+    if (prompt.includes("before_body")) {
         return JSON.stringify({
             feasible: true,
-            before_html: FAKE_BEFORE_HTML,
-            after_html: FAKE_AFTER_HTML,
-            viewport: { width: 900, height: 700 },
+            css: FAKE_MOCKUP_CSS,
+            before_body: FAKE_BEFORE_BODY,
+            after_body: FAKE_AFTER_BODY,
+            stage_width: 620,
+        });
+    }
+    if (prompt.includes("flowchart")) {
+        return JSON.stringify({
+            feasible: true,
+            css: FAKE_DIAGRAM_CSS,
+            body: FAKE_DIAGRAM_BODY,
+            stage_width: 900,
         });
     }
     return JSON.stringify(FAKE_SUMMARY);

package/dist/providers/index.d.ts

@@ -19,4 +19,4 @@ export declare function detectProviders(): Promise<{
 }>;
 export declare function resolveProvider(options?: ResolveProviderOptions): Promise<Provider>;
 export declare function getProvider(name: ProviderName): Provider;
-export { FAKE_SUMMARY, FAKE_BEFORE_HTML, FAKE_AFTER_HTML } from "./fake.js";
+export { FAKE_SUMMARY, FAKE_MOCKUP_CSS, FAKE_BEFORE_BODY, FAKE_AFTER_BODY, FAKE_DIAGRAM_CSS, FAKE_DIAGRAM_BODY, } from "./fake.js";

package/dist/providers/index.js

@@ -37,4 +37,4 @@ export function getProvider(name) {
             return { name, complete: fake.complete };
     }
 }
-export { FAKE_SUMMARY, FAKE_BEFORE_HTML, FAKE_AFTER_HTML } from "./fake.js";
+export { FAKE_SUMMARY, FAKE_MOCKUP_CSS, FAKE_BEFORE_BODY, FAKE_AFTER_BODY, FAKE_DIAGRAM_CSS, FAKE_DIAGRAM_BODY, } from "./fake.js";

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/schema.d.ts

@@ -7,18 +7,32 @@ export declare const ChangeItemSchema: z.ZodObject<{
     why_it_matters: z.ZodOptional<z.ZodString>;
     files: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
+    description: string;
     files: string[];
     category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
     title: string;
-    description: string;
     why_it_matters?: string | undefined;
 }, {
+    description: string;
     category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
     title: string;
-    description: string;
     files?: string[] | undefined;
     why_it_matters?: string | undefined;
 }>;
+/**
+ * Grouping of items into visual topics, returned by the same call that writes
+ * the summary so the visual pipeline does not need its own round-trip.
+ */
+export declare const VisualTopicSchema: z.ZodObject<{
+    title: z.ZodString;
+    item_indices: z.ZodArray<z.ZodNumber, "many">;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    item_indices: number[];
+}, {
+    title: string;
+    item_indices: number[];
+}>;
 export declare const ChangeSummarySchema: z.ZodObject<{
     headline: z.ZodString;
     overview: z.ZodString;
@@ -29,46 +43,65 @@ export declare const ChangeSummarySchema: z.ZodObject<{
         why_it_matters: z.ZodOptional<z.ZodString>;
         files: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
+        description: string;
         files: string[];
         category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
         title: string;
-        description: string;
         why_it_matters?: string | undefined;
     }, {
+        description: string;
         category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
         title: string;
-        description: string;
         files?: string[] | undefined;
         why_it_matters?: string | undefined;
     }>, "many">;
     breaking_changes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     visual_notes: z.ZodOptional<z.ZodString>;
+    visual_topics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        item_indices: z.ZodArray<z.ZodNumber, "many">;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        item_indices: number[];
+    }, {
+        title: string;
+        item_indices: number[];
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     headline: string;
     overview: string;
     items: {
+        description: string;
         files: string[];
         category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
         title: string;
-        description: string;
         why_it_matters?: string | undefined;
     }[];
     breaking_changes: string[];
     visual_notes?: string | undefined;
+    visual_topics?: {
+        title: string;
+        item_indices: number[];
+    }[] | undefined;
 }, {
     headline: string;
     overview: string;
     items: {
+        description: string;
         category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
         title: string;
-        description: string;
         files?: string[] | undefined;
         why_it_matters?: string | undefined;
     }[];
     breaking_changes?: string[] | undefined;
     visual_notes?: string | undefined;
+    visual_topics?: {
+        title: string;
+        item_indices: number[];
+    }[] | undefined;
 }>;
 export type ChangeSummary = z.infer<typeof ChangeSummarySchema>;
 export type ChangeItem = z.infer<typeof ChangeItemSchema>;
+export type VisualTopicHint = z.infer<typeof VisualTopicSchema>;
 /** Compact schema description embedded in AI prompts. */
-export declare const CHANGE_SUMMARY_SCHEMA_PROMPT = "{\n  \"headline\": \"string <=140 \u2014 one-line summary (PR title)\",\n  \"overview\": \"string \u2014 1-3 sentences in requested tone\",\n  \"items\": [{\n    \"category\": \"feature|fix|improvement|refactor|chore|docs|perf|security\",\n    \"title\": \"string <=120\",\n    \"description\": \"string\",\n    \"why_it_matters\": \"string (optional; required for client tone)\",\n    \"files\": [\"string\"]\n  }],\n  \"breaking_changes\": [\"string\"],\n  \"visual_notes\": \"string (optional)\"\n}";
+export declare const CHANGE_SUMMARY_SCHEMA_PROMPT = "{\n  \"headline\": \"string <=140 \u2014 one-line summary (PR title)\",\n  \"overview\": \"string \u2014 1-3 sentences in requested tone\",\n  \"items\": [{\n    \"category\": \"feature|fix|improvement|refactor|chore|docs|perf|security\",\n    \"title\": \"string <=120\",\n    \"description\": \"string\",\n    \"why_it_matters\": \"string (optional; required for client tone)\",\n    \"files\": [\"string\"]\n  }],\n  \"breaking_changes\": [\"string\"],\n  \"visual_notes\": \"string (optional)\",\n  \"visual_topics\": [{\n    \"title\": \"string <=80 \u2014 human topic name\",\n    \"item_indices\": [0]\n  }]\n}";

package/dist/schema.js

@@ -16,12 +16,21 @@ export const ChangeItemSchema = z.object({
     why_it_matters: z.string().min(1).optional(),
     files: z.array(z.string()).default([]),
 });
+/**
+ * Grouping of items into visual topics, returned by the same call that writes
+ * the summary so the visual pipeline does not need its own round-trip.
+ */
+export const VisualTopicSchema = z.object({
+    title: z.string().min(1).max(80),
+    item_indices: z.array(z.number().int().nonnegative()).min(1),
+});
 export const ChangeSummarySchema = z.object({
     headline: z.string().min(1).max(140),
     overview: z.string().min(1),
     items: z.array(ChangeItemSchema).min(1),
     breaking_changes: z.array(z.string()).default([]),
     visual_notes: z.string().min(1).optional(),
+    visual_topics: z.array(VisualTopicSchema).optional(),
 });
 /** Compact schema description embedded in AI prompts. */
 export const CHANGE_SUMMARY_SCHEMA_PROMPT = `{
@@ -35,5 +44,9 @@ export const CHANGE_SUMMARY_SCHEMA_PROMPT = `{
     "files": ["string"]
   }],
   "breaking_changes": ["string"],
-  "visual_notes": "string (optional)"
+  "visual_notes": "string (optional)",
+  "visual_topics": [{
+    "title": "string <=80 — human topic name",
+    "item_indices": [0]
+  }]
 }`;

package/dist/summarize.js

@@ -1,5 +1,6 @@
 import { extractJson } from "./extract-json.js";
 import { CHANGE_SUMMARY_SCHEMA_PROMPT, ChangeSummarySchema, } from "./schema.js";
+import { MAX_VISUAL_TOPICS } from "./visual/cluster.js";
 export class SummarizeError extends Error {
     exitCode = 2;
     constructor(message) {
@@ -59,6 +60,12 @@ Rules:
 - Report only what the diff shows. Do not invent work.
 - ${toneRules}
 ${convention}
+visual_topics — how the items get grouped into before/after visuals:
+- Every item index must appear in exactly one topic. Use 0-based indices into your own items array.
+- If all items advance the SAME feature or story, return exactly ONE topic containing every index, even across many files, tests, docs and plumbing.
+- Only split when a reviewer would call them separate product changes (say, a UI redesign AND an unrelated billing API).
+- At most ${MAX_VISUAL_TOPICS} topics. Fewer is better; one is right when unsure.
+
 Schema:
 ${CHANGE_SUMMARY_SCHEMA_PROMPT}
 

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/ui/index.d.ts

@@ -1,2 +1,3 @@
 export { createUi, type Ui } from "./logger.js";
+export { labelFor, linesFor, type LineBank } from "./lines.js";
 export { brand, isInteractive } from "./theme.js";

package/dist/ui/index.js

@@ -1,2 +1,3 @@
 export { createUi } from "./logger.js";
+export { labelFor, linesFor } from "./lines.js";
 export { brand, isInteractive } from "./theme.js";