@ahmedalbarghouti/farq 0.0.2 → 0.1.0

package/dist/visual/cluster.js

@@ -0,0 +1,204 @@
+import { extractJson } from "../extract-json.js";
+export const MAX_VISUAL_TOPICS = 5;
+/**
+ * Topic grouping, cheapest source first:
+ *   1. visual_topics returned by the summarize call (free — no extra request)
+ *   2. a dedicated cheap-model call
+ *   3. file-overlap union-find
+ * Same-theme items (one feature across many files) → one topic.
+ * Truly unrelated domains → separate topics.
+ */
+export async function clusterVisualTopics(summary, options) {
+    const limit = normalizeLimit(options?.maxTopics);
+    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),
+            },
+        ];
+    }
+    const fromSummary = topicsFromIntentJson(summary, {
+        topics: summary.visual_topics,
+    });
+    if (fromSummary) {
+        options?.log?.(`visual topics (from summary): ${fromSummary.length} — ${fromSummary
+            .map((t) => t.title)
+            .join("; ")}`);
+        return capTopics(fromSummary, limit);
+    }
+    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 capTopics(ai, limit);
+            }
+            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 capTopics(clusterByFileOverlap(summary), limit);
+}
+function normalizeLimit(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+        return MAX_VISUAL_TOPICS;
+    }
+    return Math.min(MAX_VISUAL_TOPICS, Math.floor(value));
+}
+/** 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);
+    }
+    const clusters = [...groups.values()].map((groupItems, idx) => ({
+        id: idx + 1,
+        title: topicTitle(groupItems),
+        items: groupItems,
+        files: uniqueFiles(groupItems),
+    }));
+    return capTopics(clusters, MAX_VISUAL_TOPICS);
+}
+/** Merge the smallest topics until at most `limit` remain. */
+export function capTopics(topics, limit = MAX_VISUAL_TOPICS) {
+    let clusters = topics;
+    while (clusters.length > limit) {
+        clusters = [...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 merged = [...smallest.items, ...next.items];
+        clusters = [
+            {
+                id: 0,
+                title: topicTitle(merged),
+                items: merged,
+                files: uniqueFiles(merged),
+            },
+            ...clusters.slice(2),
+        ];
+    }
+    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

@@ -1,16 +1,23 @@
 import { resolveChrome, ChromeError } from "./chrome.js";
+import { type Theme } from "./design.js";
 export type ComposeOptions = {
     cwd?: string;
     outDir?: string;
     beforePath: string;
     afterPath: string;
-    badge?: "generated preview" | "before / after";
+    badge?: string;
+    title?: string;
+    theme?: Theme;
     chromePath?: string;
+    /** Output PNG basename (default before-after.png). */
+    outFileName?: string;
 };
 export declare function buildComposeHtml(options: {
     beforeBase64: string;
     afterBase64: string;
     badge: string;
+    title?: string;
+    theme?: Theme;
 }): string;
 export declare function composeBeforeAfter(options: ComposeOptions): Promise<string>;
 export { ChromeError, resolveChrome };

package/dist/visual/compose.js

@@ -3,33 +3,16 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { defaultOutDir } from "../paths.js";
 import { resolveChrome, screenshotHtml, ChromeError } from "./chrome.js";
+import { buildComposeDocument, resolveTheme } from "./design.js";
+import { DEFAULT_VIEWPORT } from "./viewport.js";
 export function buildComposeHtml(options) {
-    const { beforeBase64, afterBase64, badge } = options;
-    return `<!doctype html>
-<html><head><meta charset="utf-8" />
-<style>
-  html,body{margin:0;background:#1b1d21;color:#e8e8e8;font-family:system-ui,sans-serif}
-  .wrap{padding:24px}
-  .badge{position:fixed;top:12px;right:12px;font-size:11px;letter-spacing:.04em;text-transform:uppercase;
-    background:#2a2e35;border:1px solid #3a3f48;padding:4px 8px;border-radius:4px;opacity:.9}
-  .grid{display:grid;grid-template-columns:1fr 1fr;gap:16px}
-  h2{margin:0 0 10px;font-size:14px;font-weight:600;color:#b9c0c9}
-  img{width:100%;height:auto;background:#0f1114;border:1px solid #2f343d;border-radius:6px;display:block}
-</style></head>
-<body>
-  <div class="badge">${escapeHtml(badge)}</div>
-  <div class="wrap"><div class="grid">
-    <section><h2>Before</h2><img alt="Before" src="data:image/png;base64,${beforeBase64}" /></section>
-    <section><h2>After</h2><img alt="After" src="data:image/png;base64,${afterBase64}" /></section>
-  </div></div>
-</body></html>`;
-}
-function escapeHtml(s) {
-    return s
-        .replaceAll("&", "&amp;")
-        .replaceAll("<", "&lt;")
-        .replaceAll(">", "&gt;")
-        .replaceAll('"', "&quot;");
+    return buildComposeDocument({
+        theme: options.theme ?? resolveTheme(),
+        title: options.title ?? "Before / after",
+        beforeBase64: options.beforeBase64,
+        afterBase64: options.afterBase64,
+        badge: options.badge,
+    });
 }
 export async function composeBeforeAfter(options) {
     const cwd = options.cwd ?? process.cwd();
@@ -37,22 +20,24 @@ export async function composeBeforeAfter(options) {
     mkdirSync(outDir, { recursive: true });
     const before = readFileSync(options.beforePath);
     const after = readFileSync(options.afterPath);
-    const badge = options.badge ?? "generated preview";
     const html = buildComposeHtml({
         beforeBase64: before.toString("base64"),
         afterBase64: after.toString("base64"),
-        badge,
+        badge: options.badge ?? "before / after",
+        title: options.title,
+        theme: options.theme,
     });
-    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/css-scope.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Prefix every top-level selector in a stylesheet so model-authored rules can
+ * only affect one before/after panel. Runs at build time on our side, so the
+ * output works on any Chrome (no CSS nesting or @scope support required).
+ */
+export declare function scopeCss(css: string, prefix: string): string;

package/dist/visual/css-scope.js

@@ -0,0 +1,162 @@
+/**
+ * Prefix every top-level selector in a stylesheet so model-authored rules can
+ * only affect one before/after panel. Runs at build time on our side, so the
+ * output works on any Chrome (no CSS nesting or @scope support required).
+ */
+export function scopeCss(css, prefix) {
+    if (!css || !css.trim())
+        return "";
+    return transformBlock(css, prefix);
+}
+function transformBlock(css, prefix) {
+    let out = "";
+    let prelude = "";
+    let i = 0;
+    while (i < css.length) {
+        const ch = css[i];
+        if (ch === "/" && css[i + 1] === "*") {
+            const end = css.indexOf("*/", i + 2);
+            i = end === -1 ? css.length : end + 2;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            const end = skipString(css, i);
+            prelude += css.slice(i, end);
+            i = end;
+            continue;
+        }
+        if (ch === "{") {
+            const { body, next } = readBlock(css, i);
+            out += renderRule(prelude.trim(), body, prefix);
+            prelude = "";
+            i = next;
+            continue;
+        }
+        if (ch === ";") {
+            // Statement at-rule such as @import / @charset — pass through untouched.
+            const stmt = prelude.trim();
+            if (stmt)
+                out += `${stmt};`;
+            prelude = "";
+            i++;
+            continue;
+        }
+        if (ch === "}") {
+            // Stray closer from malformed input; drop it rather than corrupt output.
+            i++;
+            continue;
+        }
+        prelude += ch;
+        i++;
+    }
+    return out;
+}
+/** At-rules whose body is a nested list of rules, not declarations. */
+const NESTED_AT_RULES = new Set(["media", "supports", "container", "layer"]);
+function renderRule(prelude, body, prefix) {
+    if (!prelude)
+        return "";
+    if (prelude.startsWith("@")) {
+        const name = prelude.slice(1).split(/[\s({]/)[0].toLowerCase();
+        if (NESTED_AT_RULES.has(name)) {
+            return `${prelude}{${transformBlock(body, prefix)}}`;
+        }
+        // @keyframes / @font-face / @property / @page carry no page selectors.
+        return `${prelude}{${body}}`;
+    }
+    return `${prefixSelectorList(prelude, prefix)}{${body}}`;
+}
+function prefixSelectorList(list, prefix) {
+    return splitTopLevel(list, ",")
+        .map((sel) => prefixSelector(sel.trim(), prefix))
+        .filter(Boolean)
+        .join(",");
+}
+const ROOT_SELECTOR = /^(html|body|:root)\b/i;
+function prefixSelector(selector, prefix) {
+    if (!selector)
+        return "";
+    // Root-level selectors would escape the panel — retarget them at the panel.
+    if (ROOT_SELECTOR.test(selector)) {
+        const rest = selector.replace(ROOT_SELECTOR, "").trim();
+        if (!rest || rest === ">")
+            return prefix;
+        return `${prefix} ${rest}`.replace(/\s+/g, " ");
+    }
+    if (selector.startsWith("&")) {
+        return `${prefix}${selector.slice(1)}`;
+    }
+    return `${prefix} ${selector}`;
+}
+/** Split on a separator that sits outside strings, parens and brackets. */
+function splitTopLevel(input, separator) {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    let i = 0;
+    while (i < input.length) {
+        const ch = input[i];
+        if (ch === '"' || ch === "'") {
+            const end = skipString(input, i);
+            current += input.slice(i, end);
+            i = end;
+            continue;
+        }
+        if (ch === "(" || ch === "[")
+            depth++;
+        else if (ch === ")" || ch === "]")
+            depth = Math.max(0, depth - 1);
+        if (ch === separator && depth === 0) {
+            parts.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+        i++;
+    }
+    parts.push(current);
+    return parts;
+}
+/** Read a `{...}` block starting at openIdx; returns inner body and index after `}`. */
+function readBlock(css, openIdx) {
+    let depth = 0;
+    let i = openIdx;
+    while (i < css.length) {
+        const ch = css[i];
+        if (ch === "/" && css[i + 1] === "*") {
+            const end = css.indexOf("*/", i + 2);
+            i = end === -1 ? css.length : end + 2;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            i = skipString(css, i);
+            continue;
+        }
+        if (ch === "{")
+            depth++;
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0) {
+                return { body: css.slice(openIdx + 1, i), next: i + 1 };
+            }
+        }
+        i++;
+    }
+    return { body: css.slice(openIdx + 1), next: css.length };
+}
+function skipString(input, start) {
+    const quote = input[start];
+    let i = start + 1;
+    while (i < input.length) {
+        const ch = input[i];
+        if (ch === "\\") {
+            i += 2;
+            continue;
+        }
+        if (ch === quote)
+            return i + 1;
+        i++;
+    }
+    return i;
+}

package/dist/visual/design.d.ts

@@ -0,0 +1,103 @@
+export declare const THEME_NAMES: readonly ["midnight", "daylight"];
+export type ThemeName = (typeof THEME_NAMES)[number];
+export declare const DEFAULT_THEME: ThemeName;
+/**
+ * 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 declare const MOCKUP_PANEL: {
+    readonly width: 605;
+    readonly height: 604;
+};
+export declare const DIAGRAM_PANEL: {
+    readonly width: 1230;
+    readonly height: 626;
+};
+/** Widths the model designs against before farq scales the result to fit. */
+export declare const DEFAULT_MOCKUP_STAGE_WIDTH = 600;
+export declare const DEFAULT_DIAGRAM_STAGE_WIDTH = 1200;
+export type ThemeTokens = {
+    canvas: string;
+    canvasAlt: string;
+    surface: string;
+    surfaceAlt: string;
+    surfaceSunken: string;
+    border: string;
+    borderStrong: string;
+    text: string;
+    textMuted: string;
+    textFaint: string;
+    accent: string;
+    accentInk: string;
+    accentSoft: string;
+    positive: string;
+    positiveSoft: string;
+    warning: string;
+    danger: string;
+    dangerSoft: string;
+    shadow: string;
+};
+export type Theme = {
+    name: ThemeName;
+    tokens: ThemeTokens;
+    /** Optional webfont import; omitted by default so renders stay offline-safe. */
+    fontImport?: string;
+    fontSans?: string;
+    fontDisplay?: string;
+};
+export type ThemeOverrides = {
+    theme?: string;
+    accent?: string;
+    fontImport?: string;
+    fontSans?: string;
+    fontDisplay?: string;
+};
+export declare function isThemeName(value: unknown): value is ThemeName;
+export declare function resolveTheme(overrides?: ThemeOverrides): Theme;
+/**
+ * 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 declare const STYLE_CONTRACT = "Design tokens (CSS custom properties already defined \u2014 use them, do not redefine them):\n- 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)\n- Type: var(--fq-font-display) for headings, var(--fq-font-sans) for body, var(--fq-font-mono) for identifiers\n- Shape: var(--fq-radius-sm), var(--fq-radius), var(--fq-radius-lg), var(--fq-shadow)\n\nStyle rules (hard):\n- 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) \u2014 then use that literal value.\n- Do not set font-family to anything except the three variables. Do not @import fonts. Do not reference external URLs, images, or scripts.\n- Do not add gradients, glows, blurs, or decorative background art. The page frame, background, header and badge are supplied by farq \u2014 do not recreate them.\n- Use exactly one accent color for emphasis; neutrals carry the rest.\n- 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.\n- Spacing in multiples of 4px. Body text >= 13px.\n- No raw code listings, no JSON dumps, no lorem ipsum. Placeholder copy must read like real product data.";
+export type StageKind = "mockup" | "diagram";
+export type StageSize = {
+    width: number;
+};
+export declare function clampStageWidth(input?: {
+    width?: number;
+} | null, kind?: StageKind): StageSize;
+export declare const PREVIEW_BADGE = "generated preview";
+export type MockupDocumentInput = {
+    theme: Theme;
+    title: string;
+    css?: string;
+    beforeCss?: string;
+    afterCss?: string;
+    beforeBody: string;
+    afterBody: string;
+    stageWidth?: number;
+    badge?: string;
+};
+export declare function buildMockupDocument(input: MockupDocumentInput): string;
+export type DiagramDocumentInput = {
+    theme: Theme;
+    title: string;
+    css?: string;
+    body: string;
+    stageWidth?: number;
+    badge?: string;
+};
+export declare function buildDiagramDocument(input: DiagramDocumentInput): string;
+export type ComposeDocumentInput = {
+    theme: Theme;
+    title: string;
+    beforeBase64: string;
+    afterBase64: string;
+    badge?: string;
+};
+/** Frame for user-supplied before/after PNGs — same chrome as generated visuals. */
+export declare function buildComposeDocument(input: ComposeDocumentInput): string;