@mehshekari/gsap-motion 3.5.0 → 3.6.0

package/README.md

@@ -23,6 +23,7 @@ No dependencies, no install scripts, Node.js 18 or later.
 | `inspect <url>` | Watches a page animate over the DevTools Protocol and reports what it saw: a filmstrip, the timeline GSAP is running, and the layouts, style recalculations and frames the browser did. `--scroll`, `--hover` and `--click` reach the state first; `--reduced`, `--dark`, `--mobile` and `--cpu` change the conditions. Needs a Chrome on the machine; installs nothing. |
 | `explain <file...|url>` | Maps an animation and changes nothing: where it lives, its preference branches, its beats in order with the reasons their comments give, its scroll configuration, and what the audit says. Given a URL it reads the running page instead, where the timeline is the one GSAP actually built. |
 | `review <url>` | Measures what the motion actually did, by sampling the DOM every frame rather than by reading GSAP's timeline — which a bundled app never exposes, and which would make it work on demo pages and fail on real ones. Reports time to first motion, the share of the screen moving at its busiest, loop seams, and motion over text being read. Sampling forces layout, so it does not report layout counts; `inspect` measures those. Takes the same `--scroll`, `--reduced`, `--dark`, `--mobile` and `--cpu`. |
+| `patterns check [file]` | Validates the Patterns section of your `ANIMATION.md`: the fields each status needs, the recorded uses behind `validated`, the named reviewer behind `canonical`, and entries verified against an older GSAP than the one installed. Exits 1 on a claim the evidence does not support, so it belongs in `lint` beside `audit`. A project with no Patterns section passes. |
 | `doctor` | Checks Node.js, the installed skill's version for this project and your user, your project's `gsap` and `@gsap/react`, and whether an `ANIMATION.md` exists. |
 
 ## In CI
@@ -31,7 +32,7 @@ The audit needs no install. Pin the version, so a new rule cannot fail your
 build without warning:
 
 ```json
-"lint": "eslint && npx @mehshekari/gsap-motion@3.5.0 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@3.6.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/bin/gsap-motion.mjs

@@ -10,6 +10,7 @@
  *   npx @mehshekari/gsap-motion inspect <url> [--at ...] [--hover ...] [--reduced]
  *   npx @mehshekari/gsap-motion explain <file...|url>
  *   npx @mehshekari/gsap-motion review <url> [--scroll ...] [--mobile]
+ *   npx @mehshekari/gsap-motion patterns check [ANIMATION.md]
  *   npx @mehshekari/gsap-motion doctor
  *
  * Installed as a dependency, the same commands run as `gsap-motion <command>`.
@@ -94,6 +95,10 @@ Commands
     --cpu 4             Throttle the CPU by this factor
     --out <dir>         Save a frame alongside the measurements
     --json              Machine-readable output
+  patterns check [file] Check the Patterns section of your ANIMATION.md:
+                        the fields each status needs, the uses behind
+                        validated, the reviewer behind canonical
+    --json              Machine-readable output
   doctor                Check Node, the installed skill and your project's GSAP
   --version             Print the version
 
@@ -335,6 +340,9 @@ switch (command) {
   case "review":
     runScript("review-motion.mjs", args);
     break;
+  case "patterns":
+    runScript("patterns.mjs", args);
+    break;
   case "doctor":
     doctor();
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Install the gsap-creative-animation Agent Skill, and audit GSAP animation for leaks, jank and accessibility failures — with npx.",
   "keywords": [
     "gsap",

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Senior motion engineer for GSAP. Turns a visual or interaction idea
 license: MIT. See LICENSE; GSAP itself is licensed separately, see NOTICE.md
 compatibility: Any Agent Skills client; written for Claude Code. GSAP 3.13+, where every plugin is free. React guidance targets @gsap/react 2.x, React 18/19 and the Next.js App Router. The audit scripts need Node.js 18+ and nothing else.
 metadata:
-  version: "3.5.0"
+  version: "3.6.0"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---
@@ -101,8 +101,8 @@ intent → precedent → targets → trigger → motion language → technique
 2. **Precedent** — grep for the animation this codebase already has. Its
    trigger point, easing, durations, stagger shape and attribute naming are the
    house language: match them, and differ only for a reason you can state.
-   Nothing downstream catches a skipped precedent — the code compiles, the
-   audit passes, and the page reads as two different sites.
+   Nothing downstream catches a skipped precedent: the code compiles, the audit
+   passes, and the page reads as two different sites.
 3. **Targets** — which elements move, and can they be reached without a
    positional selector that breaks when the markup moves?
 4. **Trigger** — mount, in-view, scroll position, pointer, click, route, loop.
@@ -112,8 +112,8 @@ intent → precedent → targets → trigger → motion language → technique
 8. **Implementation** — typed, cleaned up, responsive.
 9. **Performance** — transform and opacity; measure before defending anything else.
 10. **Accessibility** — the reduced-motion design, focus, keyboard.
-11. **Validate** — [refine.md](reference/refine.md): audit, fix in order,
-    re-run, then the checklist in [motion-design.md](reference/motion-design.md).
+11. **Validate** — [refine.md](reference/refine.md): audit, fix in order, re-run,
+    then the checklist in [motion-design.md](reference/motion-design.md).
 
 ## Output format
 

package/skill/reference/project-rules.md

@@ -83,10 +83,76 @@ one is short, and each section is an instruction rather than an essay:
 
 ## Precedents
 <!-- Files that already do this well, by path, and what each one taught. -->
+
+## Patterns
+<!-- Shapes this project has proven. Format and statuses below; `patterns
+     check` validates this section. Omit the section until there is one. -->
 ````
 
 ---
 
+## Patterns: what the project has proven
+
+A pattern is a shape of animation this project has used and can use again. The
+section is optional, and empty is the honest state for a new project.
+
+**Nothing becomes guidance by having been written.** A pattern loaded as
+guidance repeats in every session after it, so a wrong one is not one mistake,
+it is every future mistake. That is why a status is evidence, not a claim.
+
+| Status | Reached when | Loaded as |
+|---|---|---|
+| `experimental` | Built for one request, its claims verified, the audit clean. **Offered in the answer, never written to the file.** | Nothing |
+| `candidate` | The user accepts it into ANIMATION.md. That acceptance is its first use. | An option to mention, never a default |
+| `validated` | Used again in a **different component** — two uses by default — each recorded with its file and commit, and each audit clean | The house way, unless the request gives a reason not to |
+| `canonical` | A **named person** has reviewed it | A precedent, followed like the house motion language |
+| `retired` | Disproved. Kept, with the reason, so it is not reinvented | A warning only |
+
+**Who moves an entry.** The skill offers entries and proposes promotions with
+their evidence; it never changes a status on its own. `candidate` needs your
+yes. `validated` is counted by `patterns check` from the recorded uses, never
+asserted by the entry. `canonical` needs a reviewer's name.
+
+**Moving down is evidence too.** A bug traced to a pattern returns it to
+`candidate` with the failure recorded. A GSAP release past its verified version
+marks it for re-verification — it stays loaded, marked. A use later reverted
+does not count.
+
+### The format
+
+```markdown
+### Ink behind a moving pen
+
+- **Status:** candidate
+- **Concept:** a mask shares the pen's duration and ease, so ink appears only
+  where the nib has already been.
+- **Fixed:** the mask and the path share one duration and one ease.
+- **Parameters:** duration, ease, nib radius.
+- **Not when:** the stroke crosses itself — the mask reveals the crossing early.
+- **Reduced motion:** the finished stroke is set, and no tween runs.
+- **Verified against:** gsap 3.15, DrawSVGPlugin
+- **Uses:**
+  - `src/components/Signature.tsx` — `a1b2c3d` — audit clean
+  - `src/components/Hero.tsx` — `e4f5a6b` — audit clean, review: no seams
+- **Reviewed by:** <!-- a name, for canonical only -->
+```
+
+`Concept`, `Not when`, `Reduced motion` and `Verified against` are required of
+every entry that is in the file. A `retired` entry needs only **Why**. Two uses
+in the same file count once: one component is one use.
+
+Run it with the rest of the checks:
+
+```bash
+gsap-motion patterns check          # or: patterns check path/to/ANIMATION.md
+```
+
+It exits 1 on a claim the evidence does not support, so it belongs in `lint`
+beside `audit`. Where a candidate has earned `validated`, it says so and leaves
+the promotion to you.
+
+---
+
 ## Rules worth knowing without a file
 
 Each of these fails silently in any project that has the condition.

package/skill/scripts/patterns.mjs

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+/**
+ * patterns — what a project has proven, and what it has only tried.
+ *
+ * A skill that writes down whatever it just invented teaches itself its own
+ * mistakes: a bad pattern, once loaded as guidance, repeats in every session
+ * after it. So a pattern's standing is not something it can claim. It is
+ * counted from evidence recorded in the project's own ANIMATION.md:
+ *
+ *   experimental  built once, verified, offered in an answer. Never written.
+ *   candidate     the user put it in the file. Mentionable, never a default.
+ *   validated     used again, in another component, each use with its commit.
+ *   canonical     a named person reviewed it.
+ *   retired       disproved, kept with the reason so it is not reinvented.
+ *
+ * `validated` is computed here rather than asserted there, and `canonical`
+ * needs a name, because those are the two a keen assistant would otherwise
+ * grant itself. This command only reads and reports; it never edits the file.
+ *
+ * Node.js 18+, no dependencies.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const STATUSES = ["experimental", "candidate", "validated", "canonical", "retired"];
+
+/** How many separate components a pattern must appear in to be validated. */
+export const USES_FOR_VALIDATED = 2;
+
+const FIELDS = {
+  concept: "concept",
+  fixed: "fixed",
+  parameters: "parameters",
+  "not when": "notWhen",
+  "reduced motion": "reducedMotion",
+  "verified against": "verifiedAgainst",
+  "reviewed by": "reviewedBy",
+  why: "why",
+  status: "status",
+  uses: "uses",
+};
+
+/**
+ * Read the Patterns section of an ANIMATION.md.
+ *
+ * The format is what a person would write by hand — a heading per pattern and a
+ * bold-labelled list under it — because a format nobody will write is a format
+ * nothing will be recorded in. A field may wrap over several lines.
+ */
+export function parse(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const entries = [];
+
+  let inSection = false;
+  let entry = null;
+  let field = null;
+
+  const closeField = () => {
+    if (entry && field && entry.fields[field] !== undefined) {
+      entry.fields[field] = entry.fields[field].trim();
+    }
+    field = null;
+  };
+
+  for (const line of lines) {
+    const heading = /^(#{2,3})\s+(.*)$/.exec(line);
+    if (heading) {
+      const [, hashes, title] = heading;
+      if (hashes === "##") {
+        closeField();
+        entry = null;
+        inSection = /^patterns\b/i.test(title.trim());
+        continue;
+      }
+      if (inSection) {
+        closeField();
+        entry = { name: title.trim(), status: null, fields: {}, uses: [] };
+        entries.push(entry);
+      }
+      continue;
+    }
+    if (!inSection || !entry) continue;
+
+    const labelled = /^\s*-\s+\*\*(.+?):\*\*\s*(.*)$/.exec(line);
+    if (labelled) {
+      closeField();
+      const key = FIELDS[labelled[1].trim().toLowerCase()];
+      if (!key) continue;
+      if (key === "status") {
+        entry.status = labelled[2].trim().toLowerCase() || null;
+        continue;
+      }
+      if (key === "uses") {
+        field = "uses";
+        continue;
+      }
+      field = key;
+      entry.fields[key] = labelled[2];
+      continue;
+    }
+
+    /** A use: a file, the commit it landed in, and what was checked. */
+    const use = /^\s+-\s+`([^`]+)`\s*[—-]\s*`([^`]+)`\s*(?:[—-]\s*(.*))?$/.exec(line);
+    if (use && field === "uses") {
+      entry.uses.push({ file: use[1].trim(), commit: use[2].trim(), note: (use[3] ?? "").trim() });
+      continue;
+    }
+
+    /** A continuation of the field above, wrapped by a person or a formatter. */
+    if (field && field !== "uses" && /^\s+\S/.test(line)) {
+      entry.fields[field] = `${entry.fields[field] ?? ""} ${line.trim()}`;
+    }
+  }
+  closeField();
+
+  return entries;
+}
+
+/** Components, not lines: two commits to one file is one pattern used once. */
+const distinctUses = (entry) => new Set(entry.uses.map((use) => use.file)).size;
+
+const REQUIRED = ["concept", "notWhen", "reducedMotion", "verifiedAgainst"];
+const LABEL = {
+  concept: "concept",
+  notWhen: "not when",
+  reducedMotion: "reduced motion",
+  verifiedAgainst: "verified against",
+};
+
+/**
+ * What the section gets wrong.
+ *
+ * Errors are claims the evidence does not support; warnings are entries that
+ * are fine but should not be in the file yet. Nothing here is a judgement about
+ * whether the pattern is any good.
+ */
+export function check(entries, { uses = USES_FOR_VALIDATED } = {}) {
+  const found = [];
+  const at = (entry, level, message) => found.push({ name: entry.name, level, message });
+
+  for (const entry of entries) {
+    if (!entry.status) {
+      at(entry, "error", `"${entry.name}" has no status. One of: ${STATUSES.join(", ")}.`);
+      continue;
+    }
+    if (!STATUSES.includes(entry.status)) {
+      at(
+        entry,
+        "error",
+        `"${entry.name}": ${entry.status} is not a status. One of: ${STATUSES.join(", ")}.`,
+      );
+      continue;
+    }
+
+    if (entry.status === "retired") {
+      /** A retired pattern is kept only so it is not reinvented, so it owes one thing. */
+      if (!entry.fields.why) {
+        at(entry, "error", `"${entry.name}" is retired but does not say why it was retired.`);
+      }
+      continue;
+    }
+
+    if (entry.status === "experimental") {
+      at(
+        entry,
+        "warn",
+        `"${entry.name}" is experimental, which is offered, not written. ` +
+          "Make it a candidate when it is accepted, or take it out.",
+      );
+      continue;
+    }
+
+    const missing = REQUIRED.filter((key) => !entry.fields[key]);
+    if (missing.length) {
+      at(
+        entry,
+        "error",
+        `"${entry.name}" is missing: ${missing.map((key) => LABEL[key]).join(", ")}.`,
+      );
+    }
+
+    if (entry.status === "validated" || entry.status === "canonical") {
+      const count = distinctUses(entry);
+      if (count < uses) {
+        at(
+          entry,
+          "error",
+          `"${entry.name}" claims ${entry.status} with ${count} recorded use${count === 1 ? "" : "s"}. ` +
+            `${uses} in separate components are needed, each with its file and commit.`,
+        );
+      }
+    }
+
+    if (entry.status === "canonical" && !entry.fields.reviewedBy) {
+      at(
+        entry,
+        "error",
+        `"${entry.name}" claims canonical with nobody named. Add "Reviewed by".`,
+      );
+    }
+  }
+
+  return found;
+}
+
+const asVersion = (text) => {
+  const found = /(\d+)\.(\d+)(?:\.(\d+))?/.exec(text ?? "");
+  return found ? [Number(found[1]), Number(found[2]), Number(found[3] ?? 0)] : null;
+};
+
+/**
+ * Patterns verified against a GSAP older than the installed one.
+ *
+ * They stay loaded — a pattern does not stop working because a minor version
+ * shipped — but they are marked, because the claim behind them was checked
+ * against something else. A patch difference is not worth a word.
+ */
+export function stale(entries, { gsap } = {}) {
+  const installed = asVersion(gsap);
+  if (!installed) return [];
+
+  const found = [];
+  for (const entry of entries) {
+    if (entry.status === "retired") continue;
+    const verified = asVersion(entry.fields.verifiedAgainst);
+    if (!verified) continue;
+    const older = verified[0] < installed[0] || (verified[0] === installed[0] && verified[1] < installed[1]);
+    if (older) {
+      found.push({
+        name: entry.name,
+        level: "warn",
+        message:
+          `"${entry.name}" was verified against gsap ${verified[0]}.${verified[1]}, ` +
+          `and ${gsap} is installed. Re-verify it, or record the version you checked.`,
+      });
+    }
+  }
+  return found;
+}
+
+/**
+ * Candidates that have earned validated.
+ *
+ * Proposed, never applied: the skill offers a promotion with its evidence and a
+ * person accepts it. Canonical is absent on purpose — no amount of use earns a
+ * review.
+ */
+export function promotable(entries, { uses = USES_FOR_VALIDATED } = {}) {
+  return entries
+    .filter((entry) => entry.status === "candidate" && distinctUses(entry) >= uses)
+    .filter((entry) => REQUIRED.every((key) => entry.fields[key]))
+    .map((entry) => ({
+      name: entry.name,
+      to: "validated",
+      uses: distinctUses(entry),
+      files: [...new Set(entry.uses.map((use) => use.file))],
+    }));
+}
+
+// --- The command ---------------------------------------------------------------
+
+const installedGsap = (root) => {
+  for (const path of ["node_modules/gsap/package.json", "package.json"]) {
+    try {
+      const json = JSON.parse(readFileSync(resolve(root, path), "utf8"));
+      const version = path.endsWith("gsap/package.json")
+        ? json.version
+        : json.dependencies?.gsap ?? json.devDependencies?.gsap;
+      if (version) return String(version).replace(/^[\^~]/, "");
+    } catch {
+      /** No package.json, or no gsap in it: there is simply nothing to compare. */
+    }
+  }
+  return null;
+};
+
+export function report(entries, findings, { file, json, quiet }) {
+  if (json) {
+    return JSON.stringify({ file, patterns: entries.length, findings }, null, 2);
+  }
+
+  /**
+   * In a lint script, a check with nothing to say should say nothing. Errors
+   * still print, because they are why the run fails.
+   */
+  if (quiet) {
+    const errors = findings.filter((finding) => finding.level === "error");
+    return errors.map((finding) => `  error  ${finding.message}`).join("\n");
+  }
+
+  const lines = [];
+  if (!entries.length) {
+    lines.push(`No Patterns section in ${file}.`);
+    lines.push("Nothing to check. A pattern is written there once it has been accepted.");
+    return lines.join("\n");
+  }
+
+  const by = (status) => entries.filter((entry) => entry.status === status).length;
+  lines.push(`${entries.length} pattern${entries.length === 1 ? "" : "s"} in ${file}`);
+  lines.push(
+    "  " +
+      STATUSES.map((status) => `${by(status)} ${status}`)
+        .filter((part) => !part.startsWith("0 "))
+        .join(" · "),
+  );
+
+  if (findings.length) {
+    lines.push("");
+    for (const finding of findings) {
+      lines.push(`  ${finding.level === "error" ? "error" : " warn"}  ${finding.message}`);
+    }
+  }
+
+  const ready = promotable(entries);
+  if (ready.length) {
+    lines.push("", "Earned a promotion — yours to grant, with the evidence:");
+    for (const entry of ready) {
+      lines.push(`  ${entry.name} → validated (${entry.uses} uses: ${entry.files.join(", ")})`);
+    }
+  }
+
+  if (!findings.length) lines.push("", "patterns: clean");
+  return lines.join("\n");
+}
+
+async function main(argv) {
+  const json = argv.includes("--json");
+  const quiet = argv.includes("--quiet");
+  const rest = argv.filter(
+    (argument) => !["--json", "--quiet", "check"].includes(argument),
+  );
+  const file = rest[0] ?? "ANIMATION.md";
+  const root = process.cwd();
+
+  let markdown;
+  try {
+    markdown = readFileSync(resolve(root, file), "utf8");
+  } catch {
+    console.error(`Cannot read ${file}. Pass the path to your ANIMATION.md.`);
+    process.exit(2);
+  }
+
+  const entries = parse(markdown);
+  const findings = [...check(entries), ...stale(entries, { gsap: installedGsap(root) })];
+  const text = report(entries, findings, { file, json, quiet });
+  if (text) console.log(text);
+  process.exit(findings.some((finding) => finding.level === "error") ? 1 : 0);
+}
+
+const invoked = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invoked) await main(process.argv.slice(2));