transitions-agent 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# transitions-agent
+
+Scan your codebase for missing, janky, or inconsistent UI transitions. Get a motion score (0-100), findings with matching [transitions.dev](https://transitions.dev) recipes, AI-proposed fixes shown as diffs, and an optional pull request. Nothing is ever changed without your explicit confirmation, and nothing is ever pushed to your main branch.
+
+## Terminal
+
+```bash
+npx transitions-agent                     # scan: motion score + findings + recipes
+npx transitions-agent signup you@x.com    # free plan: license key arrives by email
+npx transitions-agent fix                 # propose fixes as diffs, confirm, apply
+npx transitions-agent fix --pr            # after applying: branch, commit, push, open a PR
+```
+
+The `fix` command sends the affected files to the hosted fix service (your license key, our AI). Without a license key it writes `transitions-agent-fixes.md`, a ready-made task for your own Claude Code, Cursor or Codex.
+
+### Fix modes
+
+| Mode | What it does | Risk |
+|---|---|---|
+| `--mode polish` (default) | Small safe adjustments only: durations onto motion tokens, `prefers-reduced-motion` guard, named properties instead of `transition: all`, missing transition lines on hover bases. Never restructures anything. | Minimal, few-line diffs |
+| `--mode revamp` (Business plan) | Superset of polish: confident recipe matches (modals, tooltips, dropdowns) get the recipe's full enter and exit motion, keyframes, and easing; every other finding gets the polish treatment. Logic is never touched. | Larger diffs, review the PR |
+
+```bash
+npx transitions-agent fix                # polish: safe token-level cleanup
+npx transitions-agent fix --mode revamp  # recipe-level motion rewrite
+```
+
+Flags: `--json`, `--md`, `--dir <path>`, `--min-score <n>` (exit 2 below n, for CI), `--mode polish|revamp`, `--license <key>` (or `TRANSITIONS_AGENT_LICENSE`), `--yes` (skip prompts).
+
+## GitHub Action
+
+Copy [templates/transitions-agent.yml](templates/transitions-agent.yml) to `.github/workflows/` in your repository. Every pull request then gets a motion score comment, and `min-score` can block merges when motion quality drops:
+
+```yaml
+- uses: actions/checkout@v4
+- uses: Jakubantalik/transitions.dev/agent@main
+  with:
+    min-score: "75"
+```
+
+## What it checks
+
+| Rule | What it catches |
+|---|---|
+| untransitioned-overlay | Modals, tooltips, dropdowns that pop in and out with no transition |
+| hover-without-transition | Hover states that snap instead of easing |
+| transition-all | `transition: all`, which animates layout and hurts performance |
+| hardcoded-duration | Literal durations instead of shared motion tokens |
+| no-reduced-motion | Animation with no `prefers-reduced-motion` guard |
+| inconsistent-durations | Too many different duration values across the project |
+
+## MCP server (your AI, our recipes)
+
+Prefer your own Claude to do the fixing? Connect the Transitions Agent MCP server and your assistant gets the scanner contract, the fix guidance, and the real recipe sources (Pro included on Business) - fixing runs on your subscription, not our meters:
+
+```bash
+claude mcp add --transport http transitions-agent https://api.transitions.dev/v1/agent/mcp --header "Authorization: Bearer $TRANSITIONS_AGENT_LICENSE"
+```
+
+Tools: `scan_instructions`, `fix_guidance(mode)`, `list_recipes`, `get_recipe(slug, variant)`. Free recipes need no key; Pro recipe sources need a paid plan (Pro, Business, or Enterprise).
+
+### Fixing from CI
+
+Two workflow templates, pick by who supplies the AI:
+
+- **[transitions-fix.yml](templates/transitions-fix.yml)** (Business, zero friction): one secret - the license key. Fixes run through the hosted service on our AI, metered against the plan's 200/month, and land as a pull request.
+- **[transitions-fix-own-claude.yml](templates/transitions-fix-own-claude.yml)** (Enterprise license required): runs `claude-code-action` on your own Anthropic key, connected to this MCP server. Unmetered, and your code never flows through our fix service - it goes only to Anthropic under your own agreement. CI automation on your own model keys is licensed on the Enterprise plan (org-wide license, custom rules, priority support); Business licenses hosted CI fixing only.
+
+The score/gate Action stays AI-free either way.
+
+## Safety model
+
+1. Proposed fixes are shown as diffs first; nothing is written without a yes.
+2. `--pr` opens a pull request on a new branch; your team reviews, your tests run, a human merges.
+3. Everything is git; any merged fix is one `git revert` away.
+4. Fixes touch motion only (CSS transitions, animation guards), never logic.
+
+## Hosted fix service
+
+`worker/` contains the Cloudflare Worker behind `api.transitions.dev/v1/agent/fix`: it validates the license key, meters monthly fix quota, and calls Claude with the service key. Teams never handle an AI key. See [worker/wrangler.toml](worker/wrangler.toml) for deployment.
+
+In revamp mode the service feeds the model the real transitions.dev recipe sources, Pro recipes included, so rewrites match the library exactly instead of an approximation. [worker/pack-recipes.mjs](worker/pack-recipes.mjs) packs the free and Pro recipe files into the RECIPES KV namespace; re-run it whenever recipes change.
+
+## Plans
+
+| | Scan + score + Action | Fix via your own Claude Code/Cursor | Hosted polish fixes | Hosted revamp (Pro recipes) |
+|---|---|---|---|---|
+| **Free** (sign-up) | unlimited | unlimited | 10/month, 2/day | no |
+| **Business** ($59/month, includes Transitions Pro for 5 seats) | unlimited | unlimited | 200/month | yes |
+
+The Transitions.dev **Pro** plan ($9/month) includes the free Agent tier; the paid Agent comes with the **Business** plan. In the license KV the paid tier is still stored as `plan:"team"`.
+
+Free hosted fixes run on a faster model and share a global monthly capacity pool (`FREE_GLOBAL_MONTHLY` in [worker/wrangler.toml](worker/wrangler.toml)), so free-tier AI spend has a hard ceiling. Team traffic is never affected by the pool.
+
+MIT for the scanner and CLI. The fix service requires a Transitions Agent license from [transitions.dev](https://transitions.dev).

package/bin/transitions-agent.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// transitions-agent: scan a codebase for missing or janky UI transitions.
+//
+//   npx transitions-agent                 scan + motion score + findings
+//   npx transitions-agent signup you@x.co  free plan: license key by email
+//   npx transitions-agent fix             propose AI fixes as diffs, confirm, apply
+//   npx transitions-agent fix --pr        after applying, open a pull request
+//
+// Fix modes (--mode):
+//   polish (default)   small safe adjustments only: motion tokens, reduced-motion
+//                      guard, named transition properties. Never restructures.
+//   revamp             full rewrite where a finding matches a transitions.dev
+//                      recipe (modals, tooltips, dropdowns, hovers).
+//
+// Flags:
+//   --json               machine-readable report on stdout
+//   --md                 GitHub-flavored markdown report on stdout
+//   --min-score <n>      exit 2 when the score is below n (CI gate)
+//   --dir <path>         project root to scan (default: cwd)
+//   --license <key>      fix service license (or TRANSITIONS_AGENT_LICENSE)
+//   --api <url>          fix service URL (default https://api.transitions.dev)
+//   --yes                skip confirmation prompts (CI)
+//
+// No dependencies. Node 18+.
+import { scan } from "../lib/scan.mjs";
+import { renderTerminal, renderMarkdown } from "../lib/report.mjs";
+import { runFix } from "../lib/fix.mjs";
+import { resolve } from "node:path";
+
+const args = process.argv.slice(2);
+const flags = {};
+const positional = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--dir") flags.dir = args[++i];
+  else if (args[i] === "--mode") flags.mode = args[++i];
+  else if (args[i] === "--api") flags.api = args[++i];
+  else if (args[i] === "--license") flags.license = args[++i];
+  else if (args[i] === "--min-score") flags.minScore = parseInt(args[++i], 10);
+  else if (args[i].startsWith("--")) flags[args[i].slice(2)] = true;
+  else positional.push(args[i]);
+}
+
+const root = resolve(flags.dir || ".");
+const command = positional[0] || "scan";
+const api = (flags.api || process.env.TRANSITIONS_AGENT_API || "https://api.transitions.dev").replace(/\/$/, "");
+
+if (command === "signup") {
+  const email = (positional[1] || "").trim();
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+    console.error("Usage: transitions-agent signup you@company.com");
+    process.exit(1);
+  }
+  let res;
+  try {
+    res = await fetch(api + "/agent/signup", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ email }),
+    });
+  } catch (e) {
+    console.error("Could not reach " + api + ": " + e.message);
+    process.exit(1);
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    console.error("Signup failed: " + (err.error || res.status));
+    process.exit(1);
+  }
+  console.log(`Check ${email} for your free license key (10 hosted polish fixes/month).`);
+  console.log("Then: export TRANSITIONS_AGENT_LICENSE=<key from the email>");
+  process.exit(0);
+}
+
+const result = scan(root);
+
+if (command === "scan") {
+  if (flags.json) console.log(JSON.stringify(result, null, 2));
+  else if (flags.md) console.log(renderMarkdown(result));
+  else console.log(renderTerminal(result));
+  if (Number.isFinite(flags.minScore) && result.score < flags.minScore) {
+    console.error(`Motion score ${result.score} is below the required minimum ${flags.minScore}.`);
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+if (command === "fix") {
+  const mode = flags.mode || "polish";
+  if (mode !== "polish" && mode !== "revamp") {
+    console.error(`Unknown mode "${mode}". Use --mode polish or --mode revamp.`);
+    process.exit(1);
+  }
+  console.log(renderTerminal(result));
+  const code = await runFix(root, result, {
+    mode,
+    api,
+    license: flags.license || process.env.TRANSITIONS_AGENT_LICENSE || "",
+    yes: !!flags.yes,
+    pr: !!flags.pr,
+  });
+  process.exit(code);
+}
+
+console.error(`Unknown command "${command}". Use: transitions-agent [scan|fix|signup]`);
+process.exit(1);

package/lib/fix.mjs

@@ -0,0 +1,180 @@
+// Fix flow: send findings + files to the transitions.dev fix service (option C:
+// the service holds the AI key), show proposed diffs, apply only after an
+// explicit yes, optionally open a pull request after a second explicit yes.
+import { readFileSync, writeFileSync, mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync, spawnSync } from "node:child_process";
+import readline from "node:readline";
+
+const MAX_FILES = 12;
+const MAX_FILE_BYTES = 40_000;
+
+const c = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+};
+
+// polish: token-level adjustments only. revamp: adds structural recipe rewrites.
+const POLISH_RULES = new Set([
+  "hardcoded-duration", "transition-all", "no-reduced-motion",
+  "inconsistent-durations", "hover-without-transition",
+]);
+
+export function findingsForMode(findings, mode) {
+  if (mode === "revamp") return findings;
+  return findings.filter((f) => POLISH_RULES.has(f.rule));
+}
+
+export async function runFix(root, result, opts) {
+  const { api, license, yes, pr, mode = "polish" } = opts;
+  const findings = findingsForMode(result.findings, mode);
+  const skipped = result.findings.length - findings.length;
+  if (skipped > 0) {
+    console.log(c.dim(`${skipped} structural findings need --mode revamp and are skipped in polish mode.`));
+  }
+  const fixable = findings.filter((f) => f.path !== "(project)");
+  if (!fixable.length && !findings.length) {
+    console.log(c.green("Nothing to fix" + (mode === "polish" ? " in polish mode." : ".")));
+    return 0;
+  }
+
+  const paths = [...new Set(fixable.map((f) => f.path))].slice(0, MAX_FILES);
+  const dropped = [...new Set(fixable.map((f) => f.path))].length - paths.length;
+  const files = [];
+  for (const p of paths) {
+    try {
+      const content = readFileSync(join(root, p), "utf8");
+      if (Buffer.byteLength(content) <= MAX_FILE_BYTES) files.push({ path: p, content });
+    } catch { /* file may be gone */ }
+  }
+
+  if (!license) {
+    writePromptFallback(root, findings, files, mode);
+    return 0;
+  }
+
+  console.log(c.dim(`Requesting ${mode} fixes for ${files.length} files${dropped > 0 ? ` (${dropped} deferred to a later run)` : ""}...`));
+  let res;
+  try {
+    res = await fetch(api + "/v1/agent/fix", {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: "Bearer " + license },
+      body: JSON.stringify({ mode, findings, files, score: result.score }),
+    });
+  } catch (e) {
+    console.error(c.red("✗ ") + "Could not reach the fix service: " + e.message);
+    return 1;
+  }
+  if (res.status === 401) { console.error(c.red("✗ ") + "License key not valid. Check TRANSITIONS_AGENT_LICENSE."); return 1; }
+  if (res.status === 403 || res.status === 429) {
+    const err = await res.json().catch(() => ({}));
+    if (err.error === "revamp requires team") {
+      console.error(c.yellow("Revamp mode is a Team plan feature") + " (full recipe rewrites, Pro library).");
+      console.error("Your free plan includes polish mode. Upgrade at " + c.bold("transitions.dev/pro") + " or run without --mode revamp.");
+    } else {
+      console.error(c.red("✗ ") + (err.detail || "Monthly fix quota reached. Upgrade at transitions.dev/pro."));
+    }
+    return 1;
+  }
+  if (!res.ok) { console.error(c.red("✗ ") + `Fix service error (${res.status}).`); return 1; }
+  const data = await res.json();
+  const proposed = (data.files || []).filter((f) => f.path && typeof f.content === "string");
+  if (!proposed.length) { console.log(c.yellow("The service proposed no changes.")); return 0; }
+
+  // Show each proposal as a diff. Nothing is written yet.
+  for (const p of proposed) showDiff(root, p);
+  if (data.summary) console.log("\n" + data.summary + "\n");
+  if (data.usage) console.log(c.dim(`Fixes used this month: ${data.usage.used}/${data.usage.quota}`));
+
+  const apply = yes || await confirm(`Apply these changes to ${proposed.length} files? [y/N] `);
+  if (!apply) { console.log(c.dim("Nothing changed.")); return 0; }
+  for (const p of proposed) writeFileSync(join(root, p.path), p.content);
+  console.log(c.green("✓ ") + `Applied ${proposed.length} files.`);
+
+  if (!pr) {
+    console.log(c.dim("Review with git diff. Re-run with --pr to open a pull request."));
+    return 0;
+  }
+  return openPr(root, result, proposed, { yes, mode });
+}
+
+function showDiff(root, proposal) {
+  // git diff --no-index gives a familiar colored diff without touching the repo.
+  const tmp = mkdtempSync(join(tmpdir(), "tagent-"));
+  const tmpFile = join(tmp, "proposed");
+  writeFileSync(tmpFile, proposal.content);
+  const out = spawnSync("git", ["diff", "--no-index", "--color=always", "--", proposal.path, tmpFile], {
+    cwd: root, encoding: "utf8", maxBuffer: 10_000_000,
+  });
+  console.log("\n" + c.bold(proposal.path));
+  const body = (out.stdout || "").split("\n").slice(4).join("\n").trim();
+  console.log(body || c.dim("(no change)"));
+}
+
+async function openPr(root, result, proposed, { yes, mode }) {
+  const go = yes || await confirm("Create a branch, commit, push, and open a pull request? [y/N] ");
+  if (!go) { console.log(c.dim("Changes stay local. Commit them yourself when ready.")); return 0; }
+  const branch = `transitions-agent/${mode}-` + new Date().toISOString().slice(0, 10);
+  const title = mode === "revamp"
+    ? `Revamp UI transitions with transitions.dev recipes (motion score ${result.score} before fixes)`
+    : `Polish UI transitions (motion score ${result.score} before fixes)`;
+  const body = [
+    `Automated ${mode} pass by [Transitions Agent](https://transitions.dev).`,
+    "",
+    ...proposed.map((p) => `- \`${p.path}\``),
+    "",
+    "Every change was shown as a diff and confirmed in the terminal before this PR was opened.",
+  ].join("\n");
+  try {
+    execFileSync("git", ["checkout", "-b", branch], { cwd: root, stdio: "pipe" });
+    execFileSync("git", ["add", ...proposed.map((p) => p.path)], { cwd: root, stdio: "pipe" });
+    execFileSync("git", ["commit", "-m", `fix(motion): transitions-agent ${mode} pass`], { cwd: root, stdio: "pipe" });
+    execFileSync("git", ["push", "-u", "origin", branch], { cwd: root, stdio: "inherit" });
+  } catch (e) {
+    console.error(c.red("✗ ") + "Git step failed: " + (e.stderr?.toString() || e.message));
+    return 1;
+  }
+  const gh = spawnSync("gh", ["pr", "create", "--title", title, "--body", body], { cwd: root, stdio: "inherit" });
+  if (gh.status !== 0) {
+    console.log(c.yellow("Could not open the PR automatically (is GitHub CLI installed?)."));
+    console.log("Branch " + c.bold(branch) + " is pushed. Open the PR from GitHub with this description:\n\n" + body);
+  }
+  return 0;
+}
+
+function writePromptFallback(root, findings, files, mode) {
+  // No license: hand the work to the user's own coding agent instead.
+  const out = join(root, "transitions-agent-fixes.md");
+  const modeBrief = mode === "revamp"
+    ? "Where a finding names a recipe, replace the existing motion wholesale with that transitions.dev recipe pattern. You may add keyframes and classes, but never change component logic."
+    : "Make only small, safe adjustments: move durations to motion tokens, add a prefers-reduced-motion guard, replace transition: all with named properties, add missing transition declarations. Do not restructure markup, components, or keyframes.";
+  const lines = [
+    `# ${mode === "revamp" ? "Revamp" : "Polish"} the UI transitions in this repository`,
+    "",
+    "You are working in this repository. Apply fixes for the findings below using",
+    "production-quality CSS transitions (respect prefers-reduced-motion, use motion",
+    "tokens, animate transform and opacity rather than layout). Recipes: https://transitions.dev",
+    "",
+    modeBrief,
+    "",
+    "## Findings",
+    ...findings.map((f) => `- ${f.path}${f.line ? ":" + f.line : ""} [${f.rule}] ${f.message}${f.recipe ? ` (recipe: https://transitions.dev/transitions/${f.recipe})` : ""}`),
+    "",
+    "Affected files: " + files.map((f) => f.path).join(", "),
+  ];
+  writeFileSync(out, lines.join("\n"));
+  console.log(c.yellow("No license key found") + c.dim(" (set TRANSITIONS_AGENT_LICENSE for hosted fixes)."));
+  console.log("Wrote " + c.bold("transitions-agent-fixes.md") + ". Hand it to Claude Code or Cursor:");
+  console.log(c.dim("  claude \"apply transitions-agent-fixes.md\""));
+}
+
+function confirm(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => { rl.close(); resolve(/^y(es)?$/i.test(answer.trim())); });
+  });
+}

package/lib/report.mjs

@@ -0,0 +1,84 @@
+// Report rendering: terminal (colored) and GitHub-flavored markdown.
+
+const c = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+
+const RULE_TITLES = {
+  "untransitioned-overlay": "Overlays with no enter/exit transition",
+  "hover-without-transition": "Hover states that snap",
+  "transition-all": "transition: all",
+  "hardcoded-duration": "Hardcoded durations (no motion tokens)",
+  "no-reduced-motion": "No prefers-reduced-motion guard",
+  "inconsistent-durations": "Inconsistent duration scale",
+};
+
+const SEV_ICON = { major: c.red("●"), warn: c.yellow("●"), minor: c.dim("●"), info: c.cyan("●") };
+
+export function renderTerminal(result) {
+  const lines = [];
+  const scoreColor = result.score >= 90 ? c.green : result.score >= 75 ? c.cyan : result.score >= 50 ? c.yellow : c.red;
+  lines.push("");
+  lines.push(c.bold("  transitions-agent") + c.dim(`  scanned ${result.scannedFiles} files`));
+  lines.push("");
+  lines.push("  Motion score  " + scoreColor(c.bold(`${result.score} / 100`)) + c.dim(`  (${result.grade})`));
+  // Gauge: 20 cells, filled portion in the score color.
+  const filled = Math.round(result.score / 5);
+  lines.push("  " + scoreColor("█".repeat(filled)) + c.dim("░".repeat(20 - filled)));
+  lines.push("");
+  if (!result.findings.length) {
+    lines.push(c.green("  No issues found. Your motion is in good shape."));
+    lines.push("");
+    return lines.join("\n");
+  }
+  const byRule = groupBy(result.findings, (f) => f.rule);
+  for (const [rule, list] of Object.entries(byRule)) {
+    lines.push("  " + SEV_ICON[list[0].severity] + " " + c.bold(RULE_TITLES[rule] || rule) + c.dim(`  (${list.length})`));
+    for (const f of list.slice(0, 5)) {
+      const loc = f.line ? `${f.path}:${f.line}` : f.path;
+      lines.push(c.dim("      " + loc) + "  " + f.message.slice(0, 110));
+      if (f.recipe) lines.push(c.dim("      fix recipe: ") + c.cyan(`transitions.dev/transitions/${f.recipe}`));
+    }
+    if (list.length > 5) lines.push(c.dim(`      ... and ${list.length - 5} more`));
+    lines.push("");
+  }
+  lines.push(c.dim("  Run ") + c.bold("npx transitions-agent fix") + c.dim(" to get fixes proposed as diffs, then an optional PR."));
+  lines.push("");
+  return lines.join("\n");
+}
+
+export function renderMarkdown(result, opts = {}) {
+  const { previousScore } = opts;
+  const lines = [];
+  lines.push("<!-- transitions-agent -->");
+  lines.push(`### ✨ Transitions Agent`);
+  lines.push("");
+  const delta = previousScore != null ? ` (was ${previousScore})` : "";
+  lines.push(`**Motion score: ${result.score} / 100** (${result.grade})${delta}, scanned ${result.scannedFiles} files.`);
+  lines.push("");
+  if (!result.findings.length) {
+    lines.push("No motion issues found. 🎉");
+    return lines.join("\n");
+  }
+  const byRule = groupBy(result.findings, (f) => f.rule);
+  lines.push("| Issue | Count | Where |");
+  lines.push("|---|---|---|");
+  for (const [rule, list] of Object.entries(byRule)) {
+    const where = list.slice(0, 3).map((f) => f.line ? `\`${f.path}:${f.line}\`` : `\`${f.path}\``).join("<br>");
+    lines.push(`| ${RULE_TITLES[rule] || rule} | ${list.length} | ${where}${list.length > 3 ? "<br>..." : ""} |`);
+  }
+  lines.push("");
+  lines.push("Run `npx transitions-agent` locally for details, or `npx transitions-agent fix` to get fixes as a pull request.");
+  return lines.join("\n");
+}
+
+function groupBy(arr, key) {
+  const out = {};
+  for (const x of arr) (out[key(x)] ||= []).push(x);
+  return out;
+}

package/lib/rules.mjs

@@ -0,0 +1,135 @@
+// Deterministic motion rules. Each rule returns findings:
+//   { rule, severity, path, line, message, snippet?, recipe? }
+// severity: "major" | "warn" | "minor" | "info"
+import { lineOf } from "./walk.mjs";
+
+const CSSISH = new Set([".css", ".scss", ".less", ".html", ".vue", ".svelte", ".jsx", ".tsx", ".js", ".mjs", ".ts"]);
+const STYLESHEET = new Set([".css", ".scss", ".less"]);
+const JSXISH = new Set([".jsx", ".tsx", ".js", ".mjs", ".ts"]);
+
+// Matches "transition: opacity 300ms" / "animation-duration: .3s" with a literal time.
+const DURATION_RE = /\b(transition|animation)(?:-duration)?\s*:\s*([^;}"']*\b\d*\.?\d+m?s\b[^;}"']*)/g;
+const TIME_RE = /(\d*\.?\d+)(ms|s)\b/g;
+
+export function runRules(files) {
+  const findings = [];
+  const durations = []; // { value(ms), path, line }
+  let hasAnimation = false;
+  let hasReducedMotion = false;
+
+  for (const f of files) {
+    if (!CSSISH.has(f.ext)) continue;
+    const src = f.content;
+
+    if (/prefers-reduced-motion/.test(src)) hasReducedMotion = true;
+    if (/@keyframes|\banimation(?:-name)?\s*:/.test(src)) hasAnimation = true;
+
+    // hardcoded-duration + duration collection
+    DURATION_RE.lastIndex = 0;
+    let m;
+    while ((m = DURATION_RE.exec(src))) {
+      const valuePart = m[2];
+      TIME_RE.lastIndex = 0;
+      let t;
+      let realTimes = 0;
+      while ((t = TIME_RE.exec(valuePart))) {
+        const ms = t[2] === "s" ? parseFloat(t[1]) * 1000 : parseFloat(t[1]);
+        // Values of 20ms or less are effectively instant; they are almost always
+        // prefers-reduced-motion overrides, not real motion.
+        if (ms <= 20) continue;
+        realTimes++;
+        durations.push({ ms, path: f.path, line: lineOf(src, m.index) });
+      }
+      if (realTimes > 0 && !/var\(/.test(valuePart)) {
+        findings.push({
+          rule: "hardcoded-duration",
+          severity: "minor",
+          path: f.path,
+          line: lineOf(src, m.index),
+          message: `Literal duration in "${m[0].trim().slice(0, 60)}". Use a motion token (var(--transition-fast) etc.) so the whole app moves consistently.`,
+          recipe: "motion-tokens",
+        });
+      }
+    }
+
+    // transition-all
+    const allRe = /transition\s*:\s*all\b/g;
+    while ((m = allRe.exec(src))) {
+      findings.push({
+        rule: "transition-all",
+        severity: "warn",
+        path: f.path,
+        line: lineOf(src, m.index),
+        message: "\"transition: all\" animates every property including layout. Name the properties (opacity, transform) for smoother, cheaper motion.",
+      });
+    }
+
+    // hover-without-transition (stylesheets only, heuristic)
+    if (STYLESHEET.has(f.ext)) {
+      const hoverRe = /([^{}\n]{1,120}?):hover[^{]*\{([^}]*)\}/g;
+      while ((m = hoverRe.exec(src))) {
+        const body = m[2];
+        if (!/(transform|opacity|background|color|box-shadow|scale|translate|border)/.test(body)) continue;
+        if (/transition/.test(body)) continue;
+        const base = m[1].trim().split(/[\s>+~,]/).pop();
+        if (!base || base.length < 2) continue;
+        const esc = base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const baseHasTransition = new RegExp(esc + "[^{}]*\\{[^}]*transition", "s").test(src);
+        if (!baseHasTransition) {
+          findings.push({
+            rule: "hover-without-transition",
+            severity: "warn",
+            path: f.path,
+            line: lineOf(src, m.index),
+            message: `"${m[1].trim().slice(0, 50)}:hover" changes visual state with no transition on the base selector. The change snaps instead of easing.`,
+            recipe: "learn-more-hover",
+          });
+        }
+      }
+    }
+
+    // untransitioned-overlay (JSX-ish files, per-file heuristic)
+    if (JSXISH.has(f.ext) || f.ext === ".vue" || f.ext === ".svelte") {
+      const overlay = src.match(/<(Modal|Dialog|Drawer|Sheet|Popover|Tooltip|Toast|Snackbar|Dropdown|DropdownMenu|Menu)\b/);
+      const conditional = /\{\s*\w[\w.]*\s*&&\s*</.test(src) || /\bopen\s*[=?]/.test(src) || /\bisOpen\b/.test(src) || /\bshow\w*\s*[=?]/.test(src);
+      const animated = /(framer-motion|AnimatePresence|motion\.|react-spring|transition|animate|@keyframes|data-\[state|data-state|duration-)/i.test(src);
+      if (overlay && conditional && !animated) {
+        findings.push({
+          rule: "untransitioned-overlay",
+          severity: "major",
+          path: f.path,
+          line: lineOf(src, overlay.index),
+          message: `<${overlay[1]}> appears and disappears with no enter or exit transition. It pops instead of animating.`,
+          recipe: overlay[1].toLowerCase().includes("tooltip") ? "tooltip" : "modal-open-close",
+        });
+      }
+    }
+  }
+
+  // no-reduced-motion (project-level)
+  if (hasAnimation && !hasReducedMotion) {
+    findings.push({
+      rule: "no-reduced-motion",
+      severity: "warn",
+      path: "(project)",
+      line: 0,
+      message: "The project animates but never checks prefers-reduced-motion. Users who turn motion off in their OS still get full animation. Add one media query guard.",
+      recipe: "motion-tokens",
+    });
+  }
+
+  // inconsistent-durations (project-level)
+  const unique = [...new Set(durations.map((d) => d.ms))].sort((a, b) => a - b);
+  if (unique.length > 5) {
+    findings.push({
+      rule: "inconsistent-durations",
+      severity: "info",
+      path: "(project)",
+      line: 0,
+      message: `${unique.length} different animation durations in use (${unique.slice(0, 8).map((v) => v + "ms").join(", ")}${unique.length > 8 ? ", ..." : ""}). Consolidate to 2 or 3 motion tokens.`,
+      recipe: "motion-tokens",
+    });
+  }
+
+  return findings;
+}

package/lib/scan.mjs

@@ -0,0 +1,45 @@
+// Scan orchestration: walk files, run rules, compute motion score.
+import { collectFiles } from "./walk.mjs";
+import { runRules } from "./rules.mjs";
+
+const WEIGHTS = { major: 8, warn: 4, minor: 1, info: 2 };
+// Per-rule penalty caps so one noisy rule cannot zero the score.
+const CAPS = { "hardcoded-duration": 15, "hover-without-transition": 20, "transition-all": 12, "untransitioned-overlay": 32 };
+
+export function scan(root) {
+  const files = collectFiles(root);
+  const findings = runRules(files);
+
+  const perRule = {};
+  let penalty = 0;
+  for (const f of findings) {
+    const w = WEIGHTS[f.severity] || 1;
+    perRule[f.rule] = (perRule[f.rule] || 0) + w;
+  }
+  for (const [rule, total] of Object.entries(perRule)) {
+    penalty += Math.min(total, CAPS[rule] ?? total);
+  }
+  const score = Math.max(0, 100 - penalty);
+
+  return {
+    score,
+    grade: grade(score),
+    scannedFiles: files.length,
+    findings,
+    counts: countBy(findings, (f) => f.rule),
+    severities: countBy(findings, (f) => f.severity),
+  };
+}
+
+function grade(score) {
+  if (score >= 90) return "smooth";
+  if (score >= 75) return "decent";
+  if (score >= 50) return "janky";
+  return "static";
+}
+
+function countBy(arr, key) {
+  const out = {};
+  for (const x of arr) out[key(x)] = (out[key(x)] || 0) + 1;
+  return out;
+}

package/lib/walk.mjs

@@ -0,0 +1,45 @@
+// Recursive file walker with sensible defaults. Zero dependencies.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, extname, relative } from "node:path";
+
+const SCAN_EXTS = new Set([".css", ".scss", ".less", ".html", ".jsx", ".tsx", ".js", ".mjs", ".ts", ".vue", ".svelte"]);
+const IGNORE_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", "out", ".next", ".nuxt", ".output",
+  "coverage", "vendor", ".cache", ".turbo", ".vercel", "storybook-static", ".claude",
+]);
+const MAX_FILE_BYTES = 400_000;
+
+export function collectFiles(root) {
+  const files = [];
+  walk(root, root, files, 0);
+  return files;
+}
+
+function walk(root, dir, files, depth) {
+  if (depth > 12) return;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (e.name.startsWith(".") && e.name !== ".") continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!IGNORE_DIRS.has(e.name)) walk(root, full, files, depth + 1);
+      continue;
+    }
+    const ext = extname(e.name);
+    if (!SCAN_EXTS.has(ext)) continue;
+    if (/\.min\.(js|css)$/.test(e.name) || /\.d\.ts$/.test(e.name)) continue;
+    let size;
+    try { size = statSync(full).size; } catch { continue; }
+    if (size > MAX_FILE_BYTES) continue;
+    let content;
+    try { content = readFileSync(full, "utf8"); } catch { continue; }
+    files.push({ path: relative(root, full), ext, content });
+  }
+}
+
+export function lineOf(content, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < content.length; i++) if (content[i] === "\n") line++;
+  return line;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "transitions-agent",
+  "version": "0.1.0",
+  "description": "Scan your codebase for missing, janky, or inconsistent UI transitions. Get a motion score, ready-to-apply fixes from transitions.dev recipes, and an optional pull request with the fixes.",
+  "type": "module",
+  "bin": {
+    "transitions-agent": "bin/transitions-agent.mjs"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "css",
+    "transitions",
+    "animations",
+    "motion",
+    "lint",
+    "scanner",
+    "ui",
+    "accessibility"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jakubantalik/transitions.dev.git",
+    "directory": "agent"
+  },
+  "homepage": "https://transitions.dev"
+}