@ahmedalbarghouti/farq 0.0.2 → 0.1.0

package/dist/visual/design.js

@@ -0,0 +1,327 @@
+import { scopeCss } from "./css-scope.js";
+import { VIEWPORT_MAX_HEIGHT, VIEWPORT_MAX_WIDTH } from "./viewport.js";
+export const THEME_NAMES = ["midnight", "daylight"];
+export const DEFAULT_THEME = "midnight";
+/**
+ * Interior size of a rendered panel, in CSS pixels, measured from the shell
+ * below at the 1280x720 frame. The model designs against these so its output
+ * lands at roughly 1:1 instead of being scaled down into illegibility.
+ *
+ * Re-measure after changing the shell layout — `design.test.ts` checks these
+ * against a real Chrome render whenever Chrome is available.
+ */
+export const MOCKUP_PANEL = { width: 605, height: 604 };
+export const DIAGRAM_PANEL = { width: 1230, height: 626 };
+/** Widths the model designs against before farq scales the result to fit. */
+export const DEFAULT_MOCKUP_STAGE_WIDTH = 600;
+export const DEFAULT_DIAGRAM_STAGE_WIDTH = 1200;
+/** Bounds keep a stray stage_width from tanking legibility. */
+const MOCKUP_STAGE_BOUNDS = { min: 320, max: 900 };
+const DIAGRAM_STAGE_BOUNDS = { min: 480, max: 1600 };
+const MIDNIGHT = {
+    canvas: "#0d1117",
+    canvasAlt: "#141b24",
+    surface: "#161d26",
+    surfaceAlt: "#1e2731",
+    surfaceSunken: "#0a0e13",
+    border: "#28323e",
+    borderStrong: "#3a4756",
+    text: "#e8eef5",
+    textMuted: "#9aa8b8",
+    textFaint: "#68778a",
+    accent: "#4dd0e1",
+    accentInk: "#06222a",
+    accentSoft: "rgba(77,208,225,0.14)",
+    positive: "#5ddc9a",
+    positiveSoft: "rgba(93,220,154,0.14)",
+    warning: "#f0b429",
+    danger: "#ff7a7a",
+    dangerSoft: "rgba(255,122,122,0.14)",
+    shadow: "0 18px 44px rgba(0,0,0,0.45)",
+};
+const DAYLIGHT = {
+    canvas: "#f2efe8",
+    canvasAlt: "#e8e4da",
+    surface: "#ffffff",
+    surfaceAlt: "#f7f5f0",
+    surfaceSunken: "#ebe7de",
+    border: "#dcd6c9",
+    borderStrong: "#bdb4a2",
+    text: "#161a1f",
+    textMuted: "#5b6673",
+    textFaint: "#8b95a2",
+    accent: "#0f7f8f",
+    accentInk: "#ffffff",
+    accentSoft: "rgba(15,127,143,0.12)",
+    positive: "#12734c",
+    positiveSoft: "rgba(18,115,76,0.12)",
+    warning: "#a2670a",
+    danger: "#c0392b",
+    dangerSoft: "rgba(192,57,43,0.12)",
+    shadow: "0 18px 40px rgba(28,24,16,0.14)",
+};
+const THEMES = {
+    midnight: MIDNIGHT,
+    daylight: DAYLIGHT,
+};
+const SYSTEM_SANS = '"Inter","SF Pro Text",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif';
+const SYSTEM_DISPLAY = '"Inter Tight","Inter","SF Pro Display",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif';
+const SYSTEM_MONO = '"JetBrains Mono","SF Mono",ui-monospace,SFMono-Regular,Menlo,Consolas,monospace';
+export function isThemeName(value) {
+    return (typeof value === "string" && THEME_NAMES.includes(value));
+}
+export function resolveTheme(overrides = {}) {
+    const name = isThemeName(overrides.theme) ? overrides.theme : DEFAULT_THEME;
+    const tokens = { ...THEMES[name] };
+    if (overrides.accent && isSafeCssValue(overrides.accent)) {
+        tokens.accent = overrides.accent;
+        tokens.accentSoft = `color-mix(in srgb, ${overrides.accent} 16%, transparent)`;
+    }
+    return {
+        name,
+        tokens,
+        fontImport: overrides.fontImport,
+        fontSans: overrides.fontSans,
+        fontDisplay: overrides.fontDisplay,
+    };
+}
+/** Reject anything that could break out of a CSS declaration. */
+function isSafeCssValue(value) {
+    return value.length <= 64 && !/[;{}<>]/.test(value);
+}
+function tokenCss(theme) {
+    const t = theme.tokens;
+    const sans = theme.fontSans ?? SYSTEM_SANS;
+    const display = theme.fontDisplay ?? sans;
+    return `:root{
+--fq-canvas:${t.canvas};
+--fq-canvas-alt:${t.canvasAlt};
+--fq-surface:${t.surface};
+--fq-surface-alt:${t.surfaceAlt};
+--fq-surface-sunken:${t.surfaceSunken};
+--fq-border:${t.border};
+--fq-border-strong:${t.borderStrong};
+--fq-text:${t.text};
+--fq-text-muted:${t.textMuted};
+--fq-text-faint:${t.textFaint};
+--fq-accent:${t.accent};
+--fq-accent-ink:${t.accentInk};
+--fq-accent-soft:${t.accentSoft};
+--fq-positive:${t.positive};
+--fq-positive-soft:${t.positiveSoft};
+--fq-warning:${t.warning};
+--fq-danger:${t.danger};
+--fq-danger-soft:${t.dangerSoft};
+--fq-shadow:${t.shadow};
+--fq-radius-sm:6px;
+--fq-radius:10px;
+--fq-radius-lg:16px;
+--fq-space:8px;
+--fq-font-sans:${sans};
+--fq-font-display:${display};
+--fq-font-mono:${SYSTEM_MONO};
+}`;
+}
+/**
+ * The exact vocabulary the model is allowed to use. Keeping this in one place
+ * is what makes successive runs look like the same product.
+ */
+export const STYLE_CONTRACT = `Design tokens (CSS custom properties already defined — use them, do not redefine them):
+- Colors: var(--fq-canvas), var(--fq-canvas-alt), var(--fq-surface), var(--fq-surface-alt), var(--fq-surface-sunken), var(--fq-border), var(--fq-border-strong), var(--fq-text), var(--fq-text-muted), var(--fq-text-faint), var(--fq-accent), var(--fq-accent-ink) (text on accent), var(--fq-accent-soft), var(--fq-positive), var(--fq-positive-soft), var(--fq-warning), var(--fq-danger), var(--fq-danger-soft)
+- Type: var(--fq-font-display) for headings, var(--fq-font-sans) for body, var(--fq-font-mono) for identifiers
+- Shape: var(--fq-radius-sm), var(--fq-radius), var(--fq-radius-lg), var(--fq-shadow)
+
+Style rules (hard):
+- Every color you choose MUST be one of the variables above. The only exception is a color the diff states literally (e.g. the code sets #ff5722) — then use that literal value.
+- Do not set font-family to anything except the three variables. Do not @import fonts. Do not reference external URLs, images, or scripts.
+- Do not add gradients, glows, blurs, or decorative background art. The page frame, background, header and badge are supplied by farq — do not recreate them.
+- Use exactly one accent color for emphasis; neutrals carry the rest.
+- Legal pairings only: text on a surface is var(--fq-text) or var(--fq-text-muted); text on var(--fq-accent-soft) is var(--fq-accent); text on var(--fq-accent) is var(--fq-accent-ink). Never put muted or faint text on a colored fill.
+- Spacing in multiples of 4px. Body text >= 13px.
+- No raw code listings, no JSON dumps, no lorem ipsum. Placeholder copy must read like real product data.`;
+export function clampStageWidth(input, kind = "mockup") {
+    const bounds = kind === "diagram" ? DIAGRAM_STAGE_BOUNDS : MOCKUP_STAGE_BOUNDS;
+    const fallback = kind === "diagram"
+        ? DEFAULT_DIAGRAM_STAGE_WIDTH
+        : DEFAULT_MOCKUP_STAGE_WIDTH;
+    const raw = input?.width;
+    if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) {
+        return { width: fallback };
+    }
+    return {
+        width: Math.min(bounds.max, Math.max(bounds.min, Math.round(raw))),
+    };
+}
+/**
+ * Measures each stage at its natural size and scales it to fit its viewport.
+ * This is why the prompts no longer need to threaten the model about overflow:
+ * content that is too tall shrinks instead of getting clipped.
+ *
+ * Short content is first stretched to the panel's aspect ratio so a mockup
+ * reads as a full screen rather than a floating card on empty background.
+ */
+const FIT_SCRIPT = `(function(){
+  function fit(){
+    var stages=document.querySelectorAll('.fq-stage');
+    for(var i=0;i<stages.length;i++){
+      var s=stages[i],vp=s.parentElement;
+      if(!vp)continue;
+      s.style.transform='none';
+      var aw=vp.clientWidth,ah=vp.clientHeight;
+      if(aw>0&&ah>0){
+        var natural=s.offsetWidth||aw;
+        s.style.minHeight=(natural*(ah/aw))+'px';
+      }
+      var w=Math.max(s.scrollWidth,s.offsetWidth,1);
+      var h=Math.max(s.scrollHeight,s.offsetHeight,1);
+      var maxK=s.getAttribute('data-grow')==='1'?1.8:1;
+      var k=Math.min(aw/w,ah/h,maxK);
+      if(!isFinite(k)||k<=0)k=1;
+      s.style.transformOrigin='top left';
+      s.style.transform='translate('+((aw-w*k)/2)+'px,'+((ah-h*k)/2)+'px) scale('+k+')';
+      s.setAttribute('data-fit',aw+'x'+ah+'@'+k.toFixed(3));
+    }
+  }
+  fit();
+  document.addEventListener('DOMContentLoaded',fit);
+  window.addEventListener('load',fit);
+  if(document.fonts&&document.fonts.ready)document.fonts.ready.then(fit);
+})();`;
+function shellCss(theme) {
+    return `${theme.fontImport ? `@import url("${theme.fontImport}");\n` : ""}${tokenCss(theme)}
+*,*::before,*::after{box-sizing:border-box}
+html,body{margin:0;padding:0;width:${VIEWPORT_MAX_WIDTH}px;height:${VIEWPORT_MAX_HEIGHT}px;overflow:hidden}
+body{background:var(--fq-canvas);color:var(--fq-text);font-family:var(--fq-font-sans);
+  font-size:14px;line-height:1.45;-webkit-font-smoothing:antialiased}
+.fq-frame{display:flex;flex-direction:column;width:100%;height:100%;padding:20px 24px 24px}
+.fq-head{display:flex;align-items:center;gap:12px;height:34px;flex:0 0 auto;margin-bottom:14px}
+.fq-title{font-family:var(--fq-font-display);font-size:15px;font-weight:600;letter-spacing:-0.01em;
+  color:var(--fq-text);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.fq-rule{flex:1 1 auto;height:1px;background:var(--fq-border)}
+.fq-badge{flex:0 0 auto;font-size:10px;font-weight:600;letter-spacing:0.08em;text-transform:uppercase;
+  color:var(--fq-text-faint);border:1px solid var(--fq-border);border-radius:999px;padding:4px 10px}
+.fq-body{flex:1 1 auto;min-height:0;display:grid;gap:18px}
+.fq-body--split{grid-template-columns:1fr 1fr}
+.fq-body--single{grid-template-columns:1fr}
+.fq-panel{display:flex;flex-direction:column;min-height:0;min-width:0}
+.fq-label{display:flex;align-items:center;gap:8px;flex:0 0 auto;margin-bottom:8px;
+  font-size:10px;font-weight:700;letter-spacing:0.1em;text-transform:uppercase;color:var(--fq-text-faint)}
+.fq-label::after{content:"";flex:1 1 auto;height:1px;background:var(--fq-border)}
+.fq-panel--after .fq-label{color:var(--fq-accent)}
+.fq-panel--after .fq-label::after{background:var(--fq-accent-soft)}
+.fq-viewport{position:relative;flex:1 1 auto;min-height:0;overflow:hidden;
+  background:var(--fq-canvas-alt);border:1px solid var(--fq-border);border-radius:var(--fq-radius);
+  box-shadow:var(--fq-shadow)}
+.fq-stage{position:absolute;top:0;left:0;transform-origin:top left;display:flex;flex-direction:column}
+.fq-stage>*{flex:1 1 auto}
+.fq-root{background:var(--fq-surface);color:var(--fq-text);font-family:var(--fq-font-sans)}`;
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function document_(options) {
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8" />
+<title>${escapeHtml(options.title)}</title>
+<style>${shellCss(options.theme)}</style>
+<style>${options.extraCss}</style>
+</head>
+<body>
+${options.body}
+<script>${FIT_SCRIPT}</script>
+</body></html>`;
+}
+/**
+ * `grow` lets a diagram scale past 1:1 to fill the frame. Mockups stay capped
+ * at 1:1 so they read as a screenshot rather than a zoomed-in one.
+ */
+function stage(className, width, body, grow = false) {
+    const growAttr = grow ? ' data-grow="1"' : "";
+    return `<div class="fq-viewport"><div class="fq-stage" style="width:${width}px"${growAttr}><div class="${className}">${body}</div></div></div>`;
+}
+export const PREVIEW_BADGE = "generated preview";
+export function buildMockupDocument(input) {
+    const width = clampStageWidth({ width: input.stageWidth }, "mockup").width;
+    const extraCss = [
+        input.css ?? "",
+        scopeCss(input.beforeCss ?? "", ".fq-panel--before"),
+        scopeCss(input.afterCss ?? "", ".fq-panel--after"),
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const body = `<div class="fq-frame">
+  <header class="fq-head">
+    <span class="fq-title">${escapeHtml(input.title)}</span>
+    <span class="fq-rule"></span>
+    <span class="fq-badge">${escapeHtml(input.badge ?? PREVIEW_BADGE)}</span>
+  </header>
+  <div class="fq-body fq-body--split">
+    <section class="fq-panel fq-panel--before">
+      <div class="fq-label">Before</div>
+      ${stage("fq-root", width, input.beforeBody)}
+    </section>
+    <section class="fq-panel fq-panel--after">
+      <div class="fq-label">After</div>
+      ${stage("fq-root", width, input.afterBody)}
+    </section>
+  </div>
+</div>`;
+    return document_({
+        theme: input.theme,
+        title: input.title,
+        extraCss,
+        body,
+    });
+}
+export function buildDiagramDocument(input) {
+    const width = clampStageWidth({ width: input.stageWidth }, "diagram").width;
+    const body = `<div class="fq-frame">
+  <header class="fq-head">
+    <span class="fq-title">${escapeHtml(input.title)}</span>
+    <span class="fq-rule"></span>
+    <span class="fq-badge">${escapeHtml(input.badge ?? PREVIEW_BADGE)}</span>
+  </header>
+  <div class="fq-body fq-body--single">
+    <section class="fq-panel">
+      ${stage("fq-diagram", width, input.body, true)}
+    </section>
+  </div>
+</div>`;
+    return document_({
+        theme: input.theme,
+        title: input.title,
+        extraCss: `.fq-diagram{display:flex;flex-direction:column;justify-content:center;background:transparent;color:var(--fq-text);font-family:var(--fq-font-sans);padding:8px}\n${input.css ?? ""}`,
+        body,
+    });
+}
+/** Frame for user-supplied before/after PNGs — same chrome as generated visuals. */
+export function buildComposeDocument(input) {
+    const body = `<div class="fq-frame">
+  <header class="fq-head">
+    <span class="fq-title">${escapeHtml(input.title)}</span>
+    <span class="fq-rule"></span>
+    <span class="fq-badge">${escapeHtml(input.badge ?? "before / after")}</span>
+  </header>
+  <div class="fq-body fq-body--split">
+    <section class="fq-panel fq-panel--before">
+      <div class="fq-label">Before</div>
+      <div class="fq-viewport fq-shot"><img alt="Before" src="data:image/png;base64,${input.beforeBase64}" /></div>
+    </section>
+    <section class="fq-panel fq-panel--after">
+      <div class="fq-label">After</div>
+      <div class="fq-viewport fq-shot"><img alt="After" src="data:image/png;base64,${input.afterBase64}" /></div>
+    </section>
+  </div>
+</div>`;
+    return document_({
+        theme: input.theme,
+        title: input.title,
+        extraCss: `.fq-shot{display:flex;align-items:center;justify-content:center;background:var(--fq-surface-sunken)}
+.fq-shot img{max-width:100%;max-height:100%;width:auto;height:auto;display:block}`,
+        body,
+    });
+}

package/dist/visual/diagram.d.ts

@@ -1,5 +1,6 @@
 import type { ChangeSummary } from "../schema.js";
 import type { Provider } from "../providers/index.js";
+import { type Theme } from "./design.js";
 export type DiagramResult = {
     feasible: true;
     htmlPath: string;
@@ -7,11 +8,18 @@ export type DiagramResult = {
     feasible: false;
     reason: string;
 };
+export declare function buildDiagramPrompt(options: {
+    summary: ChangeSummary;
+    diffText: string;
+}): string;
 export declare function generateDiagram(options: {
     provider: Provider;
     summary: ChangeSummary;
     diffText: string;
     outDir: string;
     model?: string;
+    theme?: Theme;
+    title?: string;
     log?: (msg: string) => void;
+    filePrefix?: string;
 }): Promise<DiagramResult>;

package/dist/visual/diagram.js

@@ -1,21 +1,30 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { extractJson } from "../extract-json.js";
-export async function generateDiagram(options) {
-    const prompt = `You create a conceptual before/after flowchart as one self-contained HTML document.
+import { DEFAULT_DIAGRAM_STAGE_WIDTH, DIAGRAM_PANEL, STYLE_CONTRACT, buildDiagramDocument, resolveTheme, } from "./design.js";
+export function buildDiagramPrompt(options) {
+    return `You explain a code change as a conceptual before/after flowchart.
+
+This is the fallback when there is no pixel UI to show (API, logic, config, docs). farq supplies the page frame, header, badge and automatic scale-to-fit — you supply only the diagram body and its CSS.
+
+The diagram renders into a ${DIAGRAM_PANEL.width}x${DIAGRAM_PANEL.height}px box. Fill it: this is a wide, short canvas, so lay the two columns out side by side and let them breathe.
 
-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.
+Produce:
+- "body": an HTML fragment with two labelled columns (Before / After) of boxes and arrows. No <html>, <head>, <body>, <style> or <script> tags.
+- "css": the stylesheet for that fragment.
+- "stage_width": the pixel width you designed against (${DEFAULT_DIAGRAM_STAGE_WIDTH} is a good default).
 
-Rules:
-- Pure HTML/CSS, no libraries, no external requests, system fonts.
-- 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.
-- 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.
+Content rules:
+- Concept level only: step, field and endpoint names are fine. No code, no syntax, no JSON dumps, no paragraphs.
+- At most 5 boxes per column, at most 8 words per box.
+- Make the delta obvious: mark what is new or changed with the accent color, and keep unchanged steps neutral.
+- Draw arrows with CSS borders or plain characters. No SVG sprites, no external assets.
+
+${STYLE_CONTRACT}
 
 Return JSON only:
-{"feasible": true, "html": "..."}
-or {"feasible": false, "reason": "..."}
+{"feasible":true,"css":"...","body":"...","stage_width":${DEFAULT_DIAGRAM_STAGE_WIDTH}}
+or {"feasible":false,"reason":"..."} — prefer a simple flowchart over declining.
 
 Change summary:
 ${JSON.stringify(options.summary, null, 2)}
@@ -23,14 +32,27 @@ ${JSON.stringify(options.summary, null, 2)}
 Diff:
 ${options.diffText}
 `;
+}
+export async function generateDiagram(options) {
+    const prompt = buildDiagramPrompt({
+        summary: options.summary,
+        diffText: options.diffText,
+    });
     const raw = await options.provider.complete(prompt, { model: options.model });
     const json = extractJson(raw);
-    if (!json.feasible || !json.html) {
+    if (!json.feasible || !json.body) {
         options.log?.(json.reason ?? "diagram not feasible");
         return { feasible: false, reason: json.reason ?? "not feasible" };
     }
+    const html = buildDiagramDocument({
+        theme: options.theme ?? resolveTheme(),
+        title: options.title ?? options.summary.headline,
+        css: json.css,
+        body: json.body,
+        stageWidth: json.stage_width,
+    });
     mkdirSync(options.outDir, { recursive: true });
-    const htmlPath = join(options.outDir, "diagram.html");
-    writeFileSync(htmlPath, json.html, "utf8");
+    const htmlPath = join(options.outDir, `${options.filePrefix ?? ""}diagram.html`);
+    writeFileSync(htmlPath, html, "utf8");
     return { feasible: true, htmlPath };
 }

package/dist/visual/mockup.d.ts

@@ -1,26 +1,31 @@
 import type { ChangeSummary } from "../schema.js";
 import type { Provider } from "../providers/index.js";
+import { type Theme } from "./design.js";
 export type MockupResult = {
     feasible: true;
-    beforePath: string;
-    afterPath: string;
-    viewport?: {
-        width: number;
-        height: number;
-    };
+    htmlPath: string;
 } | {
     feasible: false;
     reason: string;
 };
+export type MockupFile = {
+    path: string;
+    before: string;
+    after: string;
+};
+export declare function buildMockupPrompt(options: {
+    summary: ChangeSummary;
+    files: MockupFile[];
+}): string;
 export declare function generateMockup(options: {
     provider: Provider;
     summary: ChangeSummary;
-    files: Array<{
-        path: string;
-        before: string;
-        after: string;
-    }>;
+    files: MockupFile[];
     outDir: string;
     model?: string;
+    theme?: Theme;
+    title?: string;
     log?: (msg: string) => void;
+    /** Prefix for the written HTML file (e.g. visual-1-). */
+    filePrefix?: string;
 }): Promise<MockupResult>;

package/dist/visual/mockup.js

@@ -1,19 +1,33 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { extractJson } from "../extract-json.js";
-export async function generateMockup(options) {
-    const prompt = `You create faithful before/after HTML mockups from a git diff.
+import { DEFAULT_MOCKUP_STAGE_WIDTH, MOCKUP_PANEL, STYLE_CONTRACT, buildMockupDocument, resolveTheme, } from "./design.js";
+export function buildMockupPrompt(options) {
+    return `You turn a git diff into a faithful before/after UI mockup.
+
+farq supplies the page frame: background, header, Before/After labels, the badge, and automatic scale-to-fit. You supply only the two panel interiors. Never recreate the frame.
+
+Each panel renders into a ${MOCKUP_PANEL.width}x${MOCKUP_PANEL.height}px box. Compose for that box: show the changed component and just enough surrounding context to place it. This is a close-up, not a whole application screen — no site nav, no sidebars, no footer, unless the diff changes those. Anything you design wider than the box gets scaled down and becomes hard to read.
+
+Produce:
+- "before_body" / "after_body": HTML fragments for the two states. No <html>, <head>, <body>, <style> or <script> tags.
+- "css": one stylesheet shared by both fragments.
+- "before_css" / "after_css" (optional): rules for one state only. farq scopes them for you, so keep the same class names in both fragments and put the differences here.
+- "stage_width": the pixel width you designed against. Default ${DEFAULT_MOCKUP_STAGE_WIDTH}; use 390 for a phone view. Never exceed ${MOCKUP_PANEL.width}.
 
-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.
-- 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.
-- If you cannot render faithfully, return {"feasible": false, "reason": "..."}.
+Fidelity rules:
+- Render the markup and styles the diff actually shows. Do not invent UI that is not in the code.
+- Stub only what is dynamic: realistic placeholder copy for props and data.
+- The only visible difference between the panels must be the change itself. Do not redesign anything else.
+- Whatever the diff adds must be easy to see: give it at least the weight of the content around it, never the faintest token on the panel. Do not add callouts, arrows or highlight boxes to point at it.
+- Never render raw code, diff text, or file paths as content.
+- If the diff contains no renderable UI, decline instead of guessing.
+
+${STYLE_CONTRACT}
 
 Return JSON only:
-{"feasible": true, "before_html": "...", "after_html": "...", "viewport": {"width":1280,"height":900}}
-or {"feasible": false, "reason": "..."}
+{"feasible":true,"css":"...","before_css":"...","after_css":"...","before_body":"...","after_body":"...","stage_width":${DEFAULT_MOCKUP_STAGE_WIDTH}}
+or {"feasible":false,"reason":"..."}
 
 Change summary context:
 ${JSON.stringify(options.summary, null, 2)}
@@ -23,24 +37,33 @@ ${options.files
         .map((f) => `### ${f.path}\n--- BEFORE ---\n${f.before}\n--- AFTER ---\n${f.after}`)
         .join("\n\n")}
 `;
+}
+export async function generateMockup(options) {
+    const prompt = buildMockupPrompt({
+        summary: options.summary,
+        files: options.files,
+    });
     const raw = await options.provider.complete(prompt, { model: options.model });
     const json = extractJson(raw);
     if (!json.feasible) {
         options.log?.(json.reason ?? "mockup not feasible");
         return { feasible: false, reason: json.reason ?? "not feasible" };
     }
-    if (!json.before_html || !json.after_html) {
-        return { feasible: false, reason: "missing before_html/after_html" };
+    if (!json.before_body || !json.after_body) {
+        return { feasible: false, reason: "missing before_body/after_body" };
     }
+    const html = buildMockupDocument({
+        theme: options.theme ?? resolveTheme(),
+        title: options.title ?? options.summary.headline,
+        css: json.css,
+        beforeCss: json.before_css,
+        afterCss: json.after_css,
+        beforeBody: json.before_body,
+        afterBody: json.after_body,
+        stageWidth: json.stage_width,
+    });
     mkdirSync(options.outDir, { recursive: true });
-    const beforePath = join(options.outDir, "before.html");
-    const afterPath = join(options.outDir, "after.html");
-    writeFileSync(beforePath, json.before_html, "utf8");
-    writeFileSync(afterPath, json.after_html, "utf8");
-    return {
-        feasible: true,
-        beforePath,
-        afterPath,
-        viewport: json.viewport,
-    };
+    const htmlPath = join(options.outDir, `${options.filePrefix ?? ""}mockup.html`);
+    writeFileSync(htmlPath, html, "utf8");
+    return { feasible: true, htmlPath };
 }

package/dist/visual/pipeline.d.ts

@@ -1,12 +1,40 @@
 import type { ChangeSummary } from "../schema.js";
 import type { Provider } from "../providers/index.js";
-import type { GatherDiffResult } from "../git.js";
+import type { GatherDiffResult, VisualFile } from "../git.js";
+import { type Theme } from "./design.js";
+export declare const DEFAULT_VISUAL_CONCURRENCY = 3;
+export type VisualImage = {
+    path: string;
+    title: string;
+};
 export type VisualPipelineResult = {
     imagePath: string | null;
     images: string[];
+    imageMeta: VisualImage[];
     softDegraded: boolean;
     warning?: string;
 };
+/** Structured events so the CLI can show what is actually happening. */
+export type VisualProgress = {
+    kind: "topics";
+    total: number;
+} | {
+    kind: "topic-start";
+    title: string;
+    mode: "mockup" | "diagram";
+} | {
+    kind: "topic-fallback";
+    title: string;
+} | {
+    kind: "topic-shot";
+    title: string;
+} | {
+    kind: "topic-done";
+    title: string;
+    ok: boolean;
+    done: number;
+    total: number;
+};
 export type VisualPipelineOptions = {
     cwd?: string;
     outDir?: string;
@@ -17,7 +45,13 @@ export type VisualPipelineOptions = {
     noImages?: boolean;
     before?: string;
     after?: string;
+    theme?: Theme;
+    maxTopics?: number;
+    concurrency?: number;
+    /** Pre-fetched before/after file contents; avoids git work in the hot path. */
+    visualFiles?: Promise<VisualFile[]> | VisualFile[];
     verbose?: boolean;
     log?: (msg: string) => void;
+    onProgress?: (event: VisualProgress) => void;
 };
 export declare function runVisualPipeline(options: VisualPipelineOptions): Promise<VisualPipelineResult>;