design-qa-capture 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# design-qa-capture
+
+Local authenticated browser capture runner for Design QA comparisons.
+
+## Usage
+
+```bash
+npx design-qa-capture@latest capture <capture-token>
+```
+
+The command opens a browser window, lets you sign in or navigate to the exact screen to review, captures the page, and uploads the screenshot plus DOM element metadata back to Design QA.
+
+## Options
+
+```bash
+npx design-qa-capture@latest capture <capture-token> --api https://app.quality.dev
+npx design-qa-capture@latest capture <capture-token> --settle 5000
+```
+
+- `--api`: Design QA app origin. Defaults to `DESIGN_QA_API`, then `QUALITY_API`, then `https://app.quality.dev`.
+- `--settle`: Extra wait time in milliseconds before capture. Defaults to `3500`.
+
+Sessions are stored under `~/.design-qa/<host>.json` so repeat captures can reuse login state.

package/dist/index.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { createInterface } from "node:readline/promises";
+
+// ../packages/core/src/capture.ts
+import { chromium } from "playwright";
+async function captureFromPage(page, opts = {}) {
+  const maxHeightPx = opts.maxHeightPx ?? 2e4;
+  const fullPage = opts.fullPage ?? true;
+  const viewport = page.viewportSize() ?? { width: 1280, height: 720 };
+  await freezeVolatileRendering(page);
+  await page.waitForTimeout(100);
+  const dimensions = fullPage ? await page.evaluate(`(() => {
+        const doc = document.documentElement;
+        const body = document.body;
+        return {
+          width: Math.ceil(Math.max(doc.scrollWidth, body?.scrollWidth ?? 0, window.innerWidth)),
+          height: Math.ceil(Math.max(doc.scrollHeight, body?.scrollHeight ?? 0, window.innerHeight)),
+        };
+      })()`) : { width: viewport.width, height: viewport.height };
+  const height = Math.min(dimensions.height, maxHeightPx);
+  const cappedOut = dimensions.height > maxHeightPx;
+  const elements = opts.extractElements ? await extractElements(page, height) : [];
+  const png = await page.screenshot(
+    !fullPage ? { type: "png" } : cappedOut ? { type: "png", clip: { x: 0, y: 0, width: dimensions.width, height } } : { type: "png", fullPage: true }
+  );
+  return { png, width: dimensions.width, height, fullHeight: dimensions.height, cappedOut, elements };
+}
+async function extractElements(page, maxY) {
+  const raw = await page.evaluate(`(() => {
+    const selector = "a,button,h1,h2,h3,h4,h5,h6,p,span,li,label,img,input,svg";
+    const out = [];
+    for (const el of Array.from(document.querySelectorAll(selector))) {
+      const r = el.getBoundingClientRect();
+      if (r.width < 8 || r.height < 6) continue;
+      const tag = el.tagName.toLowerCase();
+      const htmlEl = el;
+      const style = window.getComputedStyle(el);
+      const raw =
+        tag === "img"
+          ? el.alt
+          : tag === "input"
+            ? el.value || el.placeholder
+            : htmlEl.innerText || el.textContent || "";
+      const text = cleanElementText(raw, 80);
+      const ariaLabel = cleanElementText(el.getAttribute("aria-label") || "", 80);
+      const role = cleanElementText(el.getAttribute("role") || "", 32);
+      const title = cleanElementText(el.getAttribute("title") || "", 80);
+      const semanticLabel = ariaLabel || title;
+      if (!text && !semanticLabel && tag !== "img" && tag !== "svg") continue;
+      out.push({
+        text,
+        tag,
+        ...(role ? { role } : {}),
+        ...(ariaLabel ? { ariaLabel } : {}),
+        x: r.left + window.scrollX,
+        y: r.top + window.scrollY,
+        w: r.width,
+        h: r.height,
+        fontFamily: style.fontFamily,
+        fontSize: style.fontSize,
+        fontWeight: style.fontWeight,
+        color: style.color,
+        letterSpacing: style.letterSpacing,
+        backgroundColor: style.backgroundColor,
+      });
+    }
+
+    function cleanElementText(value, max) {
+      return value.trim().replace(/s+/g, " ").slice(0, max);
+    }
+
+    return out;
+  })()`);
+  return raw.filter((e) => e.y < maxY).slice(0, 800);
+}
+async function freezeVolatileRendering(page) {
+  try {
+    await page.addStyleTag({
+      content: `
+        *, *::before, *::after {
+          animation-delay: 0s !important;
+          animation-duration: 0s !important;
+          animation-iteration-count: 1 !important;
+          caret-color: transparent !important;
+          transition-delay: 0s !important;
+          transition-duration: 0s !important;
+        }
+        video {
+          visibility: hidden !important;
+        }
+      `
+    });
+  } catch {
+  }
+}
+
+// src/api.ts
+async function fetchTarget(apiBase, token, fetchImpl = fetch) {
+  const res = await fetchImpl(`${apiBase}/api/capture/${token}`, { method: "GET" });
+  if (res.status === 410) throw new Error("This capture link has expired. Start a new comparison and try again.");
+  if (res.status === 404) throw new Error("Capture link not found. Copy the command again from the comparison page.");
+  if (!res.ok) throw new Error(`Could not start capture (HTTP ${res.status}).`);
+  return await res.json();
+}
+async function uploadCapture(apiBase, token, args, fetchImpl = fetch) {
+  const form = new FormData();
+  form.append("live", new Blob([new Uint8Array(args.png)], { type: "image/png" }), "live.png");
+  form.append("elements", JSON.stringify({ width: args.width, height: args.height, elements: args.elements }));
+  const res = await fetchImpl(`${apiBase}/api/capture/${token}`, { method: "POST", body: form });
+  if (res.status === 410) throw new Error("This capture link has expired or was already used.");
+  if (!res.ok) throw new Error(`Upload failed (HTTP ${res.status}).`);
+  return await res.json();
+}
+
+// src/browser.ts
+import { execSync } from "node:child_process";
+import { chromium as chromium2 } from "playwright";
+
+// src/session.ts
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+function sessionPathForUrl(url, home = homedir()) {
+  const host = new URL(url).hostname;
+  return join(home, ".design-qa", `${host}.json`);
+}
+function sessionExists(sessionPath) {
+  return existsSync(sessionPath);
+}
+async function saveSession(context, sessionPath) {
+  await mkdir(join(sessionPath, ".."), { recursive: true });
+  await context.storageState({ path: sessionPath });
+}
+
+// src/browser.ts
+var LAUNCH_ARGS = ["--disable-blink-features=AutomationControlled"];
+var EVASION_SCRIPT = `
+  Object.defineProperty(navigator, "webdriver", { get: function () { return false; } });
+
+  var __noop = function () { return null; };
+  var __methods = ["log","debug","info","warn","error","table","dir","dirxml","group","groupCollapsed","trace"];
+  for (var __i = 0; __i < __methods.length; __i++) {
+    (function (m) {
+      var orig = typeof console[m] === "function" ? console[m].bind(console) : __noop;
+      console[m] = function () {
+        var args = Array.prototype.slice.call(arguments).map(function (a) {
+          try { return typeof a === "object" ? "[obj]" : a; } catch (e) { return "[?]"; }
+        });
+        return orig.apply(console, args);
+      };
+    })(__methods[__i]);
+  }
+
+  var __realOpen = typeof window.open === "function" ? window.open.bind(window) : null;
+  window.open = function (u, t, f) {
+    var url = typeof u === "string" ? u : (u ? String(u) : u);
+    if ((!url || url === "about:blank") && (t === "_self" || t === undefined)) return null;
+    return __realOpen ? __realOpen(u, t, f) : null;
+  };
+`;
+async function openAuthedContext(url, opts) {
+  const storageState = sessionExists(opts.sessionPath) ? opts.sessionPath : void 0;
+  let browser;
+  try {
+    browser = await chromium2.launch({ headless: false, channel: "chrome", args: LAUNCH_ARGS });
+  } catch {
+    try {
+      browser = await chromium2.launch({ headless: false, args: LAUNCH_ARGS });
+    } catch (bundledError) {
+      const ok = await opts.consentToDownload();
+      if (!ok) {
+        const detail = bundledError instanceof Error ? bundledError.message : String(bundledError);
+        throw new Error(`A browser is required to capture. Aborted. (${detail})`);
+      }
+      execSync("npx playwright install chromium", { stdio: "inherit" });
+      browser = await chromium2.launch({ headless: false, args: LAUNCH_ARGS });
+    }
+  }
+  const context = await browser.newContext({ viewport: { width: 1280, height: 800 }, storageState });
+  await context.route(/theajack\.github\.io/, (route) => route.abort());
+  await context.addInitScript({ content: EVASION_SCRIPT });
+  const page = await context.newPage();
+  try {
+    await page.goto(url, { waitUntil: "commit", timeout: 6e4 });
+  } catch (navError) {
+    const detail = navError instanceof Error ? navError.message : String(navError);
+    console.warn(`\u26A0 Couldn't auto-open ${url} (${detail}). Navigate there yourself in the open window.`);
+  }
+  return { context, page, close: async () => browser.close() };
+}
+async function waitForLogin(page, targetUrl, timeoutMs = 5 * 6e4) {
+  const target = new URL(targetUrl);
+  try {
+    await page.waitForFunction(
+      (path) => window.location.pathname === path,
+      target.pathname,
+      { timeout: timeoutMs, polling: 1e3 }
+    );
+  } catch {
+    throw new Error(`Timed out waiting for login. Make sure you signed in and reached: ${targetUrl}`);
+  }
+}
+
+// src/index.ts
+function arg(flag, fallback) {
+  const i = process.argv.indexOf(flag);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+async function confirm(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = (await rl.question(`${question} (Y/n) `)).trim().toLowerCase();
+  rl.close();
+  return answer === "" || answer === "y" || answer === "yes";
+}
+async function waitForEnter(prompt) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  await rl.question(`${prompt} `);
+  rl.close();
+}
+async function main() {
+  const [, , command, token] = process.argv;
+  if (command !== "capture" || !token) {
+    console.error("Usage: design-qa-capture capture <token>");
+    process.exit(1);
+  }
+  const apiBase = arg("--api", process.env.DESIGN_QA_API ?? process.env.QUALITY_API ?? "https://app.quality.dev");
+  const settleMs = Number(arg("--settle", "3500"));
+  const { url, comparisonId } = await fetchTarget(apiBase, token);
+  const sessionPath = sessionPathForUrl(url);
+  const reusing = sessionExists(sessionPath);
+  console.log(reusing ? `\u2714 Reusing saved session for ${new URL(url).hostname}.` : "\u2197 Opening a browser window so you can sign in\u2026");
+  const { context, page, close } = await openAuthedContext(url, {
+    sessionPath,
+    consentToDownload: () => confirm("No Chrome found. Download a one-time ~150 MB Chromium for Design QA?")
+  });
+  try {
+    if (process.stdin.isTTY) {
+      console.log("A browser window is open. Log in if needed and go to the screen you want to QA.");
+      await waitForEnter("When the page is fully loaded, press Enter here to capture\u2026");
+    } else if (!reusing) {
+      console.log("\u2026 waiting to reach the page (no TTY; detecting by URL).");
+      await waitForLogin(page, url).catch(() => {
+      });
+    }
+    await page.waitForLoadState("networkidle", { timeout: 15e3 }).catch(() => {
+    });
+    await page.evaluate(async () => {
+      if ("fonts" in document) await document.fonts.ready;
+    }).catch(() => {
+    });
+    await page.waitForTimeout(Number.isFinite(settleMs) ? settleMs : 3500);
+    console.log("Capturing\u2026");
+    const capture = await captureFromPage(page, { extractElements: true, fullPage: true });
+    await saveSession(context, sessionPath);
+    console.log(`\u2714 Captured (${capture.width}\xD7${capture.height}). Uploading\u2026`);
+    await uploadCapture(apiBase, token, { png: capture.png, width: capture.width, height: capture.height, elements: capture.elements });
+    console.log(`\u2714 Done. Session saved \u2192 ${sessionPath}`);
+    console.log(`View it: ${apiBase}/comparisons/${comparisonId}`);
+  } finally {
+    await close();
+  }
+}
+main().catch((error) => {
+  console.error(`\u2716 ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "design-qa-capture",
+  "version": "0.1.0",
+  "description": "Local authenticated browser capture runner for Design QA comparisons.",
+  "type": "module",
+  "bin": {
+    "design-qa-capture": "dist/index.js"
+  },
+  "files": [
+    "dist/index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node18 --outfile=dist/index.js --external:playwright --banner:js='#!/usr/bin/env node'",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "playwright": "^1.48.0"
+  },
+  "devDependencies": {
+    "@design-qa/core": "*",
+    "@types/node": "^22.10.2",
+    "esbuild": "^0.24.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}