@palate/cli 0.0.0-stage → 0.0.1

package/src/loop/vary.mjs

@@ -0,0 +1,249 @@
+// `palate vary <route> --section "<name or selector>" [--count 3]`: fresh variations of ONE section, seen in
+// the page around it. palate finds the section, copies the page into N variant routes (relative imports
+// fixed) named like a design loop (<name>-a1, <name>-b1 …, so pick finds them), and writes one brief per
+// variant: a different structural idea and different references each. The agent replaces only the section
+// in each copy; `palate pick --name <name>` then shows them in context, blind, with the current section
+// as one of the options.
+import fs from "node:fs";
+import path from "node:path";
+import { cropSections, findSections, matchSection, openPage, routeFile, shootFull, slugOf, withBrowser } from "../look.mjs";
+import { normalizeRoute } from "../shoot.mjs";
+import { sessionDir } from "./common.mjs";
+import { craftRubric, screenWords, sectionKind, slash, tasteFor } from "./craft.mjs";
+import { kindTags, projectOf, rulesBlock } from "./rules.mjs";
+
+const LETTERS = "abcdefgh";
+
+// Structural ideas by kind of section. Each variant gets a different one.
+const IDEAS = {
+  hero: [
+    ["Product-first", "the live product UI is the hero; the headline sits beside or above it, short", "product ui screenshot"],
+    ["Statement", "one confident line of type and the action, nothing else on the first screen; the product starts right below", "large typography minimal"],
+    ["Split proof", "headline left, one real result or record from the product right (a single domain object, not a dashboard)", "split layout"],
+    ["Try it here", "the reader does the core action right in the hero (types, picks, toggles) and sees the result", "interactive form"],
+    ["Annotated", "the product at full width with three short callouts pinned to the parts that matter", "annotation callouts"],
+  ],
+  steps: [
+    ["One object, moving through", "a single artefact travels through the steps (request → variants → choice → polished screen); the step names follow it", "timeline"],
+    ["Before → after", "show the input and the output large; the steps become a thin rail between them", "comparison"],
+    ["A real run", "the steps as a log or timeline from one actual session: timestamps, artefacts, the user's click", "timeline log"],
+    ["All steps, each with its artefact", "every step visible at once as a small card holding the real thing it produces (a brief, a variant, a pick)", "cards grid"],
+    ["The cycle", "the loop drawn as a cycle, with the user's choice point as the one emphasised node and 'learns' feeding back", "diagram"],
+  ],
+  "logo cloud": [
+    ["Full-colour row", "official marks in their own colours, one centred row, 24px marks, generous spacing, names optional", "logo cloud"],
+    ["Grouped", "two short groups with small labels (agents, frameworks), marks 20–24px with names, real colours", "logo cloud grid"],
+    ["In a sentence", "the marks inline in a sentence, as glyphs beside the names (\"Works in Claude Code, Codex and Cursor\")", "inline typography"],
+    ["Integration tiles", "one tile per tool: mark, name, one line of what palate does there", "integration grid cards"],
+  ],
+  showcase: [
+    ["Make it live", "rebuild the key moment of the screenshot in real UI and animate the state change (respects reduced motion)", "product ui"],
+    ["Before | after", "two states side by side or a slider: the problem and palate's result", "comparison"],
+    ["Annotated", "the picture with three callouts pinned to its real parts", "annotation callouts"],
+    ["Small multiples", "several real states or variants small, side by side, with one emphasised", "grid gallery"],
+  ],
+  features: [
+    ["Bento of real UI", "a bento grid where every tile holds real product UI, not icons", "bento grid"],
+    ["2×2 tactile cards", "four cards, each with a real artefact and one line", "feature grid cards"],
+    ["Comparison", "a table: palate vs the default, row by row", "comparison table"],
+    ["Annotated product", "one large product view with numbered callouts", "annotation"],
+  ],
+  pricing: [
+    ["Ruled columns", "all plans side by side in ruled columns, the recommended one lightly marked", "pricing columns"],
+    ["Rate card", "a compact table of plans and what changes between them", "pricing table"],
+    ["Comparison", "plans as columns with a full feature comparison below", "comparison table"],
+  ],
+  testimonials: [
+    ["One big quote", "a single strong quote with the real person's name, role and face (or a generated avatar)", "testimonial quote"],
+    ["Wall", "a dense grid of short real quotes", "testimonials grid"],
+    ["Quote + proof", "quote beside the result it refers to (a screenshot, a metric)", "testimonial"],
+  ],
+  cta: [
+    ["Statement + action", "one line, one field or button, lots of space", "cta"],
+    ["Proof + action", "the action beside the strongest proof on the page (a number, a real result)", "cta stats"],
+    ["Inline", "the action as a sentence with the field inside it", "newsletter signup"],
+  ],
+  generic: [
+    ["Content-first list", "the section's content as a clear list or table, nothing else", "list table"],
+    ["Big figure", "one large number or fact with the sentence that explains it", "stats"],
+    ["Artefact beside text", "a real artefact from the product beside a short text column", "split layout"],
+    ["Cards", "a grid of equal cards, each with a real artefact", "cards grid"],
+  ],
+};
+const ideaKey = (kind) => (/hero/.test(kind) ? "hero" : /step|timeline/.test(kind) ? "steps" : /logo/.test(kind) ? "logo cloud" : /mockup|showcase/.test(kind) ? "showcase" : /feature/.test(kind) ? "features" : /pric/.test(kind) ? "pricing" : /testimonial/.test(kind) ? "testimonials" : /cta|signup|newsletter/.test(kind) ? "cta" : "generic");
+
+// Copies the page to a new route, rewriting relative imports so they still resolve.
+function copyPage(src, dest) {
+  const from = path.dirname(src);
+  const to = path.dirname(dest);
+  const code = fs.readFileSync(src, "utf8").replace(/((?:from|import)\s*\(?\s*["'])(\.{1,2}\/[^"']+)(["'])/g, (m, a, spec, b) => {
+    let rel = path.relative(to, path.resolve(from, spec)).replace(/\\/g, "/");
+    if (!rel.startsWith(".")) rel = `./${rel}`;
+    return `${a}${rel}${b}`;
+  });
+  fs.mkdirSync(to, { recursive: true });
+  fs.writeFileSync(dest, `// palate vary: a copy of ${path.basename(src)}; only the section marked data-palate-vary differs. Delete after the pick.\n${code}`);
+}
+
+// Where a variant route lives, following the page's own convention (folder route or file route).
+function variantFile(found, variant) {
+  const base = path.basename(found.file);
+  const ext = path.extname(base);
+  if (/^\+?page\./.test(base) || path.dirname(found.file) !== found.root) return path.join(found.root, variant, /^\+?page\./.test(base) ? base : `index${ext}`);
+  return path.join(found.root, `${variant}${ext}`);
+}
+
+// Lines in the page source that likely hold the section (by id, aria-labelledby or heading text).
+function locate(file, s) {
+  const lines = fs.readFileSync(file, "utf8").split("\n");
+  const keys = [s.id && `id="${s.id}"`, s.id && `"${s.id}"`, s.heading?.slice(0, 28), s.name?.slice(0, 28)].filter(Boolean);
+  for (const k of keys) {
+    const i = lines.findIndex((l) => l.includes(k));
+    if (i >= 0) return { line: i + 1, key: k };
+  }
+  return null;
+}
+
+export async function vary(dir, rawRoute, { section, count = 3, url, brief: want = "" } = {}) {
+  const route = normalizeRoute(rawRoute);
+  count = Math.max(2, Math.min(count, 6));
+  const { s, first, crops } = await withBrowser(dir, { url }, async ({ base, browser }) => {
+    const { page, ctx } = await openPage(browser, base, route, { width: 1440 });
+    const sections = await findSections(page);
+    const s = await matchSection(page, sections, section);
+    if (!s) throw new Error(`No section matches "${section}" on ${route}. Sections: ${sections.map((x) => `${x.index} "${x.name}"${x.id ? ` (#${x.id})` : ""}`).join(", ")}`);
+    const first = sections.filter((x) => !["header", "nav"].includes(x.tag))[0]?.index === s.index;
+    const tmp = path.join(dir, ".palate", "vary-tmp");
+    const crops = { 1440: (await cropSections(page, [s], tmp, "w1440"))[0]?.file };
+    await ctx.close();
+    return { s, first, crops };
+  });
+
+  const sectionSlug = (s.id || s.name).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").split("-").slice(0, 2).join("-") || `s${s.index}`;
+  const name = `${slugOf(route)}-${sectionSlug}`.slice(0, 28).replace(/-$/, "");
+  const session = sessionDir(dir, name);
+  const now = path.join(session, "current-1440.png");
+  if (crops[1440]) fs.renameSync(crops[1440], now);
+  fs.rmSync(path.join(dir, ".palate", "vary-tmp"), { recursive: true, force: true });
+
+  const kind = sectionKind(s, { first });
+  const pool = [...IDEAS[ideaKey(kind)]].sort(() => Math.random() - 0.5);
+  const ideas = Array.from({ length: count }, (_, i) => pool[i % pool.length]);
+  const found = routeFile(dir, route);
+  const loc = found && locate(found.file, s);
+  const taste = tasteFor(`${screenWords(route)} ${kind}`, { project: path.basename(path.resolve(dir)) });
+  const creative = craftRubric(/creativ|idea|memor|novel|demo|signature/i);
+  // The user's rules for this page and this kind of section, with what failed for them before.
+  const mine = rulesBlock(kindTags({ route, kind: "marketing", section: kind, words: s.name }), { route, project: projectOf(dir) });
+
+  // Different references for each variant: search with the section kind plus the idea's words.
+  const { searchLibrary, librarySheet } = await import("./library.mjs");
+  const used = new Set();
+  const variants = [];
+  for (const [i, [title, idea, words]] of ideas.entries()) {
+    const letter = LETTERS[i];
+    const routeName = `${name}-${letter}1`;
+    const refs = searchLibrary(`${kind} ${words}`, { n: 12, preferWhole: true, style: words }).filter((r) => !used.has(r.id)).slice(0, 4);
+    refs.forEach((r) => used.add(r.id));
+    const sheet = refs.length >= 2 ? await librarySheet(refs, path.join(session, `refs-${letter}.png`)) : null;
+    let file = null;
+    if (found) {
+      file = variantFile(found, routeName);
+      if (!fs.existsSync(file)) copyPage(found.file, file);
+    }
+    variants.push({ letter, route: `/${routeName}`, title, idea, sheet, file });
+  }
+
+  for (const v of variants) {
+    const others = variants.filter((x) => x !== v).map((x) => `${x.letter.toUpperCase()}: ${x.title}`).join("; ");
+    const brief = [
+      mine.line,
+      "",
+      `# Vary one section: "${s.name}" on ${route}, idea ${v.letter.toUpperCase()}: ${v.title}`,
+      "",
+      `Project: ${slash(dir)}. Every fact, record and number must come from the project. No invented customers, logos, testimonials or stats.`,
+      "",
+      ...mine.lines,
+      "## The section now",
+      `- Screenshot: ${slash(now)} (open it). Selector on the page: \`${s.selector}\`.`,
+      found ? `- Source: ${slash(found.file)}${loc ? `, around line ${loc.line} (\`${loc.key}\`)` : ""}.` : "- Source: palate couldn't find the file for this route (routing in code?). Find the component that renders it.",
+      `- Kind: ${kind}.`,
+      "",
+      "## Your route",
+      v.file
+        ? `palate created \`${slash(v.file)}\` as an exact copy of the page (relative imports fixed); it opens at \`${v.route}\`. Replace ONLY this section in it with your new version. Everything else in the copy stays as it is.`
+        : `Create a route at \`${v.route}\` that renders the same page with only this section replaced (copy the page, fix its imports).`,
+      "Put `data-palate-vary` on your new section's root element: palate finds it there to show it in the page.",
+      "",
+      ...(want ? ["## What the user wants from this section (this comes first)", want, ""] : []),
+      "## The idea",
+      `**${v.title}**: ${v.idea}.`,
+      `A different structure from the current section and from the other variants (${others}). Same job, same real content; a new way to show it.`,
+      "",
+      "## References (inspiration, not templates)",
+      v.sheet ? `Contact sheet: ${slash(v.sheet)} (index with full-size paths: ${slash(v.sheet.replace(/\.png$/, ".json"))}). Take parts from at least two; never copy text, logos, imagery or brand colours.` : "No library references for this idea; work from the taste profile and the page itself.",
+      "",
+      "## Whose taste",
+      taste || "No taste profile yet: clarity first, one crafted touch at most.",
+      "",
+      ...(creative.text ? ["## Making it memorable (kb/craft)", creative.text, ""] : []),
+      "## Rules",
+      "- It must sit in the page: the page's type, colours, spacing and widths. Only this section changes.",
+      "- Scope custom styles to your route file. Never edit shared files or components, and never install packages (other agents work here at the same time).",
+      "- Accessible: semantic structure, AA contrast, visible focus, reduced motion respected; content visible without waiting for scroll or JavaScript.",
+      "",
+      "## Check your work",
+      `Run \`palate shoot ${v.route} --widths 1440,390\`, open the screenshots, fix the biggest problem once and every rule it reports failing. The project's typecheck must pass for your file. Do not commit.`,
+      "",
+      "Reply with one line: the idea and the reference numbers used.",
+    ].join("\n");
+    v.brief = path.join(session, `brief-${v.letter}.md`);
+    fs.writeFileSync(v.brief, brief);
+  }
+
+  fs.writeFileSync(
+    path.join(session, "loop.json"),
+    JSON.stringify({ name, job: `A new version of the "${s.name}" section on ${route}`, title: `Section "${s.name}" on ${route}`, kind, quick: true, vary: { route, section: s.name, selector: s.selector, index: s.index, id: s.id, file: found?.file ?? null, variants: variants.map((v) => v.file).filter(Boolean) }, directions: variants.map((v) => ({ id: `vary-${v.title.toLowerCase().replace(/[^a-z]+/g, "-")}`, name: v.title, letter: v.letter })), created: new Date().toISOString() }, null, 2),
+  );
+  return [
+    mine.line,
+    "",
+    `# Varying "${s.name}" on ${route}: ${variants.length} ideas`,
+    "",
+    ...variants.map((v) => `- ${v.letter}: ${v.title} → ${v.route}${v.file ? ` (copy of the page: ${slash(v.file)})` : ""}\n  brief: ${slash(v.brief)}`),
+    "",
+    "Build every brief: with subagents, one per brief in parallel, each told \"Read <brief path> and follow it exactly; change only the section in the route it names.\" Otherwise one at a time.",
+    "",
+    `When all are built: \`palate pick --name ${name}\`. The user sees each variant in the page around it, blind, with the current section as one of the options.`,
+  ].join("\n");
+}
+
+// For pick: each route's section with some of the page above and below it, at 1440.
+export async function renderInContext(dir, routes, meta, outDir, { url } = {}) {
+  fs.mkdirSync(outDir, { recursive: true });
+  return withBrowser(dir, { url }, async ({ base, browser }) => {
+    const out = [];
+    for (const route of routes) {
+      const { page, ctx, errors } = await openPage(browser, base, route, { width: 1440 });
+      const box = await page.evaluate(({ selector }) => {
+        const el = document.querySelector("[data-palate-vary]") ?? document.querySelector(selector);
+        if (!el) return null;
+        const r = el.getBoundingClientRect();
+        return { y: r.top + scrollY, h: r.height, w: document.documentElement.clientWidth, H: document.documentElement.scrollHeight };
+      }, meta);
+      if (!box) {
+        out.push({ route, error: `section not found${errors.length ? `: ${errors[0].slice(0, 120)}` : ""}` });
+        await ctx.close();
+        continue;
+      }
+      // A little of the page above (so the tile opens on the section) and more below.
+      const top = Math.max(0, box.y - 140);
+      const clip = { x: 0, y: top, width: box.w, height: Math.min(box.h + (box.y - top) + 240, 2200, box.H - top) };
+      const file = path.join(outDir, `${route.replace(/^\//, "").replace(/[^a-z0-9-]+/gi, "-") || "current"}.png`);
+      await shootFull(page, file, { clip });
+      out.push({ route, file });
+      await ctx.close();
+    }
+    return out;
+  });
+}