transitions-refine 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "transitions-refine",
+  "version": "0.1.0",
+  "description": "Live, agent-driven Refine panel for CSS/Motion transitions — injects a timeline + Refine UI and runs transitions.dev suggestions via your coding agent.",
+  "type": "module",
+  "bin": {
+    "refine": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "server",
+    "demo.html",
+    ".agents/skills"
+  ],
+  "scripts": {
+    "prepack": "node scripts/sync-skill.mjs",
+    "live": "node bin/cli.mjs live",
+    "relay": "node server/relay.mjs"
+  },
+  "keywords": [
+    "transitions",
+    "css",
+    "motion",
+    "animation",
+    "timeline",
+    "refine",
+    "cursor",
+    "agent"
+  ],
+  "homepage": "https://transitions.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jakubantalik/transitions.dev.git",
+    "directory": "refine"
+  },
+  "license": "MIT"
+}

package/server/inject.mjs

@@ -0,0 +1,116 @@
+// Builds a self-contained, self-mounting timeline module from the working demo.
+//
+// Instead of maintaining a second copy of the timeline UI, we transform the
+// already-tested code inside demo.html into a single ES module that can be
+// dropped onto ANY page via:
+//
+//     <script type="module" src="http://localhost:7331/inject.js"></script>
+//
+// The module imports React from absolute esm.sh URLs (so the host page does
+// not need an import map), injects the timeline CSS, then mounts the panel
+// into its own container while scanning document.body for CSS transitions.
+
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const DEMO_PATH = fileURLToPath(new URL("../demo.html", import.meta.url));
+
+// Absolute module URLs so the injected script works without an import map.
+const REACT_URL = "https://esm.sh/react@19";
+const REACT_DOM_URL = "https://esm.sh/react-dom@19";
+const REACT_DOM_CLIENT_URL = "https://esm.sh/react-dom@19/client";
+
+const CUT_MARKER = "// ── demo boxes ──";
+
+function extractBetween(src, openRe, closeTag) {
+  const open = src.match(openRe);
+  if (!open) return null;
+  const start = open.index + open[0].length;
+  const end = src.indexOf(closeTag, start);
+  if (end === -1) return null;
+  return src.slice(start, end);
+}
+
+// Remove every /* @inject-skip-start */ … /* @inject-skip-end */ region.
+function stripSkipRegions(css) {
+  return css.replace(/\/\*\s*@inject-skip-start[\s\S]*?@inject-skip-end\s*\*\//g, "").trim();
+}
+
+function buildJs(scriptSrc) {
+  let js = scriptSrc;
+  // Drop everything from the demo-only boxes onward (App + createRoot render).
+  const cut = js.indexOf(CUT_MARKER);
+  if (cut !== -1) js = js.slice(0, cut);
+
+  // Rewrite the demo's bare-specifier imports to absolute URLs.
+  js = js
+    .replace(/import\s+React\s+from\s+["']react["'];?/, `import React from "${REACT_URL}";`)
+    .replace(/import\s+\{\s*createRoot\s*\}\s+from\s+["']react-dom\/client["'];?/, `import { createRoot } from "${REACT_DOM_CLIENT_URL}";`)
+    .replace(/import\s+\{\s*createPortal\s*\}\s+from\s+["']react-dom["'];?/, `import { createPortal } from "${REACT_DOM_URL}";`);
+
+  // Point the relay client at whatever origin served this module, so the panel
+  // works on any port the CLI chose (the script is served BY the relay).
+  js = js.replace(
+    /(import\s+\{\s*createPortal\s*\}\s+from\s+"[^"]+";)/,
+    `$1\n    try { if (typeof window !== "undefined" && !window.REFINE_RELAY_URL) window.REFINE_RELAY_URL = new URL(import.meta.url).origin; } catch (e) {}`
+  );
+
+  return js.trim();
+}
+
+function buildEpilogue(css) {
+  // JSON.stringify handles all escaping for the embedded stylesheet.
+  const cssLiteral = JSON.stringify(css);
+  return `
+// ── injected timeline mount ──
+(function mountInjectedTimeline(){
+  if (typeof document === "undefined") return;
+  if (document.getElementById("tl-inject-root")) return; // idempotent
+
+  if (!document.getElementById("tl-inject-style")) {
+    const st = document.createElement("style");
+    st.id = "tl-inject-style";
+    // Scoped reset so panel layout is correct without touching the host page.
+    st.textContent = "[data-timeline-panel],[data-timeline-panel] *,.tl-refine-panel,.tl-refine-panel *{box-sizing:border-box;}\\n" + ${cssLiteral};
+    document.head.appendChild(st);
+  }
+
+  const mount = document.createElement("div");
+  mount.id = "tl-inject-root";
+  document.body.appendChild(mount);
+
+  function InjectedRoot(){
+    const registry = useMemo(() => new TransitionRegistry(), []);
+    const preview = useMemo(() => new PreviewController(), []);
+    const [activeId, setActiveId] = useState(null);
+    useEffect(() => {
+      const scanner = new DomScanner(document.body, registry);
+      preview.setScanner(scanner);
+      scanner.start();
+      return () => { scanner.stop(); preview.setScanner(null); };
+    }, [registry, preview]);
+    const ctx = useMemo(() => ({ registry, preview, activeId, setActiveId }), [registry, preview, activeId]);
+    return h(TimelineCtx.Provider, { value: ctx }, h(TimelinePanel));
+  }
+
+  createRoot(mount).render(h(InjectedRoot));
+})();
+`;
+}
+
+let _cache = null;
+export async function buildInjectModule({ noCache = false } = {}) {
+  if (_cache && !noCache) return _cache;
+  const html = await readFile(DEMO_PATH, "utf8");
+
+  const styleSrc = extractBetween(html, /<style>/, "</style>");
+  const scriptSrc = extractBetween(html, /<script\s+type="module">/, "</script>");
+  if (!styleSrc || !scriptSrc) {
+    throw new Error("inject: could not locate <style> or module <script> in demo.html");
+  }
+
+  const css = stripSkipRegions(styleSrc);
+  const js = buildJs(scriptSrc);
+  _cache = `${js}\n${buildEpilogue(css)}`;
+  return _cache;
+}

package/server/motion-tokens.mjs

@@ -0,0 +1,106 @@
+// The transitions.dev motion-token vocabulary, plus a deterministic refine pass
+// that maps a transition's current values onto the nearest token and proposes
+// the differences. This mirrors the `transitions refine` behaviour in
+// ~/.agents/skills/transitions-dev/SKILL.md so the reference agent can answer
+// without an LLM. A real agent driven by the skill can do better — it infers
+// *usage* (modal close vs dropdown open) from the surrounding code rather than
+// snapping to the nearest number.
+
+// Durations — from the skill's "## Motion tokens" table.
+export const DURATION_TOKENS = [
+  { ms: 40, name: "Stagger", usage: "per-item stagger offset" },
+  { ms: 80, name: "Micro", usage: "tooltip delay, shake segment, large stagger" },
+  { ms: 150, name: "Quick", usage: "modal close, dropdown close, text swap, tooltip appear" },
+  { ms: 250, name: "Fast", usage: "icon swap, dropdown open, modal open, tabs sliding, page slide" },
+  { ms: 350, name: "Medium", usage: "panel close, toast close" },
+  { ms: 400, name: "Slow", usage: "panel open, skeleton content reveal, input clear" },
+  { ms: 500, name: "Very slow", usage: "emphasis, badge appear, text reveal, success check" },
+];
+
+// The transitions.dev default ease-out — "Smooth ease out" in the skill.
+export const SMOOTH_OUT = "cubic-bezier(0.22, 1, 0.36, 1)";
+
+// Easing values that ARE motion tokens — leave these alone.
+const TOKEN_EASINGS = new Set(
+  [
+    SMOOTH_OUT,
+    "ease-in-out",
+    "ease-out",
+    "linear",
+    "cubic-bezier(0.34, 1.36, 0.64, 1)", // bouncy overshoot (badge pop)
+    "cubic-bezier(0.34, 3.85, 0.64, 1)", // strong bouncy overshoot (avatar return)
+  ].map(normEase)
+);
+
+function normEase(s) {
+  return String(s || "").replace(/\s+/g, "").toLowerCase();
+}
+
+function nearestDuration(ms) {
+  let best = DURATION_TOKENS[0];
+  let bestDelta = Infinity;
+  for (const t of DURATION_TOKENS) {
+    const d = Math.abs(t.ms - ms);
+    if (d < bestDelta) {
+      bestDelta = d;
+      best = t;
+    }
+  }
+  return { token: best, delta: bestDelta };
+}
+
+// A generic/non-token easing the skill would nudge toward the default ease-out.
+function shouldRefineEasing(easing) {
+  const n = normEase(easing);
+  if (!n) return false;
+  if (TOKEN_EASINGS.has(n)) return false;
+  // "ease", "ease-in", or any hand-rolled cubic-bezier that isn't a token.
+  return n === "ease" || n === "ease-in" || n.startsWith("cubic-bezier") || n.startsWith("linear(");
+}
+
+/**
+ * Produce token-alignment suggestions for a list of property timings.
+ * @param {{property:string,durationMs:number,delayMs:number,easing:string}[]} timings
+ * @returns {object[]} suggestions
+ */
+export function refineTimings(timings) {
+  const suggestions = [];
+  if (!Array.isArray(timings)) return suggestions;
+
+  for (const t of timings) {
+    const prop = t.property || "all";
+
+    // Duration → nearest token (skip if already on-grid or within 10ms).
+    if (Number.isFinite(t.durationMs)) {
+      const { token, delta } = nearestDuration(t.durationMs);
+      if (delta > 10) {
+        suggestions.push({
+          id: `${prop}-duration`,
+          kind: "duration",
+          property: prop,
+          title: `Duration → ${token.name}`,
+          from: `${t.durationMs}ms`,
+          to: `${token.ms}ms`,
+          patch: { property: prop, durationMs: token.ms },
+          reason: `${token.name} (${token.ms}ms) is the closest motion token — used for ${token.usage}. ${t.durationMs}ms is off-grid.`,
+        });
+      }
+    }
+
+    // Easing → the transitions.dev default ease-out.
+    if (shouldRefineEasing(t.easing)) {
+      suggestions.push({
+        id: `${prop}-easing`,
+        kind: "easing",
+        property: prop,
+        title: `Easing → Smooth ease out`,
+        from: t.easing,
+        to: SMOOTH_OUT,
+        patch: { property: prop, easing: SMOOTH_OUT },
+        reason: `"${t.easing}" is a generic curve. The transitions.dev standard ease-out reads more intentional on opens, closes, slides, and resizes.`,
+      });
+    }
+  }
+
+  return suggestions;
+}

package/server/refine-agent.mjs

@@ -0,0 +1,86 @@
+// Optional external poller — only for REFINE_AUTO=0 mode.
+//
+// By default the relay answers each job itself with one run (see
+// server/relay.mjs), so you don't need this. It exists for the advanced setup
+// where you start the relay with REFINE_AUTO=0 and want a separate standing
+// process to claim jobs via GET /jobs/next. This implementation is the
+// deterministic, no-LLM one (snaps to the nearest motion token).
+//
+// Run: REFINE_AUTO=0 npm run relay   (in one terminal)
+//      npm run refine-poller          (in another)
+// Don't run it while the relay is in the default auto mode — jobs are already
+// answered, so it would never receive any.
+
+import { refineTimings } from "./motion-tokens.mjs";
+
+const RELAY = process.env.REFINE_RELAY_URL || "http://localhost:7331";
+const IDLE_MS = 800; // poll cadence when there's no work
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function post(path, body) {
+  await fetch(`${RELAY}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+async function handle(job) {
+  const { id, request } = job;
+  const label = request?.label || request?.selector || "transition";
+  console.log(`\n▸ job ${id.slice(0, 8)} — ${label}`);
+
+  await post(`/jobs/${id}/status`, { message: `Scanning "${label}"…` });
+  await sleep(500);
+  await post(`/jobs/${id}/status`, { message: "Matching values to the motion tokens…" });
+  await sleep(600);
+
+  const suggestions = refineTimings(request?.timings || []);
+
+  await post(`/jobs/${id}/status`, {
+    message: suggestions.length
+      ? `Found ${suggestions.length} refinement${suggestions.length === 1 ? "" : "s"}.`
+      : "Already aligned to the motion tokens.",
+  });
+  await post(`/jobs/${id}/result`, {
+    suggestions,
+    summary: suggestions.length
+      ? `${suggestions.length} value${suggestions.length === 1 ? "" : "s"} differ from the transitions.dev tokens.`
+      : "Nothing to refine — values already match the tokens.",
+  });
+  console.log(`  ✓ posted ${suggestions.length} suggestion(s)`);
+}
+
+async function loop() {
+  console.log(`refine agent polling ${RELAY}/jobs/next …`);
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    let res;
+    try {
+      res = await fetch(`${RELAY}/jobs/next`);
+    } catch {
+      console.log("  (relay not reachable — retrying)");
+      await sleep(1500);
+      continue;
+    }
+    if (res.status === 204) {
+      await sleep(IDLE_MS);
+      continue;
+    }
+    if (!res.ok) {
+      await sleep(IDLE_MS);
+      continue;
+    }
+    const job = await res.json();
+    try {
+      await handle(job);
+    } catch (e) {
+      console.error("  ✗ job failed:", e.message);
+      try {
+        await post(`/jobs/${job.id}/error`, { message: String(e.message || e) });
+      } catch {}
+    }
+  }
+}
+
+loop();