monomind 1.16.6 → 1.16.8

package/packages/@monomind/cli/.claude/skills/monomotion/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: monomotion
+description: HTML-native animation system using GSAP — timeline-driven, API-controllable animations that run in the browser without video rendering or React. Covers timeline control, WebSocket/REST-driven playback, effects, and sequencing.
+version: 1.0.0
+triggers:
+  - /monomotion
+  - /animate
+  - /animation
+  - make an animation
+  - create an animation
+  - add animation
+  - build animation
+  - animate this
+  - animate the
+  - web animation
+  - html animation
+  - browser animation
+  - motion graphics
+  - animated ui
+  - timeline animation
+  - gsap
+  - control animation
+  - api animation
+  - animate via api
+  - playback control
+  - animation controller
+  - animated intro
+  - animated outro
+  - transition animation
+  - scroll animation
+  - text animation
+  - svg animation
+  - animate on scroll
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+# Monomotion — HTML Animation with GSAP
+
+API-controllable, HTML-native animation using GSAP. No React, no video rendering — animations run live in the browser and are fully controllable via JavaScript API, WebSocket, or REST.
+
+## Core Philosophy
+
+- Animations are **timelines** — sequences of tweens with precise timing
+- Timelines are **pausable, seekable, reversible** at any point
+- Control surfaces (API, WebSocket, UI) are **decoupled** from animation definitions
+- CSS transitions and keyframes are **not used** — GSAP owns all motion
+
+## Setup
+
+```html
+<!-- CDN — drop into any HTML file -->
+<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+
+<!-- With ScrollTrigger plugin -->
+<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
+```
+
+```bash
+# npm install
+npm install gsap
+```
+
+```js
+import { gsap } from "gsap";
+```
+
+## Basic Timeline
+
+```js
+const tl = gsap.timeline({ paused: true });
+
+tl.to(".box", { x: 200, duration: 0.8, ease: "power2.out" })
+  .to(".box", { opacity: 0, duration: 0.4 }, "+=0.2")
+  .from(".title", { y: -50, autoAlpha: 0, duration: 0.6 }, "<");
+```
+
+**Position parameter shortcuts:**
+- `"+=0.2"` — 0.2s after previous tween ends
+- `"-=0.1"` — 0.1s before previous tween ends
+- `"<"` — same start time as previous tween
+- `"1.5"` — absolute 1.5s mark in timeline
+
+## Playback Control API
+
+```js
+tl.play();             // play forward from current position
+tl.pause();            // freeze
+tl.resume();           // resume from paused position
+tl.reverse();          // play backward from current position
+tl.restart();          // jump to start and play
+tl.seek(1.5);          // jump to 1.5s (no play)
+tl.progress(0.5);      // jump to 50% of total duration
+tl.timeScale(2);       // 2× speed
+tl.timeScale(0.5);     // half speed
+
+// Read state
+tl.time();             // current time in seconds
+tl.progress();         // 0–1
+tl.duration();         // total duration
+tl.isActive();         // true if currently playing
+```
+
+## Named Labels for Scene Control
+
+```js
+tl.addLabel("intro", 0)
+  .addLabel("reveal", 1.5)
+  .addLabel("outro", 3.0);
+
+// Jump to scene
+tl.seek("reveal");
+tl.play("outro");
+```
+
+## API-Driven Control
+
+See [rules/api-control.md](rules/api-control.md) for WebSocket, REST, and SSE control patterns.
+
+## Effects & Presets
+
+See [rules/effects.md](rules/effects.md) for reusable fade, slide, scale, and reveal effects.
+
+## Sequencing & Staggering
+
+See [rules/sequencing.md](rules/sequencing.md) for staggered lists, cascades, and orchestrated sequences.
+
+## Text Animations
+
+See [rules/text.md](rules/text.md) for character-by-character, word-by-word, and typewriter effects.
+
+## Scroll-Driven Animations
+
+See [rules/scroll.md](rules/scroll.md) for ScrollTrigger integration — scrub, pin, and enter/leave triggers.
+
+## SVG Animations
+
+See [rules/svg.md](rules/svg.md) for path drawing, morphing, and SVG-specific techniques.
+
+## Integration Patterns
+
+See [rules/integration.md](rules/integration.md) for embedding monomotion in dashboards, iframes, and web components.

package/packages/@monomind/cli/.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/packages/@monomind/cli/.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/packages/@monomind/cli/.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/packages/@monomind/cli/.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();
+```