transitions-refine 0.3.5 → 0.3.7

package/.agents/skills/refine-live/SKILL.md

@@ -203,21 +203,31 @@ separately. You fix that by reading the source. The request looks like:
 }
 ```
 
+**Be fast.** The `raw.timings` are already accurate for each element's *current*
+on-screen state — treat them as ground truth and reuse them verbatim. Read as
+little source as you need: only to (a) group elements into components, (b)
+recover the *opposite* phase (e.g. close) that isn't in the DOM right now, and
+(c) find the toggled state. Don't open files just to re-read timings you were
+already given.
+
 Do this:
 
 1. **Identify each animated component** the raw entries belong to (dropdown,
-   modal, tooltip, accordion, drawer, toast…). Use the selectors/labels as hints,
-   then read the source — plain CSS / CSS Modules, styled-components/emotion,
-   Tailwind, inline styles, or Motion/Framer variants.
+   modal, tooltip, accordion, drawer, toast…). The selectors/labels usually make
+   this obvious — only read source (plain CSS / CSS Modules,
+   styled-components/emotion, Tailwind, inline styles, Motion/Framer variants)
+   when the grouping is genuinely unclear.
 2. **Split each component into phases** — usually `open` and `close` (a hover-only
-   component can be a single phase). Open and close often live on different
-   selectors (`.is-open` vs `.is-closing`) with different timings; report **both**
-   even though only one is in the DOM right now.
+   component can be a single phase). The phase matching the current DOM reuses the
+   provided timings; the *opposite* phase often lives on a different selector
+   (`.is-open` vs `.is-closing`) with different timings — read source for that one.
+   Report **both** even though only one is in the DOM right now.
 3. **List each phase's members** — the elements that animate in that phase. Give
    each a stable `id`, a human `label`, a live-resolvable CSS `selector`, an
    optional `toState` hint (the class/attribute that drives the phase, e.g.
-   `.is-open`), and its real `propertyTimings`. **Quote the real timings from the
-   source — never invent.**
+   `.is-open`), and its `propertyTimings`. For the current-state phase, **copy the
+   provided `raw.timings` verbatim**; for the opposite phase, **quote the real
+   timings from source — never invent.**
 4. **Post the groups** (this completes the job):
 
    ```bash

package/bin/cli.mjs

@@ -24,6 +24,13 @@ import { homedir } from "node:os";
 const PKG_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const CWD = process.cwd();
 const HOME = process.env.HOME || homedir();
+const PKG_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")).version || "0";
+  } catch {
+    return "0";
+  }
+})();
 
 const MARK_START = "<!-- timeline-inject:start -->";
 const MARK_END = "<!-- timeline-inject:end -->";
@@ -81,14 +88,27 @@ function escapeRe(s) {
 
 // Copy a whole skill directory from the package into the user's project so the
 // in-IDE agent (/refine live) and any spawned cursor-agent can read it.
+//
+// Crucially this REFRESHES a stale copy on upgrade. An older installed skill can
+// shadow newer job handling — e.g. a pre-scan `refine-live` skill that doesn't
+// know how to answer kind:"scan" jobs, so scan jobs time out and the panel hangs
+// on "Agent is scanning…". We stamp the package version into the skill dir and
+// re-copy whenever it's missing or mismatched (so we don't clobber every run).
 function dropSkill(name) {
   const src = join(PKG_ROOT, ".agents/skills", name);
   const destDir = join(CWD, ".agents/skills", name);
   if (!existsSync(src)) return false;
-  if (existsSync(destDir)) return "exists";
+  const marker = join(destDir, ".refine-version");
+  const existed = existsSync(destDir);
+  if (existed) {
+    let installed = null;
+    try { installed = readFileSync(marker, "utf8").trim(); } catch {}
+    if (installed === PKG_VERSION) return "exists";
+  }
   mkdirSync(dirname(destDir), { recursive: true });
-  cpSync(src, destDir, { recursive: true });
-  return true;
+  cpSync(src, destDir, { recursive: true, force: true });
+  try { writeFileSync(marker, PKG_VERSION + "\n"); } catch {}
+  return existed ? "updated" : true;
 }
 
 // ── agent CLI (for the persistent LLM path) ──────────────────────────────────
@@ -162,7 +182,8 @@ function cmdLive(args) {
   for (const name of ["refine-live", "transitions-dev"]) {
     const r = dropSkill(name);
     if (r === true) log(`✓ added .agents/skills/${name}`);
-    else if (r === "exists") log(`✓ ${name} skill already present`);
+    else if (r === "updated") log(`✓ updated .agents/skills/${name} (now v${PKG_VERSION})`);
+    else if (r === "exists") log(`✓ ${name} skill already present (v${PKG_VERSION})`);
   }
 
   // 2.5) ensure an agent CLI so the relay can answer LLM jobs itself — this is

package/demo.html

@@ -1085,8 +1085,20 @@
     .tl-gate-beam-fill { display: block; width: 100%; height: 100%; border-radius: 36px; background: #fff; }
     .tl-gate-sub { margin: 16px 0 0; max-width: 244px; font-size: 12px; font-weight: 400; line-height: 14px;
       color: #6f6f6f; text-wrap: pretty; }
+    /* recovery actions when a scan errored/timed out — never trap the panel */
+    .tl-gate-actions { display: flex; align-items: center; gap: 8px; margin: 18px 0 0; }
+    .tl-gate-btn { height: 32px; padding: 0 14px; border: 0; border-radius: 60px; cursor: pointer;
+      font: 500 12px/14px inherit; color: #2c2c2c; background: #f3f3f3; white-space: nowrap;
+      box-shadow: 0 1px 3px 0 rgba(0,0,0,0.04), inset 0 0 0 1px rgba(0,0,0,0.06), inset 0 -1px 0 0 rgba(0,0,0,0.10);
+      transition: background 140ms cubic-bezier(0.4,0,0.2,1); }
+    .tl-gate-btn:hover { background: #ececec; }
+    .tl-gate-btn:active { background: #e6e6e6; }
+    .tl-gate-btn-primary { color: #fff; background: #0a84ff;
+      box-shadow: 0 0 0 1px rgba(0,101,208,0.10) inset, 0 -1px 0 0 rgba(3,66,142,0.15) inset, 0 1px 3px 0 rgba(4,41,117,0.08); }
+    .tl-gate-btn-primary:hover { background: #0a78e6; }
     @media (prefers-reduced-motion: reduce) {
-      .tl-gate, .tl-gate-pill-wrap .tl-gate-beam { animation: none !important; } }
+      .tl-gate, .tl-gate-pill-wrap .tl-gate-beam { animation: none !important; }
+      .tl-gate-btn { transition: none !important; } }
     /* dot-matrix loader — ported from @dotmatrix/dotm-square-14
        (github.com/zzzzshawn/matrix, MIT). A 5×5 dot grid cross-fades through four
        frame masks in the sequence 0→1→2→3→2→1, dot opacities x=1 / o=0.52 / .=0.08.
@@ -2718,6 +2730,9 @@
       const[acceptError,setAcceptError]=useState(null);
       // ── grouped scan (agent reads source → Open/Close phases) ──
       const[groupScanState,setGroupScanState]=useState("idle"); // idle | scanning | done | error
+      // Escape hatch for the gate: if a scan errors/times out the user can choose
+      // to proceed with the flat (ungrouped) list instead of being trapped.
+      const[skipGrouping,setSkipGrouping]=useState(false);
       const didGroupScanRef=useRef(false);
       const[refineLabel,setRefineLabel]=useState(null);
       const[appliedIds,setAppliedIds]=useState({});
@@ -2966,11 +2981,13 @@
         // Capped (~12s) so a page with no resolvable flat entries can never hang
         // the panel on "Grouping…" — it falls through to the empty-flat check below.
         let prev=-1,stable=0,iters=0;
-        while(scanTokenRef.current===token&&iters++<40){
+        while(scanTokenRef.current===token&&iters++<60){
           const n=registry.getAll().filter(e=>e.kind!=="phase").length;
-          if(n>0&&n===prev){if(++stable>=2)break;}else stable=0;
+          // two consecutive equal reads is enough; at 150ms ticks that's ~300ms
+          // instead of the old ~900ms, shaving dead time off every scan.
+          if(n>0&&n===prev){if(++stable>=1)break;}else stable=0;
           prev=n;
-          await new Promise(r=>setTimeout(r,300));
+          await new Promise(r=>setTimeout(r,150));
         }
         if(scanTokenRef.current!==token)return;
         const flat=registry.getAll().filter(e=>e.kind!=="phase");
@@ -2987,9 +3004,9 @@
           timings:(e.baseLanes||[]).map(l=>({property:l.property,durationMs:l.durationMs,delayMs:l.delayMs,easing:l.easing}))}));
         try{
           const{id}=await relayCreateJob({kind:"scan",url:location.href,raw});
-          for(let i=0;i<520;i++){
+          for(let i=0;i<500;i++){
             if(scanTokenRef.current!==token)return; // superseded / unmounted
-            await new Promise(r=>setTimeout(r,500));
+            await new Promise(r=>setTimeout(r,300));
             if(scanTokenRef.current!==token)return;
             const job=await relayGetJob(id);
             if(job.status==="done"){
@@ -3010,6 +3027,7 @@
       const rescanTransitions=useCallback(()=>{
         try{localStorage.removeItem(GROUP_STORE_KEY);}catch{}
         registry.clearGroups();
+        setSkipGrouping(false); // re-engage the gate so a fresh scan can be shown
         runGroupScan();
       },[runGroupScan,GROUP_STORE_KEY,registry]);
       // Gate the auto group-scan behind a live agent: the panel stays on the
@@ -3067,13 +3085,19 @@
 
       // gate: the panel is unusable until a live agent is connected AND it has
       // scanned the page's transitions.
-      //   loading  → first /health probe pending (blank, avoids a text flash)
-      //   blocked  → no live agent → "Before we start" (run /refine live)
-      //   scanning → live agent, scan in flight → "Agent is scanning…"
-      //   ready    → live + scan done → the real timeline UI
+      //   loading    → first /health probe pending (blank, avoids a text flash)
+      //   blocked    → no live agent → "Before we start" (run /refine live)
+      //   scanning   → live agent, scan in flight → "Agent is scanning…"
+      //   scan-error → scan failed/timed out → recoverable (retry / continue)
+      //   ready      → live + scan settled (done or idle, or user skipped) → real UI
+      // NOTE: "idle" and "error" must NOT keep us on the scanning screen, or a
+      // timed-out scan (e.g. an older /refine-live skill that can't answer scan
+      // jobs) would trap the panel forever with no way out.
       const gate = !live
         ? (llmAvailable===null ? "loading" : "blocked")
-        : (groupScanState==="done" ? "ready" : "scanning");
+        : groupScanState==="scanning" ? "scanning"
+        : (groupScanState==="error" && !skipGrouping) ? "scan-error"
+        : "ready";
       return h(React.Fragment,null,
         render&&h("div",{className:"t-panel-slide","data-timeline-panel":true,
             "data-open":panelOpen?"true":"false","data-phase":phase,style:{height:panelHeight+"px"}},
@@ -3109,7 +3133,16 @@
                         h("span",{className:"tl-gate-pill"},
                           h(DotmLoader),
                           h("span",{className:"tl-gate-pill-label"},"Agent is scanning your transitions"))),
-                      h("p",{className:"tl-gate-sub"},"Just a moment while we get things ready.")))),
+                      h("p",{className:"tl-gate-sub"},"Just a moment while we get things ready."))),
+                  gate==="scan-error" && h("div",{className:"tl-gate"},
+                    h("div",{className:"tl-gate-col"},
+                      h("div",{className:"tl-gate-title"},"We couldn’t scan your transitions"),
+                      h("p",{className:"tl-gate-text"},
+                        "The agent didn’t finish grouping. Make sure ",h("code",{className:"tl-code"},"/refine live"),
+                        " is running with the latest skill, then try again — or continue with the ungrouped list."),
+                      h("div",{className:"tl-gate-actions"},
+                        h("button",{className:"tl-gate-btn tl-gate-btn-primary",onClick:rescanTransitions},"Try again"),
+                        h("button",{className:"tl-gate-btn",onClick:()=>setSkipGrouping(true)},"Continue without grouping"))))),
             toast&&createPortal(
               h("div",{className:"tl-toast-wrap","aria-live":"polite"},
                 h("div",{className:cx("tl-toast",toast.closing&&"is-closing")},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transitions-refine",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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": {

package/server/relay.mjs

@@ -50,7 +50,26 @@ function augmentAgentCmd(cmd) {
   return extra.length ? `${cmd} ${extra.join(" ")}` : cmd;
 }
 const AGENT_CMD = augmentAgentCmd(process.env.REFINE_AGENT_CMD || null);
+// Pin a fast model for scan jobs. Grouping is a structured task that doesn't
+// need a heavy reasoning model, and the user's *default* model may be a slow one
+// (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";
 const AGENT_TIMEOUT_MS = Number(process.env.REFINE_AGENT_TIMEOUT_MS) || 120000;
+
+// Inject `--model <m>` into a `cursor-agent …` command (after the binary).
+// IMPORTANT: `--model` and the SCAN_MODEL slug (e.g. "composer-2.5-fast") are
+// cursor-agent-specific. If a user wired a different CLI (Codex, Claude Code, …)
+// into REFINE_AGENT_CMD, appending the flag would be invalid and break the scan,
+// so we leave non-cursor commands untouched — those agents still get the speedup
+// from the trimmed scan prompt. Also a no-op when the model is empty
+// (REFINE_SCAN_MODEL="") or a model is already pinned explicitly.
+function withModel(cmd, model) {
+  if (!cmd || !model) return cmd;
+  if (!/cursor-agent/.test(cmd)) return cmd; // not cursor-agent → don't touch
+  if (/(^|\s)--model(\s|=)/.test(cmd)) return cmd; // respect an explicit choice
+  return cmd.replace(/^(\s*\S+)/, `$1 --model ${model}`);
+}
 const LONGPOLL_MS = Number(process.env.REFINE_LONGPOLL_MS) || 25000;
 // Grace window after a `/refine live` agent's last poll during which LLM mode is
 // still reported "available". Kept well above LONGPOLL_MS so the normal gaps
@@ -260,21 +279,19 @@ function buildScanPrompt(job) {
   return [
     "You are GROUPING UI transitions by reading the user's SOURCE CODE. A naive DOM scan only sees each element's current computed transition — it cannot tell open from close, and lists related elements separately. Fix that.",
     "",
-    "Raw DOM-detected transitions (JSON) — use as hints to locate the components, not as the final answer:",
+    "Raw DOM-detected transitions (JSON). These timings are ALREADY ACCURATE for the component's CURRENT on-screen state — treat them as ground truth, do NOT re-derive them from source:",
     JSON.stringify({ url: r.url, raw: r.raw }, null, 2),
     "",
+    "To stay fast, read as little source as you need — only to (a) group elements into components, (b) recover the OPPOSITE phase (e.g. close) that isn't in the DOM right now, and (c) find the toggled state. Do not open files just to re-read timings you were already given.",
+    "",
     "Steps:",
-    "1. Identify each animated UI component (dropdown, modal, tooltip, accordion, drawer, toast…). Read its source (CSS/CSS Modules, styled-components/emotion, Tailwind, inline styles, Motion/Framer variants).",
-    "2. For each component, split into PHASES — typically `open` and `close` (a hover-only component may have a single phase). Open and close often live on different selectors (e.g. `.is-open` vs `.is-closing`) with different timings; report BOTH even though only one is in the DOM right now.",
+    "1. Identify each animated UI component (dropdown, modal, tooltip, accordion, drawer, toast…). The provided `label`/`selector`/`properties` usually make the grouping obvious; only read source when the grouping is genuinely unclear.",
+    "2. For each component, split into PHASES — typically `open` and `close` (a hover-only component may have a single phase). The phase matching the CURRENT DOM state reuses the provided timings verbatim. The OPPOSITE phase often lives on a different selector (e.g. `.is-open` vs `.is-closing`) with different timings — read source for that one. Report BOTH even though only one is in the DOM right now.",
     "3. PHASE STATE — how the phase is driven (REQUIRED for playback to work). For each phase provide:",
     "   - `stateTarget`: a CSS selector for the ONE element whose class/attribute is toggled to drive the whole phase (e.g. the dropdown root, the `.modal`, the element with `[data-open]`). It MUST resolve in the live DOM RIGHT NOW, in any state — so it must NOT itself contain the toggled state (write `.t-morph`, never `.t-morph[data-open=\"true\"]`).",
     "   - `fromState` and `toState`: the class/attribute on `stateTarget` at the START and END of this phase, as a token: a class `\".is-open\"`, an attribute `\"[data-open=\\\"true\\\"]\"`, or `null`/`\"\"` for the base/no-class state. OPEN usually goes base→open (`fromState:null`, `toState:\".is-open\"`); CLOSE goes open→base (`fromState:\".is-open\"`, `toState:null`). Get the DIRECTION right — open must animate into the open look, close must animate back out.",
-    "4. For each phase, list its MEMBER elements (panel, backdrop, the staggered items…). Give each member a stable `id`, a human `label`, a CSS `selector`, and its real `propertyTimings`. The member `selector` MUST resolve in the live DOM RIGHT NOW regardless of phase — use the BASE element selector and do NOT bake the phase's toggled class/attribute into it (write `.t-morph .t-morph-plus`, never `.t-morph[data-open=\"true\"] .t-morph-plus`). The toggled state belongs only in the phase's `stateTarget`/`toState`.",
-    "5. TIMINGS MUST BE EXACT AND PER-PROPERTY. This is the most common mistake — do not make it:",
-    "   - List one `propertyTimings` entry per animated property. Read EACH property's own duration/delay/easing from the shorthand `transition:` list (or the property-specific longhand). Do NOT copy one property's duration onto the others, and do NOT use the phase's longest/representative duration for every lane.",
-    "   - Resolve CSS custom properties (e.g. `var(--morph-fade-dur)`) to concrete numbers by following the `:root`/scope where they're defined; convert `s`→ms (`0.25s`→250). Never emit a `var(...)` or a guess.",
-    "   - It is normal and expected for properties within one phase to differ (e.g. opacity/filter 200ms but transform 350ms). If every property in a phase ends up identical, re-read the source — you probably collapsed them by mistake.",
-    "   - Open and close usually have DIFFERENT durations/easings; report each from its own rule.",
+    "4. For each phase, list its MEMBER elements (panel, backdrop, the staggered items…). Give each member a stable `id`, a human `label`, a CSS `selector`, and its `propertyTimings`. For the phase that matches the current DOM, COPY each member's `propertyTimings` straight from the provided `raw.timings` (same per-property duration/delay/easing) — don't change numbers you were handed. The member `selector` MUST resolve in the live DOM RIGHT NOW regardless of phase — use the BASE element selector and do NOT bake the phase's toggled class/attribute into it (write `.t-morph .t-morph-plus`, never `.t-morph[data-open=\"true\"] .t-morph-plus`). The toggled state belongs only in the phase's `stateTarget`/`toState`.",
+    "5. TIMINGS ARE PER-PROPERTY. For the OPPOSITE phase you read from source: list one `propertyTimings` entry per animated property with its own duration/delay/easing; resolve CSS custom properties (e.g. `var(--morph-fade-dur)`) to concrete numbers and convert `s`→ms (`0.25s`→250); never emit a `var(...)` or a guess. Open and close usually have DIFFERENT durations/easings. (The current-state phase just reuses the provided numbers.)",
     "",
     "Output ONLY a JSON object — no prose, no markdown fences — shaped exactly like:",
     '{"summary":"Grouped 3 components.","groups":[{"id":"dropdown","label":"Dropdown","component":"src/Dropdown.tsx","phases":[{"id":"dropdown:open","phase":"open","label":"Open","stateTarget":".dropdown","fromState":null,"toState":".is-open","members":[{"id":"panel","label":"Panel","selector":".dropdown .dropdown-panel","propertyTimings":[{"property":"opacity","durationMs":200,"delayMs":0,"easing":"ease-out"},{"property":"transform","durationMs":200,"delayMs":0,"easing":"cubic-bezier(0.22, 1, 0.36, 1)"}]}]},{"id":"dropdown:close","phase":"close","label":"Close","stateTarget":".dropdown","fromState":".is-open","toState":null,"members":[{"id":"panel","label":"Panel","selector":".dropdown .dropdown-panel","propertyTimings":[{"property":"opacity","durationMs":150,"delayMs":0,"easing":"ease-in"},{"property":"transform","durationMs":150,"delayMs":0,"easing":"ease-in"}]}]}]}]}',
@@ -340,7 +357,7 @@ async function answerJob(job) {
         );
       }
       job.statusLog.push({ message: "Reading components from source…", at: now() });
-      result = await runAgentCmd(AGENT_CMD, buildScanPrompt(job), parseScanOutput);
+      result = await runAgentCmd(withModel(AGENT_CMD, SCAN_MODEL), buildScanPrompt(job), parseScanOutput);
       job.result = { groups: result.groups, summary: result.summary };
       job.status = "done";
       job.updatedAt = now();