transitions-refine 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transitions-refine",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "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": {
@@ -14,6 +14,7 @@
   ],
   "scripts": {
     "prepack": "node scripts/sync-skill.mjs",
+    "build:website-demo": "node scripts/build-website-demo.mjs",
     "live": "node bin/cli.mjs live",
     "relay": "node server/relay.mjs"
   },

package/server/motion-tokens.mjs

@@ -20,6 +20,23 @@ export const DURATION_TOKENS = [
 // The transitions.dev default ease-out — "Smooth ease out" in the skill.
 export const SMOOTH_OUT = "cubic-bezier(0.22, 1, 0.36, 1)";
 
+// Scales — from the skill's "## Motion tokens" Scales table. These are the
+// non-resting ("pre") scale a surface animates FROM (it always settles to 1).
+export const SCALE_TOKENS = [
+  { v: 0.96, name: "Large", usage: "modal open / close" },
+  { v: 0.97, name: "Medium", usage: "dropdown open" },
+  { v: 0.98, name: "Small", usage: "tooltip open" },
+  { v: 0.99, name: "Tiny", usage: "dropdown close" },
+];
+
+// Blur (px) — from the skill's "## Motion tokens" Blur table. The non-resting
+// blur a surface animates FROM (it always settles to 0).
+export const BLUR_TOKENS = [
+  { px: 2, name: "Small", usage: "panel reveal, icon swap, text swap, skeleton reveal, number pop-in" },
+  { px: 3, name: "Medium", usage: "page slide, text reveal" },
+  { px: 8, name: "Large", usage: "success check open" },
+];
+
 // Easing values that ARE motion tokens — leave these alone.
 const TOKEN_EASINGS = new Set(
   [
@@ -49,6 +66,54 @@ function nearestDuration(ms) {
   return { token: best, delta: bestDelta };
 }
 
+function nearestScale(v) {
+  let best = SCALE_TOKENS[0];
+  let bestDelta = Infinity;
+  for (const t of SCALE_TOKENS) {
+    const d = Math.abs(t.v - v);
+    if (d < bestDelta) { bestDelta = d; best = t; }
+  }
+  return { token: best, delta: bestDelta };
+}
+
+function nearestBlur(px) {
+  let best = BLUR_TOKENS[0];
+  let bestDelta = Infinity;
+  for (const t of BLUR_TOKENS) {
+    const d = Math.abs(t.px - px);
+    if (d < bestDelta) { bestDelta = d; best = t; }
+  }
+  return { token: best, delta: bestDelta };
+}
+
+const norm = (s) => String(s || "").toLowerCase();
+
+// Usage-aware token pick — the skill says "match on USAGE, not the nearest
+// number". Even deterministic should honour this when the label/selector/phase
+// reveal the component, so a dropdown's 0.8 pre-scale snaps to 0.97 (dropdown
+// open), not to 0.96 (the nearest number). Returns null when usage is unclear,
+// and the caller falls back to nearest-by-magnitude.
+function pickScaleByUsage(hint) {
+  const h = norm(hint);
+  if (!h) return null;
+  const isClose = /clos/.test(h);
+  if (/\bmodal\b|\bdialog\b|\blightbox\b/.test(h)) return SCALE_TOKENS.find((t) => t.v === 0.96);
+  if (/\btooltip\b|\btip\b|\bpopover\b/.test(h)) return SCALE_TOKENS.find((t) => t.v === 0.98);
+  if (/\bdropdown\b|drop-down|\bmenu\b|\bselect\b|\bcombobox\b|\bcaret\b/.test(h))
+    return SCALE_TOKENS.find((t) => t.v === (isClose ? 0.99 : 0.97));
+  return null;
+}
+
+function pickBlurByUsage(hint) {
+  const h = norm(hint);
+  if (!h) return null;
+  if (/success|check/.test(h)) return BLUR_TOKENS.find((t) => t.px === 8);
+  if (/\bpage\b|\bslide\b/.test(h)) return BLUR_TOKENS.find((t) => t.px === 3);
+  if (/text/.test(h) && /reveal/.test(h)) return BLUR_TOKENS.find((t) => t.px === 3);
+  if (/panel|icon|swap|skeleton|number|digit|reveal/.test(h)) return BLUR_TOKENS.find((t) => t.px === 2);
+  return null;
+}
+
 // A generic/non-token easing the skill would nudge toward the default ease-out.
 function shouldRefineEasing(easing) {
   const n = normEase(easing);
@@ -60,15 +125,21 @@ function shouldRefineEasing(easing) {
 
 /**
  * Produce token-alignment suggestions for a list of property timings.
- * @param {{property:string,durationMs:number,delayMs:number,easing:string}[]} timings
+ * @param {{property:string,durationMs:number,delayMs:number,easing:string,scale?:number,blur?:number,varName?:string,hint?:string}[]} timings
+ * @param {{label?:string,selector?:string,phase?:string}} [ctx] usage hints for scale/blur token selection
  * @returns {object[]} suggestions
  */
-export function refineTimings(timings) {
+export function refineTimings(timings, ctx) {
   const suggestions = [];
   if (!Array.isArray(timings)) return suggestions;
+  const c = ctx || {};
 
   for (const t of timings) {
     const prop = t.property || "all";
+    // Usage hint for scale/blur: combine the transition's label/selector/phase
+    // with this lane's own property/member so component words (dropdown, modal,
+    // page slide…) are visible to the usage matcher.
+    const hint = [c.label, c.selector, c.phase, t.hint, t.property, t.member].filter(Boolean).join(" ");
 
     // Duration → nearest token (skip if already on-grid or within 10ms).
     if (Number.isFinite(t.durationMs)) {
@@ -102,6 +173,49 @@ export function refineTimings(timings) {
         reason: `"${t.easing}" is a generic curve. The transitions.dev standard ease-out reads more intentional on opens, closes, slides, and resizes.`,
       });
     }
+
+    // Scale → a transitions.dev scale token (usage-first, nearest fallback). The
+    // captured value is the non-resting "pre" scale (settles to 1); skip 1/none.
+    if (Number.isFinite(t.scale) && Math.abs(t.scale - 1) > 1e-4) {
+      const usage = pickScaleByUsage(hint);
+      const { token: near, delta } = nearestScale(t.scale);
+      const token = usage || near;
+      // Suggest when usage names a token, or the current value is off-grid.
+      if (token && (usage || delta > 5e-3) && Math.abs(token.v - t.scale) > 1e-4) {
+        suggestions.push({
+          id: `${prop}-scale`,
+          kind: "scale",
+          property: prop,
+          member: t.member || null,
+          title: `Scale → ${token.name}`,
+          from: String(t.scale),
+          to: String(token.v),
+          patch: { property: prop, scale: token.v, ...(t.varName ? { varName: t.varName } : {}), ...(t.member ? { member: t.member } : {}) },
+          reason: `${token.name} (${token.v}) is the transitions.dev scale token for ${token.usage}. ${t.scale} is ${usage ? "off the usage token" : "off-grid"}.`,
+        });
+      }
+    }
+
+    // Blur → a transitions.dev blur token (usage-first, nearest fallback). The
+    // captured value is the non-resting "pre" blur (settles to 0); skip 0/none.
+    if (Number.isFinite(t.blur) && t.blur > 1e-4) {
+      const usage = pickBlurByUsage(hint);
+      const { token: near, delta } = nearestBlur(t.blur);
+      const token = usage || near;
+      if (token && (usage || delta > 0.5) && Math.abs(token.px - t.blur) > 1e-4) {
+        suggestions.push({
+          id: `${prop}-blur`,
+          kind: "blur",
+          property: prop,
+          member: t.member || null,
+          title: `Blur → ${token.name}`,
+          from: `${t.blur}px`,
+          to: `${token.px}px`,
+          patch: { property: prop, blur: token.px, ...(t.varName ? { varName: t.varName } : {}), ...(t.member ? { member: t.member } : {}) },
+          reason: `${token.name} (${token.px}px) is the transitions.dev blur token for ${token.usage}. ${t.blur}px is ${usage ? "off the usage token" : "off-grid"}.`,
+        });
+      }
+    }
   }
 
   return suggestions;

package/server/relay.mjs

@@ -28,7 +28,7 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
-import { refineTimings } from "./motion-tokens.mjs";
+import { refineTimings, DURATION_TOKENS, SCALE_TOKENS, BLUR_TOKENS, SMOOTH_OUT } from "./motion-tokens.mjs";
 import { buildInjectModule } from "./inject.mjs";
 
 const PORT = Number(process.env.REFINE_RELAY_PORT) || 7331;
@@ -55,6 +55,13 @@ const AGENT_CMD = augmentAgentCmd(process.env.REFINE_AGENT_CMD || null);
 // (Opus / GPT-5.5) — forcing a fast model here keeps the initial scan snappy.
 // Override with REFINE_SCAN_MODEL=""  to fall back to the agent's default.
 const SCAN_MODEL = process.env.REFINE_SCAN_MODEL ?? "composer-2.5-fast";
+// Pin a fast model for refine (suggestion) jobs too. The motion-token vocabulary
+// is inlined into the prompt (see MOTION_TOKENS_BLOCK) so a fast model has every
+// fact it needs for the common token-tweak path — keeping suggestions snappy
+// without falling back to the user's (possibly heavy/slow) default model.
+// Override with REFINE_MODEL="" to use the agent's default model if you ever find
+// the fast model regresses a tricky `replace`/recipe judgement. cursor-agent only.
+const REFINE_MODEL = process.env.REFINE_MODEL ?? "composer-2.5-fast";
 const AGENT_TIMEOUT_MS = Number(process.env.REFINE_AGENT_TIMEOUT_MS) || 120000;
 
 // Inject `--model <m>` into a `cursor-agent …` command (after the binary).
@@ -79,6 +86,11 @@ const POLLER_TTL_MS = Number(process.env.REFINE_POLLER_TTL_MS) || 120000;
 // How long a pending LLM job waits to be claimed before erroring. Comfortably
 // above one long-poll cycle so a transient polling gap doesn't fail the job.
 const PENDING_TIMEOUT_MS = Number(process.env.REFINE_PENDING_TIMEOUT_MS) || 120000;
+// Idle auto-stop for the in-chat `/refine live` loop. The chat poll loop costs
+// agent turns even while idle, so after this long with no job we tell the loop
+// to stop (it returns {stop:true} from /jobs/next). 0 disables. Only the chat
+// loop is affected — a wired REFINE_AGENT_CMD never polls /jobs/next.
+const POLLER_IDLE_STOP_MS = Number(process.env.REFINE_POLLER_IDLE_STOP_MS) || 600000;
 
 /** @type {Map<string, Job>} */
 const jobs = new Map();
@@ -90,6 +102,15 @@ let lastPollAt = 0;
 const pollerActive = () => now() - lastPollAt < POLLER_TTL_MS;
 const llmAvailable = () => Boolean(AGENT_CMD) || pollerActive();
 
+// Stop signal for the in-chat `/refine live` loop. Set by POST /poller/stop
+// (the panel's "Stop" button) or by the idle auto-stop; consumed by the next
+// GET /jobs/next, which returns {stop:true} so the loop exits cleanly.
+let stopRequested = false;
+// When did a real job last arrive? Drives idle auto-stop so a forgotten loop
+// can't poll (and bill) forever. Seeded on first poll so a fresh loop gets the
+// full idle window before any auto-stop.
+let lastJobAt = 0;
+
 // Whether the Cursor CLI (cursor-agent) is installed on this machine. Drives the
 // panel's two agent-unavailable states: "Cursor CLI not installed" vs. simply
 // "run /refine live". A wired REFINE_AGENT_CMD implies it's present.
@@ -124,6 +145,7 @@ function createJob(request) {
     updatedAt: now(),
   };
   jobs.set(id, job);
+  lastJobAt = now(); // real work → reset the chat-loop idle auto-stop window
   if (jobs.size > 100) {
     const oldest = [...jobs.values()].sort((a, b) => a.updatedAt - b.updatedAt)[0];
     if (oldest && oldest.status !== "pending" && oldest.status !== "working") jobs.delete(oldest.id);
@@ -144,42 +166,122 @@ function nextPendingLlm() {
 
 // ── answering a job (one run per job) ────────────────────────────────────────
 
+// Inlined transitions.dev motion-token vocabulary (mirrors motion-tokens.mjs and
+// the transitions-dev skill's "## Motion tokens"). Embedding it in the refine
+// prompt means the common token-tweak path needs ZERO file reads — only recipe
+// selection (replace/both) still opens the skill + a reference file.
+const MOTION_TOKENS_BLOCK = [
+  "Motion tokens (transitions.dev) — match on USAGE intent, not the nearest number:",
+  "Durations:",
+  ...DURATION_TOKENS.map((t) => `  - ${t.ms}ms ${t.name}: ${t.usage}`),
+  `Default easing "Smooth ease out": ${SMOOTH_OUT}.`,
+  "Token easings (already on-grid — leave unchanged): ease-out, ease-in-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 overshoot, avatar return).",
+  'Generic curves to nudge toward "Smooth ease out": "ease", "ease-in", or any hand-rolled cubic-bezier()/linear() that is not a token above.',
+  "Scales (the non-resting 'pre' scale a surface animates FROM — it always settles to 1):",
+  ...SCALE_TOKENS.map((t) => `  - ${t.v} ${t.name}: ${t.usage}`),
+  "Blur (the non-resting 'pre' blur a surface animates FROM — it always settles to 0):",
+  ...BLUR_TOKENS.map((t) => `  - ${t.px}px ${t.name}: ${t.usage}`),
+].join("\n");
+
+// Inlined recipe catalog + decision hints (mirrors the transitions-dev skill's
+// "## Quick reference" + "## Decision rules"). Embedding it lets the `replace`
+// path pick a recipe WITHOUT reading SKILL.md — at most it opens the ONE chosen
+// reference file for exact structure/timings.
+const RECIPES_BLOCK = [
+  "transitions.dev recipes — match the inferred USAGE to ONE recipe (reference file in parens):",
+  "- Card resize: a container changes width/height on a layout change (01-card-resize.md)",
+  "- Number pop-in: a number/digit updates (02-number-pop-in.md)",
+  "- Notification badge: a small dot/badge appears on a trigger (03-notification-badge.md)",
+  "- Text states swap: text content changes in place (04-text-states-swap.md)",
+  "- Menu dropdown: an anchored surface grows from its trigger (05-menu-dropdown.md)",
+  "- Modal open/close: a centered dialog scales up, softer scale-down on close (06-modal.md)",
+  "- Panel reveal: a surface slides into a region with a cross-blur (07-panel-reveal.md)",
+  "- Page side-by-side: slide between list<->detail or step1<->step2 (08-page-side-by-side.md)",
+  "- Icon swap: two icons cross-fade in the same slot (09-icon-swap.md)",
+  "- Success check: a checkmark celebration, fade+rotate+bob+stroke-draw (10-success-check.md)",
+  "- Avatar group hover: hover lifts an item in a horizontal stack (11-avatar-group-hover.md)",
+  "- Error state shake: invalid-input shake (12-error-state-shake.md)",
+  "- Input clear with dissolve: clearing a text field (13-input-clear-dissolve.md)",
+  "- Skeleton loader and reveal: placeholder pulses then swaps to real content (14-skeleton-reveal.md)",
+  "- Shimmer text: in-progress/'thinking' text shimmer (15-shimmer-text.md)",
+  "- Tabs sliding: a moving highlight across segmented options (16-tabs-sliding.md)",
+  "- Tooltip open/close: delayed fade+scale in, instant out (17-tooltip.md)",
+  "- Texts reveal: staggered blurred rise of stacked text lines (18-texts-reveal.md)",
+  "- Card hover tilt: 3D tilt toward the pointer (19-card-tilt.md)",
+  "- Plus to menu morph: a circular trigger becomes the surface it opens (20-plus-menu-morph.md)",
+  "- Accordion expand: a collapsible body grows/shrinks in height (21-accordion.md)",
+  "Tie-break: prefer the lower-overhead recipe (card resize over panel reveal, dropdown over modal). If no recipe genuinely fits, return an empty suggestions array.",
+].join("\n");
+
 function buildPrompt(job) {
   const r = job.request || {};
   const rawType = r.refineType || "small";
   const refineType = rawType === "replace" ? "replace" : rawType === "both" ? "both" : "small";
+  const needsRecipe = refineType === "replace" || refineType === "both";
+  // A grouped transition usually has related phases (open + close). When the panel
+  // sends them, a recipe swap is ONE motion and must update every phase together —
+  // so the agent returns a `patches` array (one entry per phase) instead of a
+  // single-phase `patch`.
+  const phases = Array.isArray(r.phases) ? r.phases.filter((p) => p && p.phase) : [];
+  const multiPhase = needsRecipe && phases.length > 1;
   const lines = [
     "You are refining ONE CSS transition against the transitions.dev library and motion tokens.",
-    "Read the transitions-dev skill's SKILL.md (look in .agents/skills/transitions-dev/ or ~/.agents/skills/transitions-dev/) and apply its `transitions refine` behaviour, `## Motion tokens`, and `## Decision rules`.",
+    MOTION_TOKENS_BLOCK,
     "",
     "Transition context (JSON):",
-    JSON.stringify({ label: r.label, selector: r.selector, refineType, timings: r.timings }, null, 2),
+    JSON.stringify({ label: r.label, selector: r.selector, refineType, timings: r.timings, phases: phases.length ? phases : undefined }, null, 2),
     "",
     "Infer each declaration's USAGE (modal close, dropdown open, tooltip, badge, resize, color/theme change…) from the label/selector. Match on usage intent, not the nearest number.",
     "",
+    "Some timings carry VALUES too: a `transform` lane may include `scale` (its non-resting pre-scale, e.g. 0.8) and a `filter` lane may include `blur` (its non-resting pre-blur in px). When present, also check these against the Scales/Blur tokens by USAGE (a dropdown-open surface should pre-scale to 0.97, not whatever number it has) and propose a fix when they differ. A lane may also carry `varName` (the CSS custom property backing the value) — pass it straight through in the patch so the edit targets that variable.",
+    "",
   ];
+  if (needsRecipe) {
+    lines.push(
+      "To pick a whole-transition replacement, match the inferred USAGE against the recipe list below (the skill's decision rules are summarised here — do NOT read SKILL.md or any reference file). Derive the duration/easing from the MOTION TOKENS above for the recipe's phase (open vs close), and put the recipe's reference filename in `reference` so the user can paste the full recipe themselves. The patch only drives the live preview; exact keyframes/structure come from that pasted file — so you never need to open it.",
+      "",
+      RECIPES_BLOCK,
+      "",
+    );
+    if (multiPhase) {
+      lines.push(
+        "RELATED PHASES: `phases` lists this transition's related states (e.g. open AND close). They are ONE motion — a recipe swap must update them TOGETHER. For the replace suggestion emit a `patches` array with ONE entry per phase in `phases`, each shaped `{\"phase\":<that phase's name verbatim>,\"property\":\"all\",\"durationMs\":<recipe duration for THAT phase>,\"easing\":<recipe easing>,\"scale\":<recipe pre-scale for THAT phase>,\"blur\":<recipe pre-blur px for THAT phase>}`. Take each phase's duration from the MOTION TOKENS for that phase — open is usually slower than close (e.g. 250ms open / 150ms close) — and use the same easing for both unless the recipe differs. Include `scale`/`blur` ONLY when the recipe animates transform-scale / filter-blur (omit them otherwise), using the Scales/Blur tokens for that phase. Also include a single `patch` equal to the FIRST phase's entry (it drives the live preview). Apply will write every phase from `patches`.",
+        "",
+      );
+    }
+  }
   if (refineType === "replace") {
     lines.push(
       "refineType is \"replace\": suggest a WHOLE-TRANSITION replacement ONLY — do NOT propose motion-token tweaks (no kind \"duration\"/\"delay\"/\"easing\").",
-      "Run the skill's `## Decision rules` on the inferred usage, pick the SINGLE best-fit transitions.dev recipe, and read its reference file (e.g. 06-modal.md) for the real timings/easing. Emit ONE suggestion with kind \"replace\": set its `patch` to the recipe's recommended duration/easing for the property that already transitions (or \"all\") so Apply works live, add a `reference` field with the reference filename, and name the recipe in `title`/`reason`. Never invent timings — quote the reference file. If no recipe genuinely fits the usage, return an empty suggestions array.",
+      multiPhase
+        ? "Pick the SINGLE best-fit recipe from the list above. Emit ONE suggestion with kind \"replace\": include the `patches` array (one entry per related phase, as described above) AND a single `patch` (the first phase) for the live preview, add a `reference` field with the reference filename, and name the recipe in `title`/`reason`. If no recipe genuinely fits the usage, return an empty suggestions array."
+        : "Pick the SINGLE best-fit recipe from the list above. Emit ONE suggestion with kind \"replace\": set its `patch` to the motion-token duration/easing for the recipe's phase on the property that already transitions (or \"all\") so Apply works live, add a `reference` field with the reference filename, and name the recipe in `title`/`reason`. If no recipe genuinely fits the usage, return an empty suggestions array.",
+      "Answer in ONE response — do NOT read or search files.",
     );
   } else if (refineType === "both") {
     lines.push(
       "refineType is \"both\": produce TWO independent groups in the SAME suggestions array — the UI shows them in separate tabs, so include each group whenever it applies.",
-      "(1) Motion-token tweaks (kind \"duration\"/\"delay\"/\"easing\"): for each declaration, propose the token value only where it DIFFERS from the current one.",
-      "(2) Whole-transition replacement (kind \"replace\"): ALWAYS evaluate one — run the skill's `## Decision rules` on the inferred usage, pick the SINGLE best-fit transitions.dev recipe, and read its reference file (e.g. 06-modal.md) for the real timings/easing. Emit at most ONE \"replace\" suggestion: set its `patch` to the recipe's recommended duration/easing for the property that already transitions (or \"all\"), add a `reference` field with the reference filename, and name the recipe in `title`/`reason`. Never invent timings — quote the reference file. If no recipe genuinely fits the usage, simply omit the replace suggestion.",
+      "(1) Motion-token tweaks (kind \"duration\"/\"delay\"/\"easing\"/\"scale\"/\"blur\"): for each declaration, propose the token value only where it DIFFERS from the current one. Use \"scale\" for an off-token transform pre-scale and \"blur\" for an off-token filter pre-blur, picked by usage.",
+      multiPhase
+        ? "(2) Whole-transition replacement (kind \"replace\"): ALWAYS evaluate one — pick the SINGLE best-fit recipe. Emit at most ONE \"replace\" suggestion with the `patches` array (one entry per related phase) AND a single `patch` (the first phase), a `reference` field, and the recipe named in `title`/`reason`. If no recipe genuinely fits, omit the replace suggestion."
+        : "(2) Whole-transition replacement (kind \"replace\"): ALWAYS evaluate one — pick the SINGLE best-fit recipe from the list above. Emit at most ONE \"replace\" suggestion: set its `patch` to the motion-token duration/easing for the recipe's phase on the property that already transitions (or \"all\"), add a `reference` field with the reference filename, and name the recipe in `title`/`reason`. If no recipe genuinely fits, omit the replace suggestion.",
+      "Answer in ONE response — do NOT read or search files.",
     );
   } else {
     lines.push(
-      "refineType is \"small\": FIRST suggest motion-token tweaks — for each declaration, propose the token value only where it DIFFERS from the current one (kind \"duration\"/\"delay\"/\"easing\").",
-      "THEN, when it is possible and sensible, ALSO add at most ONE kind \"replace\" suggestion (alongside, not instead of, the token tweaks): run the skill's `## Decision rules`, pick the SINGLE best-fit recipe, read its reference file for the real timings, set its `patch` to the recipe's recommended duration/easing for the existing property (or \"all\"), add a `reference` field with the reference filename, and name the recipe in `title`/`reason`. Only add it when the transition is clearly a hand-rolled version of a catalogued recipe or is missing structure the usage calls for; otherwise omit it and let the token tweaks stand alone.",
+      "refineType is \"small\": suggest motion-token tweaks ONLY — for each declaration, propose the token value only where it DIFFERS from the current one (kind \"duration\"/\"delay\"/\"easing\"/\"scale\"/\"blur\"). Use \"scale\" for an off-token transform pre-scale and \"blur\" for an off-token filter pre-blur, picked by usage. Do NOT propose a whole-transition replacement (no kind \"replace\") — the Replace tab requests that separately.",
+      "Answer in ONE response using ONLY the data above. Do NOT read or search files, run tools, spawn subagents, or explore the codebase — the motion tokens contain everything you need. This is a quick judgement, not a coding task.",
     );
   }
   lines.push(
     "",
     "Output ONLY a JSON object — no prose, no markdown fences — shaped exactly like:",
-    '{"summary":"…","suggestions":[{"id":"width-duration","kind":"duration","property":"width","title":"Duration → Fast","from":"400ms","to":"250ms","patch":{"property":"width","durationMs":250},"reason":"…"}]}',
-    'In each `patch` include only the changed fields (durationMs, delayMs, easing); `property` must match an input property or "all". If nothing should change, return an empty suggestions array.',
+    '{"summary":"…","suggestions":[{"id":"width-duration","kind":"duration","property":"width","member":"Container","title":"Duration → Fast","from":"400ms","to":"250ms","patch":{"property":"width","member":"Container","durationMs":250},"reason":"…"}]}',
+    'A scale tweak looks like {"id":"transform-scale","kind":"scale","property":"transform","member":"Menu","title":"Scale → Medium","from":"0.8","to":"0.97","patch":{"property":"transform","member":"Menu","scale":0.97},"reason":"…"}; a blur tweak like {"id":"filter-blur","kind":"blur","property":"filter","member":"Panel","title":"Blur → Small","from":"8px","to":"2px","patch":{"property":"filter","member":"Panel","blur":2},"reason":"…"}.',
+    "CRITICAL — `member`: every suggestion and its `patch` MUST echo the `member` of the input lane it came from, copied VERBATIM from that lane in the data above. This is REQUIRED whenever any input lane carries a `member` — most importantly when several lanes share the same `property` (e.g. a dropdown where a caret does `transform: rotate` AND a panel does `transform: scale`): the `member` is the ONLY way to tell which lane a `transform` tweak targets. Omitting it mislabels the suggestion onto the wrong element. Omit `member` only for lanes that genuinely have none.",
+    multiPhase
+      ? 'A multi-phase replace suggestion ALSO carries a `patches` array, e.g. "patches":[{"phase":"open","property":"all","durationMs":250,"easing":"cubic-bezier(0.22, 1, 0.36, 1)","scale":0.97},{"phase":"close","property":"all","durationMs":150,"easing":"cubic-bezier(0.22, 1, 0.36, 1)","scale":0.99}]. In each `patch`/`patches` entry include only the changed fields (durationMs, delayMs, easing, scale, blur — plus `member` copied from the input lane, and `varName` if the input lane had one); `property` must match an input property or "all".'
+      : 'In each `patch` include only the changed fields (durationMs, delayMs, easing, scale, blur — plus `member` copied from the input lane, and `varName` if the input lane had one); `property` must match an input property or "all". If nothing should change, return an empty suggestions array.',
   );
   return lines.join("\n");
 }
@@ -220,7 +322,31 @@ function parseScanOutput(stdout) {
   return { groups: obj.groups, summary: obj.summary ?? null };
 }
 
-function runAgentCmd(cmd, prompt, parse = parseAgentOutput) {
+// Serialize cursor-agent spawns. Two cursor-agent processes started at once race
+// on their shared CLI config — one renames `…/cli-config.json.tmp → cli-config.json`
+// while the other already moved it, so the loser crashes with ENOENT mid config
+// save and its scan/refine job fails. Because the relay fires every job via
+// setImmediate, a cold-start scan + any other job spawn in parallel and trip this.
+// Running cursor-agent one-at-a-time removes the race; jobs are rarely concurrent
+// so the queuing cost is negligible (and each attempt is still bounded by
+// AGENT_TIMEOUT_MS). Non-cursor CLIs are left to run freely.
+let agentLock = Promise.resolve();
+function withAgentLock(fn) {
+  const run = agentLock.then(fn, fn);
+  // keep the chain alive regardless of this run's outcome
+  agentLock = run.then(() => {}, () => {});
+  return run;
+}
+
+// Failures worth retrying: transient agent startup / shared-config races, not
+// genuine "the model answered wrong" errors (those reject from parse, not here)
+// or timeouts (a retry would just time out again).
+const AGENT_TRANSIENT_RE = /ENOENT|EAGAIN|EBUSY|ECONNRESET|EPIPE|cli-config|\brename\b|failed to start/i;
+const AGENT_RETRIES = Number.isFinite(Number(process.env.REFINE_AGENT_RETRIES))
+  ? Number(process.env.REFINE_AGENT_RETRIES)
+  : 2;
+
+function runAgentOnce(cmd, prompt, parse) {
   return new Promise((resolve, reject) => {
     const child = spawn("sh", ["-c", cmd], { stdio: ["pipe", "pipe", "pipe"] });
     let out = "";
@@ -249,6 +375,34 @@ function runAgentCmd(cmd, prompt, parse = parseAgentOutput) {
   });
 }
 
+// Spawn the agent CLI once per attempt, serializing cursor-agent runs and
+// retrying transient startup/config-race failures with backoff. A retry re-spawns
+// a fresh process (read-only scan/refine, idempotent apply), so it's safe — and
+// the backoff happens OUTSIDE the lock so a retrying job doesn't block others.
+async function runAgentCmd(cmd, prompt, parse = parseAgentOutput) {
+  const isCursor = /(^|\s|\/)cursor-agent(\s|$)/.test(cmd || "");
+  const attempt = () =>
+    isCursor ? withAgentLock(() => runAgentOnce(cmd, prompt, parse)) : runAgentOnce(cmd, prompt, parse);
+  const maxTries = 1 + Math.max(0, AGENT_RETRIES);
+  let lastErr;
+  for (let i = 0; i < maxTries; i++) {
+    try {
+      return await attempt();
+    } catch (e) {
+      lastErr = e;
+      const msg = String((e && e.message) || e);
+      if (i < maxTries - 1 && AGENT_TRANSIENT_RE.test(msg)) {
+        const backoff = 250 * (i + 1) + Math.floor(Math.random() * 150);
+        console.warn(`  ↻ agent attempt ${i + 1}/${maxTries} failed (${msg.slice(0, 120)}) — retrying in ${backoff}ms`);
+        await new Promise((r) => setTimeout(r, backoff));
+        continue;
+      }
+      throw e;
+    }
+  }
+  throw lastErr;
+}
+
 // Prompt for an "apply" job: the agent edits the user's source so the selected
 // transition uses the approved timings.
 function buildApplyPrompt(job) {
@@ -259,11 +413,11 @@ function buildApplyPrompt(job) {
     "Change context (JSON):",
     JSON.stringify({ label: r.label, selector: r.selector, component: r.component, group: r.group, phase: r.phase, changes: r.changes }, null, 2),
     "",
-    "If `phase` is set (e.g. \"open\"/\"close\"), the change targets ONE state of a component — edit the rule for THAT state (e.g. the `.is-open` rule for open, the `.is-closing`/base rule for close), not the other phase. Each change may carry its own `member` + `selector` identifying which element it belongs to.",
+    "Each change may carry its own `phase` (e.g. \"open\"/\"close\"), `member`, and `selector`. A change's `phase` targets ONE state of the component — edit the rule for THAT state (e.g. the `.is-open` rule for open; the `.is-closing`/base rule for close), NOT the other phase. The top-level `phase` is only a fallback for changes that omit their own. A recipe swap may include changes for BOTH open and close — apply each to its own phase's rule so the open and close timings end up different where the recipe says so.",
     "",
     "Steps:",
     "1. Find where this transition is defined in the source. Search by the per-change `selector`/`member`, the `component` hint, and class names. Handle plain CSS, CSS Modules, styled-components/emotion template literals, Tailwind utilities/config, inline style objects, and Motion/Framer variants — the browser selector is a hint, the real declaration may live in any of these.",
-    "2. For each change, edit the source so that property's transition uses the `to` values: durationMs (ms), easing, delayMs (ms). Keep the file's existing unit/format conventions (e.g. `0.25s` vs `250ms`) and only touch the timing of the named property on the right member + phase. If a CSS variable / design token backs the value, update it at the most sensible single place.",
+    "2. For each change, edit the source so that property's transition uses the `to` values. A change's `to` may include timing (durationMs in ms, easing, delayMs in ms) AND/OR values: `scale` (the non-resting transform pre-scale, e.g. set `transform: scale(0.97)` on the pre-open/closed state — never the resting scale(1)) and `blur` (the non-resting filter pre-blur in px, e.g. `filter: blur(2px)` on that same state). If the change carries `varName`, the value is backed by that CSS custom property — update the variable's value at its definition instead of the inline declaration. Keep the file's existing unit/format conventions (e.g. `0.25s` vs `250ms`) and only touch the named property on the right member + phase.",
     "3. Make the minimal edit. Do not reformat or change unrelated code.",
     "",
     'Output ONLY a JSON object — no prose, no markdown fences — shaped exactly like:',
@@ -308,7 +462,8 @@ function refineDeterministic(job) {
       summary: "Replacing a whole transition needs the agent — switch to the Agent tab and run `/refine live`.",
     };
   }
-  const suggestions = refineTimings(job.request?.timings || []);
+  const r = job.request || {};
+  const suggestions = refineTimings(r.timings || [], { label: r.label, selector: r.selector, phase: r.phase });
   return {
     suggestions,
     summary: suggestions.length
@@ -372,7 +527,9 @@ async function answerJob(job) {
         );
       }
       job.statusLog.push({ message: "Asking your agent…", at: now() });
-      result = await runAgentCmd(AGENT_CMD, buildPrompt(job));
+      const t0 = now();
+      result = await runAgentCmd(withModel(AGENT_CMD, REFINE_MODEL), buildPrompt(job));
+      console.log(`  ⏱ refine agent ${job.id.slice(0, 8)} (${job.request?.refineType || "small"}) ${now() - t0}ms`);
     } else {
       job.statusLog.push({ message: "Matching values to the motion tokens…", at: now() });
       result = refineDeterministic(job);
@@ -497,11 +654,27 @@ const server = createServer(async (req, res) => {
   // GET /jobs/next — long-poll claimed by a `/refine live` agent (LLM jobs).
   if (method === "GET" && path === "/jobs/next") {
     lastPollAt = now();
+    if (!lastJobAt) lastJobAt = now(); // seed idle window on the loop's first poll
+    // Stop signal (manual Stop button or idle auto-stop) → tell the loop to exit.
+    // A pending job always wins so we never drop real work on the stop edge.
+    if ((stopRequested || (POLLER_IDLE_STOP_MS && now() - lastJobAt >= POLLER_IDLE_STOP_MS)) && !nextPendingLlm()) {
+      stopRequested = false;
+      lastJobAt = 0;
+      lastPollAt = 0; // loop is exiting → report it inactive immediately on /health
+      return send(res, 200, { stop: true });
+    }
     const deadline = now() + LONGPOLL_MS;
     const attempt = () => {
       if (res.writableEnded) return;
+      if (stopRequested && !nextPendingLlm()) {
+        stopRequested = false;
+        lastJobAt = 0;
+        lastPollAt = 0; // loop is exiting → report it inactive immediately on /health
+        return send(res, 200, { stop: true });
+      }
       const job = nextPendingLlm();
       if (job) {
+        lastJobAt = now();
         job.status = "working";
         job.updatedAt = now();
         return send(res, 200, { id: job.id, request: job.request });
@@ -512,6 +685,13 @@ const server = createServer(async (req, res) => {
     return attempt();
   }
 
+  // POST /poller/stop — the panel's "Stop" button. Flags the in-chat loop to
+  // exit on its next poll. No-op for a wired REFINE_AGENT_CMD (never polls).
+  if (method === "POST" && path === "/poller/stop") {
+    stopRequested = true;
+    return send(res, 200, { ok: true, stopping: pollerActive() });
+  }
+
   const m = path.match(/^\/jobs\/([^/]+)(?:\/(status|result|error))?$/);
   if (m) {
     const job = jobs.get(m[1]);