@monoes/monomindcli 1.7.0 → 1.9.0

package/.claude/skills/monomotion/rules/api-control.md

@@ -0,0 +1,139 @@
+# API-Driven Animation Control
+
+## Pattern: Central Animation Registry
+
+Expose timelines through a registry so any control surface can drive them.
+
+```js
+// animation-registry.js
+const registry = new Map();
+
+export function register(name, timeline) {
+  registry.set(name, timeline);
+}
+
+export function control(name, action, value) {
+  const tl = registry.get(name);
+  if (!tl) return { error: `unknown timeline: ${name}` };
+
+  switch (action) {
+    case "play":     tl.play(); break;
+    case "pause":    tl.pause(); break;
+    case "reverse":  tl.reverse(); break;
+    case "restart":  tl.restart(); break;
+    case "seek":     tl.seek(Number(value)); break;
+    case "progress": tl.progress(Number(value)); break;
+    case "speed":    tl.timeScale(Number(value)); break;
+    case "label":    tl.seek(value); break;
+  }
+
+  return { time: tl.time(), progress: tl.progress(), paused: tl.paused() };
+}
+
+export function state(name) {
+  const tl = registry.get(name);
+  if (!tl) return null;
+  return { time: tl.time(), progress: tl.progress(), duration: tl.duration(), paused: tl.paused() };
+}
+```
+
+## WebSocket Control Server (Node.js)
+
+```js
+// server.js
+import { WebSocketServer } from "ws";
+import { control, state } from "./animation-registry.js";
+
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on("connection", (ws) => {
+  ws.on("message", (raw) => {
+    const { timeline, action, value } = JSON.parse(raw);
+    const result = control(timeline, action, value);
+    ws.send(JSON.stringify(result));
+  });
+});
+```
+
+```js
+// browser — connect and drive animations
+const ws = new WebSocket("ws://localhost:8080");
+
+function send(timeline, action, value) {
+  ws.send(JSON.stringify({ timeline, action, value }));
+}
+
+send("intro", "play");
+send("intro", "seek", 1.5);
+send("outro", "reverse");
+```
+
+## REST Control Endpoint (Express)
+
+```js
+import express from "express";
+import { control, state } from "./animation-registry.js";
+
+const app = express();
+app.use(express.json());
+
+// POST /animation/:name/:action
+app.post("/animation/:name/:action", (req, res) => {
+  const result = control(req.params.name, req.params.action, req.body.value);
+  res.json(result);
+});
+
+// GET /animation/:name
+app.get("/animation/:name", (req, res) => {
+  res.json(state(req.params.name));
+});
+
+app.listen(3000);
+```
+
+```bash
+# Drive from CLI
+curl -X POST http://localhost:3000/animation/intro/play
+curl -X POST http://localhost:3000/animation/intro/seek -d '{"value":1.5}' -H 'Content-Type: application/json'
+curl http://localhost:3000/animation/intro
+```
+
+## SSE — Push State to Browser
+
+```js
+// server: broadcast state on every animation tick
+app.get("/animation/stream", (req, res) => {
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+
+  const interval = setInterval(() => {
+    const s = state("intro");
+    res.write(`data: ${JSON.stringify(s)}\n\n`);
+  }, 50); // 20fps state stream
+
+  req.on("close", () => clearInterval(interval));
+});
+```
+
+```js
+// browser: receive state stream
+const es = new EventSource("/animation/stream");
+es.onmessage = ({ data }) => {
+  const { progress } = JSON.parse(data);
+  document.querySelector(".progress-bar").style.width = `${progress * 100}%`;
+};
+```
+
+## Keyboard Control
+
+```js
+document.addEventListener("keydown", (e) => {
+  switch (e.key) {
+    case " ":  tl.paused() ? tl.resume() : tl.pause(); break;
+    case "ArrowRight": tl.seek(tl.time() + 0.5); break;
+    case "ArrowLeft":  tl.seek(Math.max(0, tl.time() - 0.5)); break;
+    case "r":  tl.restart(); break;
+    case "0":  tl.seek(0); break;
+  }
+});
+```

package/.claude/skills/monomotion/rules/effects.md

@@ -0,0 +1,109 @@
+# Effects & Presets
+
+## Fade
+
+```js
+// Fade in
+gsap.from(el, { autoAlpha: 0, duration: 0.5 });
+
+// Fade out
+gsap.to(el, { autoAlpha: 0, duration: 0.5 });
+
+// Cross-fade two elements
+const tl = gsap.timeline();
+tl.to(elA, { autoAlpha: 0, duration: 0.4 })
+  .from(elB, { autoAlpha: 0, duration: 0.4 }, "<");
+```
+
+> Always use `autoAlpha` instead of `opacity` — it also handles `visibility: hidden` so elements don't intercept pointer events when invisible.
+
+## Slide
+
+```js
+// Slide in from left
+gsap.from(el, { x: -100, autoAlpha: 0, duration: 0.6, ease: "power2.out" });
+
+// Slide up
+gsap.from(el, { y: 40, autoAlpha: 0, duration: 0.5, ease: "power3.out" });
+
+// Slide out to right
+gsap.to(el, { x: 100, autoAlpha: 0, duration: 0.4, ease: "power2.in" });
+```
+
+## Scale
+
+```js
+// Pop in
+gsap.from(el, { scale: 0.8, autoAlpha: 0, duration: 0.4, ease: "back.out(1.7)" });
+
+// Expand from center
+gsap.from(el, { scale: 0, transformOrigin: "center center", duration: 0.5, ease: "elastic.out(1, 0.5)" });
+```
+
+## Clip Reveal (wipe)
+
+```js
+// Wipe left to right
+gsap.from(el, { clipPath: "inset(0 100% 0 0)", duration: 0.8, ease: "power2.inOut" });
+
+// Wipe top to bottom
+gsap.from(el, { clipPath: "inset(0 0 100% 0)", duration: 0.6, ease: "power2.out" });
+```
+
+## Highlight / Underline Draw
+
+```js
+// Draw an SVG underline
+gsap.from("line.underline", { drawSVG: "0%", duration: 0.6, ease: "power2.out" });
+// Requires DrawSVGPlugin (GSAP Club)
+```
+
+## Blur In
+
+```js
+gsap.from(el, {
+  filter: "blur(12px)",
+  autoAlpha: 0,
+  duration: 0.7,
+  ease: "power2.out",
+  clearProps: "filter", // remove inline style after animation
+});
+```
+
+## Shake
+
+```js
+gsap.to(el, {
+  keyframes: [
+    { x: -8 }, { x: 8 }, { x: -6 }, { x: 6 },
+    { x: -3 }, { x: 3 }, { x: 0 },
+  ],
+  duration: 0.5,
+  ease: "none",
+});
+```
+
+## Pulse
+
+```js
+gsap.to(el, {
+  scale: 1.05,
+  duration: 0.3,
+  yoyo: true,
+  repeat: 1,
+  ease: "power1.inOut",
+});
+```
+
+## Ease Reference
+
+| Ease | Character |
+|------|-----------|
+| `power1–4.out` | Smooth deceleration (UI standard) |
+| `power1–4.in` | Accelerates out (exits) |
+| `power2.inOut` | Smooth both ends |
+| `back.out(1.7)` | Slight overshoot on arrival |
+| `elastic.out(1, 0.3)` | Springy bounce |
+| `bounce.out` | Ball bounce |
+| `expo.out` | Fast start, long tail |
+| `none` | Linear |

package/.claude/skills/monomotion/rules/integration.md

@@ -0,0 +1,140 @@
+# Integration Patterns
+
+## Vanilla HTML Drop-In
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <style>
+    .box { width: 80px; height: 80px; background: #6366f1; border-radius: 8px; }
+  </style>
+</head>
+<body>
+  <div class="box"></div>
+  <button id="play">Play</button>
+  <button id="pause">Pause</button>
+
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+  <script>
+    const tl = gsap.timeline({ paused: true });
+    tl.to(".box", { x: 300, rotation: 360, duration: 1, ease: "power2.inOut" })
+      .to(".box", { x: 0, rotation: 0, duration: 1, ease: "power2.inOut" });
+
+    document.getElementById("play").onclick  = () => tl.play();
+    document.getElementById("pause").onclick = () => tl.pause();
+  </script>
+</body>
+</html>
+```
+
+## Embedding in an iframe
+
+The parent page controls the animation inside the iframe:
+
+```js
+// In the iframe page — expose controls on window
+window.monomotion = {
+  play:     (name) => registry.control(name, "play"),
+  pause:    (name) => registry.control(name, "pause"),
+  seek:     (name, t) => registry.control(name, "seek", t),
+  progress: (name, p) => registry.control(name, "progress", p),
+};
+```
+
+```js
+// In the parent page
+const iframe = document.querySelector("iframe");
+iframe.contentWindow.monomotion.play("intro");
+iframe.contentWindow.monomotion.seek("intro", 1.5);
+```
+
+## Web Component
+
+```js
+class MonoAnimation extends HTMLElement {
+  connectedCallback() {
+    const name = this.getAttribute("name");
+    const src = this.getAttribute("src");
+
+    this.innerHTML = `<div class="animation-host"></div>`;
+
+    // Load animation definition dynamically
+    import(src).then(({ build }) => {
+      this._tl = build(this.querySelector(".animation-host"));
+    });
+  }
+
+  play()    { this._tl?.play(); }
+  pause()   { this._tl?.pause(); }
+  seek(t)   { this._tl?.seek(t); }
+}
+
+customElements.define("mono-animation", MonoAnimation);
+```
+
+```html
+<mono-animation name="hero" src="./animations/hero.js"></mono-animation>
+<button onclick="document.querySelector('mono-animation').play()">Play</button>
+```
+
+## React Integration (if needed)
+
+```jsx
+import { useEffect, useRef } from "react";
+import { gsap } from "gsap";
+
+function AnimatedBox() {
+  const boxRef = useRef(null);
+  const tlRef  = useRef(null);
+
+  useEffect(() => {
+    tlRef.current = gsap.timeline({ paused: true });
+    tlRef.current.to(boxRef.current, { x: 200, duration: 0.8, ease: "power2.out" });
+
+    return () => tlRef.current.kill();
+  }, []);
+
+  return (
+    <div>
+      <div ref={boxRef} style={{ width: 80, height: 80, background: "#6366f1" }} />
+      <button onClick={() => tlRef.current.play()}>Play</button>
+    </div>
+  );
+}
+```
+
+## Dashboard Control Panel
+
+```html
+<div class="control-panel">
+  <input type="range" id="scrubber" min="0" max="100" value="0" />
+  <button id="btn-play">▶</button>
+  <button id="btn-pause">⏸</button>
+  <button id="btn-reverse">◀◀</button>
+  <span id="time-display">0.00s</span>
+</div>
+
+<script>
+  const scrubber = document.getElementById("scrubber");
+  let isScrubbing = false;
+
+  scrubber.addEventListener("input", () => {
+    isScrubbing = true;
+    tl.progress(scrubber.value / 100).pause();
+  });
+  scrubber.addEventListener("change", () => { isScrubbing = false; });
+
+  // Sync scrubber with playback
+  gsap.ticker.add(() => {
+    if (!isScrubbing) {
+      scrubber.value = tl.progress() * 100;
+      document.getElementById("time-display").textContent = tl.time().toFixed(2) + "s";
+    }
+  });
+
+  document.getElementById("btn-play").onclick    = () => tl.play();
+  document.getElementById("btn-pause").onclick   = () => tl.pause();
+  document.getElementById("btn-reverse").onclick = () => tl.reverse();
+</script>
+```

package/.claude/skills/monomotion/rules/scroll.md

@@ -0,0 +1,131 @@
+# Scroll-Driven Animations
+
+## Setup
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
+```
+
+```js
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+gsap.registerPlugin(ScrollTrigger);
+```
+
+## Reveal on Enter
+
+```js
+gsap.from(".card", {
+  y: 50,
+  autoAlpha: 0,
+  duration: 0.6,
+  ease: "power2.out",
+  scrollTrigger: {
+    trigger: ".card",
+    start: "top 85%",    // when top of element hits 85% of viewport
+    toggleActions: "play none none reverse",
+  },
+});
+```
+
+**toggleActions:** `onEnter onLeave onEnterBack onLeaveBack`  
+Options: `play pause resume reverse restart reset none`
+
+## Scrub — Timeline Tied to Scroll
+
+```js
+const tl = gsap.timeline({
+  scrollTrigger: {
+    trigger: ".section",
+    start: "top top",
+    end: "bottom top",
+    scrub: 1,          // 1 = 1s lag behind scroll (0 = instant)
+    pin: true,         // pin the section while scrolling through it
+  },
+});
+
+tl.from(".title", { x: -200, autoAlpha: 0 })
+  .from(".image", { scale: 0.8, autoAlpha: 0 }, "<");
+```
+
+## Pin a Section
+
+```js
+ScrollTrigger.create({
+  trigger: ".sticky-section",
+  start: "top top",
+  end: "+=600",        // pin for 600px of scroll distance
+  pin: true,
+  pinSpacing: true,
+});
+```
+
+## Horizontal Scroll
+
+```js
+const sections = gsap.utils.toArray(".panel");
+
+gsap.to(sections, {
+  xPercent: -100 * (sections.length - 1),
+  ease: "none",
+  scrollTrigger: {
+    trigger: ".horizontal-wrapper",
+    pin: true,
+    scrub: 1,
+    end: () => `+=${document.querySelector(".horizontal-wrapper").offsetWidth}`,
+  },
+});
+```
+
+## Animate Each Element as it Enters
+
+```js
+gsap.utils.toArray(".reveal").forEach((el) => {
+  gsap.from(el, {
+    y: 40,
+    autoAlpha: 0,
+    duration: 0.7,
+    ease: "power2.out",
+    scrollTrigger: {
+      trigger: el,
+      start: "top 88%",
+      toggleActions: "play none none none",  // play once, don't reverse
+    },
+  });
+});
+```
+
+## Progress Bar
+
+```js
+gsap.to(".scroll-progress", {
+  scaleX: 1,
+  transformOrigin: "left center",
+  ease: "none",
+  scrollTrigger: {
+    trigger: "body",
+    start: "top top",
+    end: "bottom bottom",
+    scrub: 0,
+  },
+});
+```
+
+```css
+.scroll-progress {
+  position: fixed;
+  top: 0; left: 0;
+  width: 100%; height: 3px;
+  background: #6366f1;
+  transform: scaleX(0);
+  z-index: 9999;
+}
+```
+
+## Refresh After Dynamic Content
+
+```js
+// Call after DOM changes that affect scroll heights
+ScrollTrigger.refresh();
+```

package/.claude/skills/monomotion/rules/sequencing.md

@@ -0,0 +1,105 @@
+# Sequencing & Staggering
+
+## Stagger — Animate a List
+
+```js
+// Stagger children in sequence
+gsap.from(".card", {
+  y: 30,
+  autoAlpha: 0,
+  duration: 0.5,
+  stagger: 0.1,        // 100ms between each element
+  ease: "power2.out",
+});
+
+// Stagger from center outward
+gsap.from(".dot", {
+  scale: 0,
+  stagger: { each: 0.05, from: "center" },
+  ease: "back.out(2)",
+});
+
+// Stagger in a grid
+gsap.from(".cell", {
+  autoAlpha: 0,
+  stagger: { amount: 1, grid: [4, 5], from: "start" },
+});
+```
+
+## Timeline Sequences
+
+```js
+const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
+
+// Sequential — each starts after previous ends
+tl.from(".header", { y: -40, autoAlpha: 0 })
+  .from(".body",   { y: 20, autoAlpha: 0 })
+  .from(".footer", { y: 20, autoAlpha: 0 });
+
+// Overlap — start 0.2s before previous ends
+tl.from(".a", { x: -100 })
+  .from(".b", { x: -100 }, "-=0.2")
+  .from(".c", { x: -100 }, "-=0.2");
+
+// Parallel — all start at same time
+tl.from(".icon",  { scale: 0 })
+  .from(".label", { x: -20, autoAlpha: 0 }, "<");
+```
+
+## Nested Timelines
+
+```js
+function introScene() {
+  const tl = gsap.timeline();
+  tl.from(".logo", { scale: 0, duration: 0.6, ease: "back.out(2)" })
+    .from(".tagline", { y: 20, autoAlpha: 0, duration: 0.4 });
+  return tl;
+}
+
+function contentScene() {
+  const tl = gsap.timeline();
+  tl.from(".cards", { y: 40, autoAlpha: 0, stagger: 0.1 });
+  return tl;
+}
+
+// Master timeline — compose scenes
+const master = gsap.timeline();
+master.add(introScene())
+      .add(contentScene(), "+=0.3");  // 0.3s gap between scenes
+```
+
+## Callbacks
+
+```js
+const tl = gsap.timeline({
+  onStart:    () => console.log("started"),
+  onComplete: () => console.log("done"),
+  onUpdate:   () => progressBar.style.width = `${tl.progress() * 100}%`,
+});
+
+// Per-tween callbacks
+tl.to(".el", { x: 100, onComplete: () => el.classList.add("done") });
+```
+
+## Repeat & Yoyo
+
+```js
+// Loop forever
+gsap.to(".spinner", { rotation: 360, duration: 1, repeat: -1, ease: "none" });
+
+// Bounce back and forth 3 times
+gsap.to(".ball", { y: 100, duration: 0.5, repeat: 3, yoyo: true, ease: "power1.inOut" });
+```
+
+## Delay & Queue
+
+```js
+// Simple delay
+gsap.to(".el", { x: 100, delay: 0.5 });
+
+// Queue independent sequences
+gsap.timeline()
+  .to(".a", { x: 100, duration: 0.5 })
+  .to(".b", { x: 100, duration: 0.5 })
+  .to(".c", { x: 100, duration: 0.5 });
+```