@palate/cli 0.0.0-stage → 0.0.1

package/src/look.mjs

@@ -0,0 +1,312 @@
+// Shared page helpers for the specific-job commands (critique, fix, vary, details, animate): one dev server
+// and one browser per run, a page loaded like a reader would see it, its sections, crops of them, and
+// numbered contact sheets the agent can read at a glance.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { acquireBrowser, acquireServer } from "./pool.mjs";
+import { cropImage, decodePng, stackImages, writePng } from "./png.mjs";
+import { normalizeRoute } from "./shoot.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const sectionsScript = fs.readFileSync(path.join(here, "page-sections.js"), "utf8").trim().replace(/;\s*$/, "");
+
+// Counts what scripts set up for motion (scroll observers, Web Animations), before the page's own code runs.
+export const MOTION_INIT = `window.__palateMotion = { io: 0, waapi: 0, started: 0, entrances: 0, styled: new Set(), props: {} };
+const __pinned = (el) => { for (let e = el; e && e.nodeType === 1; e = e.parentElement) { const p = getComputedStyle(e).position; if (p === "fixed" || p === "sticky") return true; } return false; };
+for (const t of ["animationstart", "transitionrun"]) document.addEventListener(t, (e) => { const M = window.__palateMotion; M.started++; const prop = e.propertyName || "animation"; M.props[prop] = (M.props[prop] || 0) + 1; if ((t === "animationstart" || /opacity|transform|translate|scale|filter|clip/.test(prop)) && !__pinned(e.target)) M.entrances++; }, true);
+new MutationObserver((list) => { for (const m of list) if (/opacity|transform|translate|scale/.test(m.target.getAttribute("style") || "") && !__pinned(m.target)) window.__palateMotion.styled.add(m.target); }).observe(document, { subtree: true, attributes: true, attributeFilter: ["style"] });
+if (window.IntersectionObserver) { const IO = window.IntersectionObserver; window.IntersectionObserver = class extends IO { constructor(...a) { super(...a); window.__palateMotion.io++; } }; }
+if (Element.prototype.animate) { const an = Element.prototype.animate; Element.prototype.animate = function (...a) { window.__palateMotion.waapi++; return an.apply(this, a); }; }`;
+
+// Dev-server chrome (Next's dev badge, Astro's toolbar …) is not part of the design; hide it in screenshots.
+export const HIDE_DEV = `addEventListener("DOMContentLoaded", () => { const s = document.createElement("style"); s.textContent = "nextjs-portal, [data-nextjs-toast], #__next-build-watcher, astro-dev-toolbar, #vite-plugin-checker-error-overlay, [data-nextjs-dev-tools-button] { display: none !important; }"; document.head.appendChild(s); });`;
+
+export const slugOf = (route) => normalizeRoute(route).replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "") || "home";
+export const stamp = () => new Date().toISOString().replace(/[-:]/g, "").replace(/\..+$/, "").replace("T", "-");
+
+// Runs fn({ base, browser }) with the project's dev server (or --url) and a browser, then cleans both up.
+// In keep-alive mode (the CLI and the MCP server) both are shared across the whole process.
+export async function withBrowser(dir, { url } = {}, fn) {
+  const server = await acquireServer(dir, { url });
+  const { browser, release } = await acquireBrowser();
+  try {
+    return await fn({ base: server.base, browser });
+  } finally {
+    await release();
+    server.stop();
+  }
+}
+
+// Scrolls through the page so lazy images load and scroll-triggered reveals fire, then returns to the top.
+export async function scrollThrough(page, { step = 0.8, pause = 140 } = {}) {
+  const { h, vh } = await page.evaluate(() => ({ h: document.documentElement.scrollHeight, vh: innerHeight }));
+  for (let y = 0; y < h; y += Math.round(vh * step)) {
+    await page.evaluate((top) => window.scrollTo({ top, behavior: "instant" }), y);
+    await page.waitForTimeout(pause);
+  }
+  await page.evaluate(() => window.scrollTo({ top: 0, behavior: "instant" }));
+  await page.waitForTimeout(400);
+}
+
+// Opens a route at a width and waits until it has settled. Returns { page, ctx, errors }.
+export async function openPage(browser, base, route, { width = 1440, reducedMotion, javaScriptEnabled = true, scroll = true, init } = {}) {
+  const ctx = await browser.newContext({ viewport: { width, height: width < 600 ? 844 : 900 }, reducedMotion: reducedMotion ? "reduce" : "no-preference", javaScriptEnabled });
+  const page = await ctx.newPage();
+  const errors = [];
+  page.on("pageerror", (e) => errors.push(e.message));
+  await page.addInitScript(HIDE_DEV);
+  if (init) await page.addInitScript(init);
+  // Twice when needed: a dev server may reload once while it optimises dependencies.
+  for (let k = 0; k < 2; k++) {
+    try {
+      await page.goto(base + normalizeRoute(route), { waitUntil: "networkidle", timeout: 60_000 });
+      await page.waitForTimeout(700);
+      await page.evaluate(() => document.body.innerHTML.length);
+      break;
+    } catch (e) {
+      if (k) errors.push(e.message);
+    }
+  }
+  if (scroll) await scrollThrough(page);
+  await settle(page);
+  return { page, ctx, errors };
+}
+
+// Lets the page come to rest before a capture: fonts loaded, the images on screen decoded, finite animations
+// and transitions done (at most `wait` ms), then two frames so their styles are painted.
+export async function settle(page, { wait = 1000 } = {}) {
+  await page
+    .evaluate(async (wait) => {
+      const onScreen = (el) => {
+        const r = el.getBoundingClientRect();
+        return r.width > 0 && r.bottom > 0 && r.top < innerHeight;
+      };
+      const finite = (a) => a.playState === "running" && Number.isFinite(a.effect?.getComputedTiming?.().endTime);
+      const work = [document.fonts?.ready, ...[...document.images].filter(onScreen).map((i) => i.decode()), ...(document.getAnimations?.() ?? []).filter(finite).map((a) => a.finished)];
+      await Promise.race([Promise.all(work.map((p) => Promise.resolve(p).catch(() => {}))), new Promise((r) => setTimeout(r, wait))]);
+      // A hidden page gets no frames; don't wait forever for them.
+      await new Promise((r) => (requestAnimationFrame(() => requestAnimationFrame(r)), setTimeout(r, 250)));
+    }, wait)
+    .catch(() => {});
+}
+
+// What stays put while the page scrolls, for a capture made screen by screen. Sticky things go back to their
+// place in the page (where they sit at the top). Small fixed things (a header, a cookie bar, a chat button)
+// show on the first screen only, as on a full-page screenshot; a full-screen fixed layer (a grain, a backdrop)
+// shows on every screen, as a reader sees it. Snapping and smooth scrolling are off so a scroll lands where
+// it's sent. step: "tile" marks what is pinned now (returns scrollY), "end" puts everything back.
+const PINS = (step) => {
+  const root = document.documentElement;
+  const css = document.getElementById("__palate-pins");
+  if (step === "end") {
+    css?.remove();
+    for (const el of document.querySelectorAll("[data-palate-pin], [data-palate-unstick]")) el.removeAttribute("data-palate-pin"), el.removeAttribute("data-palate-unstick");
+    root.removeAttribute("data-palate-scrolled");
+    return scrollY;
+  }
+  if (!css) {
+    const s = document.createElement("style");
+    s.id = "__palate-pins";
+    s.textContent = "html, body { scroll-snap-type: none !important; scroll-behavior: auto !important; } [data-palate-unstick] { position: relative !important; inset: auto !important; } html[data-palate-scrolled] [data-palate-pin] { opacity: 0 !important; transition: none !important; }";
+    (document.head ?? root).appendChild(s);
+  }
+  const vw = innerWidth, vh = innerHeight;
+  for (const el of document.querySelectorAll("body *")) {
+    if (el.hasAttribute("data-palate-unstick") || el.hasAttribute("data-palate-pin")) continue;
+    const p = getComputedStyle(el).position;
+    if (p === "sticky") el.setAttribute("data-palate-unstick", "");
+    // offsetParent is null only when the screen holds it (not a transformed ancestor).
+    else if (p === "fixed" && el.offsetParent === null) {
+      const r = el.getBoundingClientRect();
+      const seen = Math.max(0, Math.min(r.right, vw) - Math.max(r.left, 0)) * Math.max(0, Math.min(r.bottom, vh) - Math.max(r.top, 0));
+      if (seen < 0.6 * vw * vh) el.setAttribute("data-palate-pin", "");
+    }
+  }
+  root.toggleAttribute("data-palate-scrolled", scrollY > 0);
+  return Math.round(scrollY);
+};
+const FULL_HEIGHT = () => Math.max(document.body?.scrollHeight ?? 0, document.documentElement.scrollHeight, document.body?.offsetHeight ?? 0, document.documentElement.offsetHeight, document.documentElement.clientHeight);
+
+// The whole page (or clip, in page coordinates) as one image, captured screen by screen from the top down.
+// Never Playwright's fullPage: Chrome's beyond-the-viewport capture resizes the page to 1x1 and back right
+// before it shoots, and a page that lays out in between is captured half rebuilt (container-query sizes at
+// zero, sections shrunk, everything below shifted up). Screen-sized captures never resize the page, so they
+// show what a reader sees. Returns { width, height, channels, data, scale, y } (y: the page y of row 0).
+export async function captureFull(page, { clip, maxHeight = 24_000 } = {}) {
+  const view = await page.evaluate(() => ({ vw: innerWidth, vh: innerHeight, top: scrollY }));
+  const parts = [];
+  let scale = 1;
+  const x = clip ? Math.max(0, Math.round(clip.x)) : 0;
+  const width = clip ? Math.min(view.vw - x, Math.round(clip.width)) : view.vw;
+  const y0 = clip ? Math.max(0, Math.round(clip.y)) : 0;
+  try {
+    // Snapping and smooth scrolling off before the first scroll.
+    await page.evaluate(PINS, "tile");
+    let y = y0;
+    for (let guard = 0; guard < 200; guard++) {
+      // The page can grow while it's captured (late content): measure again each screen.
+      const h = Math.min(await page.evaluate(FULL_HEIGHT), y0 + maxHeight);
+      const end = clip ? Math.min(Math.round(clip.y + clip.height), h) : h;
+      if (y >= end) break;
+      // Again when something else moved it meanwhile (a smooth scroll or a snap still running).
+      const target = Math.min(y, Math.max(0, h - view.vh));
+      let s = -1;
+      for (let k = 0; k < 3 && s !== target; k++) {
+        await page.evaluate((top) => window.scrollTo({ top, left: 0, behavior: "instant" }), target);
+        await settle(page, { wait: 500 });
+        s = await page.evaluate(PINS, "tile");
+      }
+      await page.evaluate(() => new Promise((r) => (requestAnimationFrame(() => requestAnimationFrame(r)), setTimeout(r, 250))));
+      // The screen shows the page from s to s + vh; stop when it can't scroll to y (a page that scrolls inside).
+      if (s > y || s + view.vh <= y) break;
+      const take = Math.min(end, s + view.vh) - y;
+      const img = decodePng(await page.screenshot({ clip: { x, y: y - s, width, height: take } }));
+      scale = img.width / width;
+      parts.push(img);
+      y += take;
+    }
+  } finally {
+    await page.evaluate(PINS, "end").catch(() => {});
+    await page.evaluate((top) => window.scrollTo({ top, left: 0, behavior: "instant" }), view.top).catch(() => {});
+    await settle(page, { wait: 500 });
+  }
+  if (!parts.length) throw new Error("nothing to capture: the page has no height");
+  return { ...stackImages(parts), scale, y: y0 };
+}
+
+// captureFull written to a PNG file. Returns the image.
+export async function shootFull(page, file, opts) {
+  const img = await captureFull(page, opts);
+  writePng(file, img);
+  return img;
+}
+
+export const findSections = (page) => page.evaluate(`(${sectionsScript})()`);
+
+// One crop per section, full width so its margins show, cut from one capture of the page (so a sticky header
+// shows only where it belongs, and every crop shows the page as measured). image: a captureFull of this page
+// to cut from (gate passes its full-page capture); without it the part of the page the sections cover is
+// captured.
+export async function cropSections(page, sections, outDir, prefix, { maxHeight = 2400, image } = {}) {
+  fs.mkdirSync(outDir, { recursive: true });
+  const boxes = sections.filter((s) => s.box.width >= 10 && Math.min(s.box.height, maxHeight) >= 10);
+  if (!boxes.length) return [];
+  const top = Math.max(0, Math.min(...boxes.map((s) => s.box.y)));
+  const bottom = Math.max(...boxes.map((s) => s.box.y + Math.min(s.box.height, maxHeight)));
+  const img = image ?? (await captureFull(page, { clip: { x: 0, y: top, width: 1e6, height: bottom - top } }));
+  const out = [];
+  for (const s of boxes) {
+    const { y, height } = s.box;
+    const crop = cropImage(img, { y: (Math.max(0, y) - img.y) * img.scale, height: Math.min(height, maxHeight) * img.scale });
+    if (!crop || crop.height < 10) continue;
+    const file = path.join(outDir, `${prefix}-${String(s.index).padStart(2, "0")}-${s.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32) || s.tag}.png`);
+    writePng(file, crop);
+    out.push({ ...s, file, cropped: height > maxHeight });
+  }
+  return out;
+}
+
+// Finds a section by name, heading, id or CSS selector (case-insensitive substring for words).
+export async function matchSection(page, sections, query) {
+  const q = query.trim().toLowerCase();
+  const byWords = sections.find((s) => [s.name, s.heading, s.id].some((v) => v && v.toLowerCase() === q)) ?? sections.find((s) => [s.name, s.heading, s.id, s.selector].some((v) => v && v.toLowerCase().includes(q)));
+  if (byWords) return byWords;
+  // A selector: the section that contains (or is) the matched element.
+  const hit = await page
+    .evaluate((sel) => {
+      const el = document.querySelector(sel);
+      if (!el) return null;
+      const r = el.getBoundingClientRect();
+      return { y: r.top + scrollY, h: r.height };
+    }, query)
+    .catch(() => null);
+  if (!hit) return null;
+  return sections.find((s) => hit.y >= s.box.y - 1 && hit.y + hit.h <= s.box.y + s.box.height + 1) ?? null;
+}
+
+const dataUri = (f) => `data:image/${/\.jpe?g$/i.test(f) ? "jpeg" : "png"};base64,${fs.readFileSync(f).toString("base64")}`;
+const esc = (s) => String(s ?? "").replace(/[<>&"]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;" })[c]);
+
+// A labelled grid of images: rows of { label, cells: [{ caption, file }] }. One file the agent reads cheaply.
+export async function contactSheet(browser, rows, out, { cell = 300, maxCell = 420 } = {}) {
+  const cols = Math.max(...rows.map((r) => r.cells.length), 1);
+  const html = rows
+    .map(
+      (r) => `<div class="row">${r.label ? `<div class="label">${esc(r.label)}</div>` : ""}<div class="cells" style="grid-template-columns:repeat(${cols},${cell}px)">${r.cells
+        .map((c) => `<figure>${c.caption ? `<figcaption>${esc(c.caption)}</figcaption>` : ""}${c.file ? `<img src="${dataUri(c.file)}">` : `<div class="empty">${esc(c.note ?? "")}</div>`}</figure>`)
+        .join("")}</div></div>`,
+    )
+    .join("");
+  const page = await browser.newPage({ viewport: { width: Math.min(4000, cols * (cell + 12) + 40), height: 800 } });
+  try {
+    await page.setContent(`<!doctype html><body style="margin:0;background:#ecebe7;font:600 14px system-ui;color:#191917"><div id="g">${html}</div><style>#g{display:inline-block;padding:12px}.row{margin-bottom:14px}.label{margin:0 0 6px;font-size:15px}.cells{display:grid;gap:10px;align-items:start}figure{margin:0}figcaption{font:500 12px system-ui;margin-bottom:4px;color:#444}img{width:${cell}px;max-height:${maxCell}px;object-fit:cover;object-position:top;display:block;border:1px solid #c9c8c2;background:#fff}.empty{width:${cell}px;height:60px;display:grid;place-items:center;border:1px dashed #b5b4ad;font:500 12px system-ui;color:#666}</style></body>`);
+    await page.locator("#g").screenshot({ path: out });
+  } finally {
+    await page.close();
+  }
+  return out;
+}
+
+export const NOT_FOUND_ROUTE = /^\/(404|_?not-found)\/?$/i;
+
+// A route file that renders nothing of its own yet: the bench template's `<main></main>`, or a starter's demo
+// page (create-vite's counter, create-next-app's "Get started by editing"). Such a page is new, not existing:
+// there is nothing on it to keep.
+const STARTER_TEXT = /Vite \+ React|count is|Edit <code>|Get started by editing|Learn React|to test HMR|Welcome to (Nuxt|SvelteKit|Astro|Remix)/;
+export function isScaffold(file) {
+  let src;
+  try {
+    src = fs.readFileSync(file, "utf8");
+  } catch {
+    return false;
+  }
+  if (STARTER_TEXT.test(src) && src.length < 6000) return true;
+  if (src.length > 4000) return false;
+  const code = src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1").replace(/^\s*import\s[^;\n]*;?\s*$/gm, "");
+  // Its own components (<Hero />, <Nav>) mean it renders something.
+  if ((code.match(/<([A-Z][\w.]*)/g) ?? []).some((t) => !/^<(React\.)?Fragment$/.test(t))) return false;
+  const words = (code.match(/>([^<>{}]+)</g) ?? []).flatMap((m) => m.slice(1, -1).trim().split(/\s+/)).filter((w) => /[a-z]{2,}/i.test(w));
+  return words.length <= 3;
+}
+
+// The source file that renders a route, for file-based routers (Next app/pages, Vite file routes, SvelteKit,
+// Nuxt, Astro, Remix). Route groups like (marketing) are skipped. Returns null when routing is in code.
+export function routeFile(dir, route) {
+  const segs = normalizeRoute(route).split("/").filter(Boolean);
+  const exts = ["tsx", "jsx", "ts", "js", "vue", "svelte", "astro", "mdx"];
+  const roots = ["src/app", "app", "src/pages", "pages", "src/routes", "app/routes"].map((r) => path.join(dir, r)).filter((r) => fs.existsSync(r));
+  // The not-found page has its own file: not-found.tsx (Next app router), 404.tsx (Next pages router, Astro,
+  // Nuxt), +error.svelte (SvelteKit).
+  if (NOT_FOUND_ROUTE.test(normalizeRoute(route)))
+    for (const r of roots)
+      for (const n of ["not-found", "404", "+error"]) for (const e of exts) if (fs.existsSync(path.join(r, `${n}.${e}`))) return { file: path.join(r, `${n}.${e}`), root: r };
+  const pageNames = ["page", "+page", "index", "route", "_index"];
+  const find = (base, rest) => {
+    if (!rest.length) {
+      for (const n of pageNames) for (const e of exts) if (fs.existsSync(path.join(base, `${n}.${e}`))) return path.join(base, `${n}.${e}`);
+    } else {
+      for (const e of exts) if (rest.length === 1 && fs.existsSync(path.join(base, `${rest[0]}.${e}`))) return path.join(base, `${rest[0]}.${e}`);
+      if (fs.existsSync(path.join(base, rest[0]))) {
+        const hit = find(path.join(base, rest[0]), rest.slice(1));
+        if (hit) return hit;
+      }
+    }
+    // Route groups don't add a segment.
+    if (fs.existsSync(base))
+      for (const e of fs.readdirSync(base, { withFileTypes: true }))
+        if (e.isDirectory() && /^\(.+\)$/.test(e.name)) {
+          const hit = find(path.join(base, e.name), rest);
+          if (hit) return hit;
+        }
+    return null;
+  };
+  for (const r of roots) {
+    const hit = find(r, segs);
+    if (hit) return { file: hit, root: r };
+  }
+  // A single-page app with no file routing (Vite, CRA): "/" is its App component.
+  if (!roots.length && !segs.length)
+    for (const base of ["src/App", "src/app", "App"]) for (const e of exts) if (fs.existsSync(path.join(dir, `${base}.${e}`))) return { file: path.join(dir, `${base}.${e}`), root: path.join(dir, path.dirname(base)) };
+  return null;
+}