transitions-refine 0.3.21 → 0.3.23

package/demo.html

@@ -1202,8 +1202,11 @@
       gap: 8px; box-sizing: border-box; padding: 7.5px 7.5px 7.5px 14px;
       border-bottom: 1px solid #f0f0f0; }
     .tl-refine-titles { min-width: 0; }
-    .tl-refine-titles h3 { font-size: 13px; font-weight: 500; line-height: 14px; color: #17181c; }
-    .tl-refine-titles p { margin-top: 2px; font-size: 12px; font-weight: 400; line-height: 14px; color: #676767;
+    /* Explicit margin:0 — the injected build strips the demo-only global *{margin:0}
+       reset, so without this h3/p inherit the UA default block margins (~1em) and
+       the header balloons to ~82px instead of matching the 52px timeline top bar. */
+    .tl-refine-titles h3 { margin: 0; font-size: 13px; font-weight: 500; line-height: 14px; color: #17181c; }
+    .tl-refine-titles p { margin: 2px 0 0; font-size: 12px; font-weight: 400; line-height: 14px; color: #676767;
       white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 190px; }
     .tl-refine-actions { flex: none; display: flex; align-items: center; gap: 2px; }
     .tl-refine-mode { display: flex; align-items: center; gap: 6px; height: 36px;
@@ -2686,7 +2689,7 @@
     // Shared "Connect with your agent" copy — used by the full-panel gate and by
     // the Refine area when no live agent is connected, so both read identically.
     // `cliMissing` swaps the body to an install-first hint.
-    function AgentConnectBody({cliMissing,reason,onReconnect}){
+    function AgentConnectBody({cliMissing,relayDown,reason,onReconnect}){
       const[rechecking,setRechecking]=useState(false);
       const recheck=async()=>{
         if(!onReconnect||rechecking) return;
@@ -2694,7 +2697,15 @@
         try{ await onReconnect(); } finally { setRechecking(false); }
       };
       return h(React.Fragment,null,
-        cliMissing
+        relayDown
+          // The relay isn't reachable at all — Reconnect can't help (it talks to a
+          // running relay). The only fix is starting the relay again.
+          ? h("p",{className:"tl-gate-text"},
+              "The relay isn’t running. Start it with ",
+              h("code",{className:"tl-code"},"npx transitions-refine live"),
+              " in your project (or ",h("code",{className:"tl-code"},"/refine live"),
+              " in your editor), then retry.")
+          : cliMissing
           ? h("p",{className:"tl-gate-text"},"Install an agent CLI, then run ",
               h("code",{className:"tl-code"},"npx transitions-refine live"),
               " (recommended) or ",h("code",{className:"tl-code"},"/refine live")," in your editor.")
@@ -2704,13 +2715,14 @@
               h("code",{className:"tl-code"},"/refine live"),
               " in your editor if the relay is already up without an agent wired."),
         // Surface WHY the relay couldn't wire a CLI (from /health agentReason) so a
-        // silent fall-back to poller mode is never a mystery. The relay self-heals
-        // on a TTL; Reconnect just forces an immediate re-check.
-        reason&&h("p",{className:"tl-gate-reason"},reason),
+        // silent fall-back to poller mode is never a mystery. Hidden when the relay
+        // is down (the reason is stale). The relay self-heals on a TTL; Reconnect
+        // forces an immediate re-check (or just re-probes /health if it's down).
+        !relayDown&&reason&&h("p",{className:"tl-gate-reason"},reason),
         onReconnect&&h("button",{className:"tl-gate-recheck",disabled:rechecking,onClick:recheck},
-          rechecking?"Reconnecting…":"Reconnect agent"));
+          rechecking?(relayDown?"Retrying…":"Reconnecting…"):(relayDown?"Retry connection":"Reconnect agent")));
     }
-    function RefinePanel({open,onClose,phase,label,refineType,onType,suggestions,summary,error,appliedIds,onApply,onApplyAll,mode,onMode,llmAvailable,cliInstalled,agentReason,onReconnect,onStart,lanes}){
+    function RefinePanel({open,onClose,phase,label,refineType,onType,suggestions,summary,error,appliedIds,onApply,onApplyAll,mode,onMode,llmAvailable,cliInstalled,relayDown,agentReason,onReconnect,onStart,lanes}){
       // mount-on-open; keep mounted through the panel-reveal slide-out, then unmount
       const[render,setRender]=useState(open);
       const[panelOpen,setPanelOpen]=useState(false);
@@ -2820,7 +2832,7 @@
           // /refine live makes the agent available and Start scanning works again.
           return h("div",{className:"tl-refine-center"},
             h("div",{className:"tl-refine-unavail-title"},"Connect with your agent"),
-            h(AgentConnectBody,{cliMissing:cliInstalled===false,reason:agentReason,onReconnect}));
+            h(AgentConnectBody,{cliMissing:cliInstalled===false,relayDown,reason:agentReason,onReconnect}));
         }
         const idleDescR = agentMode ? (REFINE_TYPES.find(t=>t.key===rt)||REFINE_TYPES[0]).desc : (rt==="replace"
           ? "Deterministic mode can't pick a recipe to replace the transition — switch to Agent mode for replacements."
@@ -3812,6 +3824,7 @@
       const[llmAvailable,setLlmAvailable]=useState(null); // null=unknown, true/false from /health
       const[cliInstalled,setCliInstalled]=useState(null); // null=unknown, true/false from /health
       const[agentReason,setAgentReason]=useState(null); // why no CLI is wired (/health agentReason)
+      const[relayDown,setRelayDown]=useState(false); // /health unreachable → relay not running
       // chatLoop = LLM served by the in-chat `/refine live` poll loop (pollerActive
       // and no wired REFINE_AGENT_CMD). This is the mode that bills agent turns
       // while idle, so the header shows a credit warning + Stop for it.
@@ -3833,7 +3846,7 @@
       const chatLoopRef=useRef(false);
       // probe the relay so the idle panel can show the right availability copy
       const refreshHealth=useCallback(async()=>{
-        try{const j=await relayHealth();setLlmAvailable(!!j.llmAvailable);
+        try{const j=await relayHealth();setRelayDown(false);setLlmAvailable(!!j.llmAvailable);
           setCliInstalled(j.cliInstalled==null?null:!!j.cliInstalled);
           setAgentReason(j.agentReason||null);
           const loop=!!j.pollerActive&&!j.agentCmd;
@@ -3844,7 +3857,12 @@
             chatLoopRef.current=true;setChatLoop(true);setLiveStopped(false);
           }else{chatLoopRef.current=false;setChatLoop(false);setLiveStopped(!quietStopRef.current);} // draining
           return j;}
-        catch{chatLoopRef.current=false;setLlmAvailable(false);setCliInstalled(false);setChatLoop(false);return null;}
+        // /health unreachable = the relay isn't running (the daemon a prior
+        // `npx transitions-refine live` started was reaped when the agent shell
+        // ended, etc.). DON'T claim the CLI is missing — that shows the wrong
+        // "install a CLI" copy AND a Reconnect button that POSTs to a dead relay.
+        // Flag relayDown so the gate tells the user to restart the relay instead.
+        catch{chatLoopRef.current=false;setRelayDown(true);setLlmAvailable(false);setChatLoop(false);return null;}
       },[]);
       const stopLive=useCallback(async()=>{
         quietStopRef.current=false;
@@ -4169,7 +4187,19 @@
         if(!specs.length) return ()=>txTeardownPhase(store);
         const varsKey=v=>Object.keys(v).sort().map(k=>k+":"+v[k]).join(";");
         const recompute=()=>{
-          const desired=new Map(); // el → {css,vars}
+          // Two concerns, applied DIFFERENTLY:
+          //   • TIMING (the inline `transition` string) is direction-specific —
+          //     open and close share one element + one inline slot, so it must be
+          //     GATED to the active state (open's timing only while open, etc).
+          //   • VALUE VARS (scale/blur custom props, e.g. --dropdown-pre-scale)
+          //     define a STATE's resting value, not the transition itself. A
+          //     "from" var only shows in the OPPOSITE state, so gating it to the
+          //     destination state means it's never visible (this was the bug:
+          //     accepting a scale edit did nothing live). They're safe to apply
+          //     PERSISTENTLY — each var only affects whichever state references
+          //     it — which previews both directions. So: vars = always, css = gated.
+          const desiredCss=new Map();  // el → css  (state-gated)
+          const desiredVars=new Map(); // el → {name:value}  (persistent)
           for(const sp of specs){
             const stEls=fresh(sp.stateTarget);
             // is THIS phase's destination state active on the stateTarget RIGHT NOW?
@@ -4177,19 +4207,31 @@
             if(sp.toSuf) active=stEls.length?stEls.some(e=>safeMatches(e,sp.toSuf)):true;        // open
             else if(sp.fromSuf) active=stEls.length?stEls.some(e=>!safeMatches(e,sp.fromSuf)):true; // close = not in fromState
             else active=true; // no state info → always reflect (degrades to old behavior)
-            if(!active)continue;
-            for(const mm of sp.members) for(const el of txMemberEls(mm.selector,sp.stateTarget)){ if(inUI(el))continue; desired.set(el,{css:mm.css,vars:mm.vars}); }
+            for(const mm of sp.members) for(const el of txMemberEls(mm.selector,sp.stateTarget)){
+              if(inUI(el))continue;
+              if(mm.vars&&Object.keys(mm.vars).length){ const ex=desiredVars.get(el)||{}; desiredVars.set(el,{...ex,...mm.vars}); }
+              if(active) desiredCss.set(el,mm.css);
+            }
           }
-          for(const [el,d] of desired){
-            const vars=d.vars||{},vk=varsKey(vars),cur=store.applied.get(el);
-            if(cur&&cur.css===d.css&&cur.vk===vk)continue;
-            if(!cur) store.applied.set(el,{prevInline:el.style.transition||"",prevVars:Object.fromEntries(Object.keys(vars).map(n=>[n,el.style.getPropertyValue(n)])),css:d.css,vk});
-            else store.applied.set(el,{prevInline:cur.prevInline,prevVars:cur.prevVars,css:d.css,vk});
-            try{el.style.transition=d.css;}catch{}
+          const allEls=new Set([...desiredCss.keys(),...desiredVars.keys()]);
+          for(const el of allEls){
+            const css=desiredCss.has(el)?desiredCss.get(el):null;
+            const vars=desiredVars.get(el)||{};
+            const vk=varsKey(vars);
+            const cur=store.applied.get(el);
+            if(cur&&cur.css===css&&cur.vk===vk)continue;
+            if(!cur){
+              store.applied.set(el,{prevInline:el.style.transition||"",prevVars:Object.fromEntries(Object.keys(vars).map(n=>[n,el.style.getPropertyValue(n)])),css,vk});
+            }else{
+              const prevVars={...(cur.prevVars||{})};for(const n of Object.keys(vars)){if(!(n in prevVars))prevVars[n]=el.style.getPropertyValue(n);}
+              store.applied.set(el,{prevInline:cur.prevInline,prevVars,css,vk});
+            }
+            const rec=store.applied.get(el);
+            try{el.style.transition=css!=null?css:rec.prevInline;}catch{}
             for(const n of Object.keys(vars)){try{el.style.setProperty(n,vars[n]);}catch{}}
           }
           for(const [el,rec] of Array.from(store.applied)){
-            if(desired.has(el))continue;
+            if(allEls.has(el))continue;
             try{el.style.transition=rec.prevInline;}catch{}
             for(const n of Object.keys(rec.prevVars||{})){try{const pv=rec.prevVars[n];if(pv)el.style.setProperty(n,pv);else el.style.removeProperty(n);}catch{}}
             store.applied.delete(el);
@@ -4367,6 +4409,7 @@
           // resolved — lets the agent recover the opposite phase + toggled state
           // without reading source. Empty → agent falls back to source reads.
           cssRules:harvestCssHints(e)}));
+        let provisionalShown=false; // applied the relay's instant in-process grouping
         try{
           const{id}=await relayCreateJob({kind:"scan",url:location.href,raw});
           for(let i=0;i<520;i++){
@@ -4376,13 +4419,28 @@
             await new Promise(r=>setTimeout(r,i<20?120:300));
             if(scanTokenRef.current!==token)return;
             const job=await relayGetJob(id);
+            // Provisional groups: the relay grouped the CSSOM harvest in-process and
+            // attached it BEFORE the agent answered. Show it instantly so the panel
+            // never sits on "Grouping…" through a cold agent turn; the agent's final
+            // result (with polished names) overwrites it on `done` below.
+            if(job.result&&job.result.provisional&&!provisionalShown){
+              const pg=job.result.groups||[];
+              if(pg.length){registry.setGroups(pg);setScanned(true);provisionalShown=true;}
+            }
             if(job.status==="done"){
               const groups=(job.result&&job.result.groups)||[];
               if(groups.length){registry.setGroups(groups);setScanned(true);
                 try{localStorage.setItem(GROUP_STORE_KEY,JSON.stringify({groups,sig,ts:Date.now()}));}catch{}}
               groupScanRetryRef.current=0;setGroupScanState("done");if(!opts.skipSeed)autoStopAfterScan();return;}
-            if(job.status==="error"){throw new Error(job.error||"scan job errored");}
+            if(job.status==="error"){
+              // No agent answered — but if we already showed provisional groups,
+              // keep them (better than reverting to flat) and treat the scan as done.
+              if(provisionalShown){groupScanRetryRef.current=0;setGroupScanState("done");if(!opts.skipSeed)autoStopAfterScan();return;}
+              throw new Error(job.error||"scan job errored");
+            }
           }
+          // Timed out waiting for the agent: keep any provisional groups we showed.
+          if(provisionalShown){groupScanRetryRef.current=0;setGroupScanState("done");if(!opts.skipSeed)autoStopAfterScan();return;}
           throw new Error("scan timed out");
         }catch(e){
           // Transient failure (a cold-start agent spawn racing on its CLI config,
@@ -4574,13 +4632,13 @@
             h(RefinePanel,{open:refineOpen,onClose:()=>setRefineOpen(false),phase:refinePhase,label:refineLabel,
               refineType,onType:changeRefineType,suggestions:refineSuggestions,summary:refineSummary,error:refineError,
               appliedIds,onApply:applySuggestion,onApplyAll:applyAllSuggestions,
-                    mode:refineMode,onMode:changeRefineMode,llmAvailable,cliInstalled,agentReason,onReconnect:reconnectAgent,onStart:startScan,
+                    mode:refineMode,onMode:changeRefineMode,llmAvailable,cliInstalled,relayDown,agentReason,onReconnect:reconnectAgent,onStart:startScan,
                     lanes:active?.effectiveTimings||[]}))
               : h("div",{className:"tl-panel-main"},
                   gate==="blocked" && h("div",{className:"tl-gate"},
                     h("div",{className:"tl-gate-col"},
                       h("div",{className:"tl-gate-title"},"Connect with your agent"),
-                      h(AgentConnectBody,{cliMissing:cliInstalled===false,reason:agentReason,onReconnect:reconnectAgent})))),
+                      h(AgentConnectBody,{cliMissing:cliInstalled===false,relayDown,reason:agentReason,onReconnect:reconnectAgent})))),
             toast&&createPortal(
               h("div",{className:"tl-toast-wrap","data-tl-ui":"","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.21",
+  "version": "0.3.23",
   "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/group-deterministic.mjs

@@ -0,0 +1,370 @@
+// Provisional, in-process grouping straight from the CSSOM harvest
+// (entry.cssRules + entry.timings). It mirrors what buildScanPrompt asks the
+// agent to do MECHANICALLY for the common case — cluster by component root,
+// split open/close phases, copy the current-state timings, read the
+// opposite-phase timings from a state-variant rule — so the panel can show
+// grouped components in <1s instead of waiting out a cold agent turn.
+//
+// This is deliberately PROVISIONAL: the relay still runs the real agent scan
+// (wired CLI) or leaves the job for a `/refine live` agent, and that result
+// OVERWRITES this one when it lands. So any imperfection here is transient and
+// the FINAL naming/grouping stays agent-quality. We return `null` (defer fully
+// to the agent, today's exact behaviour) whenever the harvest is missing or no
+// confident group emerges — never a worse-than-today result.
+
+// Component vocabulary — names a cluster from its class tokens. Order = most
+// specific first. Only used for the provisional label; the agent renames later.
+// Matched against a name "haystack" with -/_ normalized to spaces, so it hits
+// both class tokens (dd-dropdown) and human labels ("Dropdown panel").
+const VOCAB = [
+  [/\b(?:dropdown|combobox|listbox|autocomplete)\b/i, "Dropdown"],
+  [/\bmenu\b/i, "Menu"],
+  [/\b(?:modal|dialog|lightbox)\b/i, "Modal"],
+  [/\b(?:popover|popup)\b/i, "Popover"],
+  [/\btooltip\b/i, "Tooltip"],
+  [/\b(?:accordion|collapse|collapsible|disclosure)\b/i, "Accordion"],
+  [/\b(?:drawer|offcanvas|sheet)\b/i, "Drawer"],
+  [/\bsidebar\b/i, "Sidebar"],
+  [/\b(?:toast|snackbar|notification)\b/i, "Toast"],
+  [/\btabs?\b/i, "Tabs"],
+  [/\bpanel\b/i, "Panel"],
+];
+
+// State-token class names. A class on an ancestor (or the element) that matches
+// one of these marks the toggled state that drives a phase.
+const OPEN_CLASS = /^(?:is-)?(?:open|opened|active|show|shown|visible|expanded|entered|in)$/i;
+const CLOSE_CLASS = /^(?:is-)?(?:clos(?:e|ed|ing)|hidden|hide|leaving|exiting|out|collapsed)$/i;
+
+function isStateClass(c) {
+  return OPEN_CLASS.test(c) || CLOSE_CLASS.test(c);
+}
+function classPhase(c) {
+  return CLOSE_CLASS.test(c) ? "close" : "open";
+}
+
+// ── tiny CSS helpers ─────────────────────────────────────────────────────────
+
+// Split respecting parens/brackets so cubic-bezier(0.22, 1, 0.36, 1) and
+// [data-state="open"] stay intact.
+function splitTop(str, sep) {
+  const out = [];
+  let depth = 0;
+  let cur = "";
+  for (const ch of String(str)) {
+    if (ch === "(" || ch === "[") depth++;
+    else if (ch === ")" || ch === "]") depth = Math.max(0, depth - 1);
+    if (ch === sep && depth === 0) {
+      out.push(cur);
+      cur = "";
+    } else cur += ch;
+  }
+  out.push(cur);
+  return out.map((s) => s.trim()).filter(Boolean);
+}
+
+function timeToMs(t) {
+  const m = String(t).trim().match(/^(-?[\d.]+)\s*(ms|s)$/i);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  if (!Number.isFinite(n)) return null;
+  return m[2].toLowerCase() === "s" ? Math.round(n * 1000) : Math.round(n);
+}
+
+function parseRule(str) {
+  const i = String(str).indexOf("{");
+  if (i < 0) return null;
+  const head = str.slice(0, i).trim();
+  let body = str.slice(i + 1);
+  const j = body.lastIndexOf("}");
+  if (j >= 0) body = body.slice(0, j);
+  return { selectors: splitTop(head, ","), body };
+}
+
+function declMap(body) {
+  const m = new Map();
+  for (const d of splitTop(body, ";")) {
+    const c = d.indexOf(":");
+    if (c < 0) continue;
+    m.set(d.slice(0, c).trim().toLowerCase(), d.slice(c + 1).trim());
+  }
+  return m;
+}
+
+const EASING_KW = /^(?:ease|ease-in|ease-out|ease-in-out|linear|step-start|step-end)$/i;
+const EASING_FN = /^(?:cubic-bezier|steps|linear)\s*\(/i;
+
+// transition shorthand → [{property,durationMs,delayMs,easing}]
+function parseShorthand(value) {
+  const out = [];
+  for (const seg of splitTop(value, ",")) {
+    const toks = splitTop(seg, " ");
+    let prop = null;
+    let easing = null;
+    const times = [];
+    for (const tk of toks) {
+      const ms = timeToMs(tk);
+      if (ms != null) {
+        times.push(ms);
+        continue;
+      }
+      if (EASING_KW.test(tk) || EASING_FN.test(tk)) {
+        easing = tk;
+        continue;
+      }
+      if (!prop && /^[a-z][\w-]*$/i.test(tk)) prop = tk;
+    }
+    if (prop && prop.toLowerCase() !== "none") {
+      out.push({
+        property: prop,
+        durationMs: times[0] ?? 0,
+        delayMs: times[1] ?? 0,
+        easing: easing || "ease",
+      });
+    }
+  }
+  return out;
+}
+
+function timingsFromBody(body) {
+  const d = declMap(body);
+  if (d.has("transition")) return parseShorthand(d.get("transition"));
+  const props = d.get("transition-property");
+  if (!props) return [];
+  const plist = splitTop(props, ",");
+  const durs = splitTop(d.get("transition-duration") || "", ",").map(timeToMs);
+  const eas = splitTop(d.get("transition-timing-function") || "", ",");
+  const dels = splitTop(d.get("transition-delay") || "", ",").map(timeToMs);
+  const at = (arr, i, fb) => (arr.length ? arr[i % arr.length] : fb);
+  return plist
+    .filter((p) => p && p.toLowerCase() !== "none")
+    .map((p, i) => ({
+      property: p,
+      durationMs: at(durs, i, 0) ?? 0,
+      delayMs: at(dels, i, 0) ?? 0,
+      easing: at(eas, i, "ease") || "ease",
+    }));
+}
+
+// ── selector analysis ────────────────────────────────────────────────────────
+
+// Classes in the LAST compound of a selector (the element the rule targets).
+function leafClasses(selector) {
+  const compounds = String(selector).split(/\s*[>+~]\s*|\s+/).filter(Boolean);
+  const last = compounds[compounds.length - 1] || "";
+  return (last.match(/\.[-\w]+/g) || []).map((s) => s.slice(1));
+}
+
+// Does this selector (one compound chain) target the member identified by its
+// own leaf classes? True when its last compound carries one of those classes.
+function targetsMember(selector, leaf) {
+  if (!leaf.length) return false;
+  const compounds = String(selector).split(/\s*[>+~]\s*|\s+/).filter(Boolean);
+  const last = compounds[compounds.length - 1] || "";
+  return leaf.some((c) => new RegExp("\\." + escapeRe(c) + "(?![\\w-])").test(last));
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// From a state-variant selector that targets `leaf`, pull out the toggled state
+// token and the stateTarget selector (the element the token sits on, with the
+// token stripped). Returns {stateTarget, token, phase} or null.
+function deriveState(selector, leaf) {
+  const compounds = String(selector).split(/\s+/).filter(Boolean); // descendant only — keep it simple
+  if (!compounds.length) return null;
+  const memberIdx = compounds.length - 1;
+  // walk compounds, find the FIRST that carries a state class or state attr.
+  for (let i = 0; i < compounds.length; i++) {
+    const comp = compounds[i];
+    const classes = (comp.match(/\.[-\w]+/g) || []).map((s) => s.slice(1));
+    const stateCls = classes.find(isStateClass);
+    // attribute state: [data-open], [data-state="open"], [aria-expanded="true"], [open]
+    const attr = comp.match(/\[[^\]]+\]/g) || [];
+    const stateAttr = attr.find((a) => /data-open|data-state|aria-expanded|aria-hidden|\bopen\b|visible|expanded/i.test(a));
+
+    if (stateCls) {
+      const target = stripToken(comp, "." + stateCls) + ancestorPrefix(compounds, i);
+      return { stateTarget: normalizeSel(target), token: "." + stateCls, phase: classPhase(stateCls) };
+    }
+    if (stateAttr) {
+      const target = stripToken(comp, stateAttr) + ancestorPrefix(compounds, i);
+      const phase = /clos|hidden|false|collapsed/i.test(stateAttr) ? "close" : "open";
+      return { stateTarget: normalizeSel(target), token: stateAttr, phase };
+    }
+    if (i === memberIdx) break;
+  }
+  return null;
+}
+
+// Build the ancestor prefix selector for the compound at index i (everything
+// before it), so stateTarget keeps its context (".wrap .dd" not just ".dd").
+function ancestorPrefix() {
+  return ""; // single-compound stateTarget is enough for live-preview scoping
+}
+function stripToken(compound, token) {
+  return compound.split(token).join("");
+}
+function normalizeSel(sel) {
+  const s = String(sel).trim();
+  return s || "*";
+}
+
+function humanize(token) {
+  return String(token)
+    .replace(/^[.#]/, "")
+    .replace(/[-_]+/g, " ")
+    .replace(/\b(is|tl|tx|wd|ui|js|css)\b/gi, "")
+    .trim()
+    .replace(/\s+/g, " ")
+    .replace(/^\w/, (c) => c.toUpperCase()) || "Component";
+}
+
+function nameFromTokens(tokens) {
+  const hay = tokens.join(" ").replace(/[-_]+/g, " ");
+  for (const [re, name] of VOCAB) if (re.test(hay)) return name;
+  return null;
+}
+
+function slug(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "group";
+}
+
+// ── per-entry analysis ───────────────────────────────────────────────────────
+
+function analyzeEntry(entry) {
+  if (!entry || !Array.isArray(entry.cssRules) || !entry.cssRules.length) return null;
+  const memberSel = entry.selector || "";
+  const leaf = leafClasses(memberSel);
+  if (!leaf.length) return null;
+
+  const rules = entry.cssRules.map(parseRule).filter(Boolean);
+  let state = null; // {stateTarget, token, phase} — the open toggle
+  let baseTimings = null; // transition on the base (no-state) member rule
+  let openTimings = null; // transition on an OPEN-state variant rule
+  let closeTimings = null; // transition on a CLOSE-state variant rule
+
+  for (const rule of rules) {
+    for (const sel of rule.selectors) {
+      if (!targetsMember(sel, leaf)) continue;
+      const st = deriveState(sel, leaf);
+      const t = timingsFromBody(rule.body);
+      if (st) {
+        if (st.phase === "open" && !state) state = st; // prefer an open token for stateTarget
+        if (st.phase === "open" && t.length) openTimings = t;
+        if (st.phase === "close" && t.length) closeTimings = t;
+        if (!state) state = st; // fall back to a close token if that's all there is
+      } else if (t.length && !baseTimings) {
+        baseTimings = t;
+      }
+    }
+  }
+  if (!state) return null; // no toggle → can't phase it; defer to agent
+
+  // Authoritative live timings for the element's CURRENT DOM state.
+  const current = Array.isArray(entry.timings) && entry.timings.length
+    ? entry.timings.map((t) => ({ property: t.property, durationMs: t.durationMs, delayMs: t.delayMs, easing: t.easing }))
+    : null;
+
+  // Standard pattern: the base rule's transition drives the OPEN (enter); a
+  // `.is-closing`-style variant carries the CLOSE. Fall back sensibly when a
+  // phase has no dedicated rule (one transition both ways).
+  const open = openTimings || baseTimings || current;
+  const close = closeTimings || baseTimings || current;
+  if (!open || !close) return null;
+
+  const memberId = slug(leaf[leaf.length - 1] || entry.label || "member");
+  const member = {
+    id: memberId,
+    label: entry.label || humanize(leaf[leaf.length - 1]),
+    selector: memberSel,
+  };
+  // Name hints: the element's own classes, its stateTarget, AND the human label
+  // the scanner already produced (e.g. "Dropdown panel" → matches /dropdown/).
+  const labelWords = String(entry.label || "").split(/\s+/).filter(Boolean);
+  return {
+    stateTarget: state.stateTarget,
+    token: state.token,
+    member,
+    openTimings: open,
+    closeTimings: close,
+    nameTokens: [...leaf, state.stateTarget, ...labelWords],
+  };
+}
+
+// ── public API ───────────────────────────────────────────────────────────────
+
+export function groupDeterministic(raw) {
+  if (process.env.REFINE_FAST_GROUP === "0") return null;
+  if (!Array.isArray(raw) || !raw.length) return null;
+
+  // Cluster entries by stateTarget. Every entry must analyze; if ANY entry has
+  // cssRules but no resolvable toggle, that one alone shouldn't sink the rest —
+  // but we DO require all-or-nothing on the harvest itself to avoid a confusing
+  // partial provisional. Entries that don't analyze are simply left ungrouped.
+  const clusters = new Map();
+  let analyzed = 0;
+  for (const entry of raw) {
+    const info = analyzeEntry(entry);
+    if (!info) continue;
+    analyzed++;
+    const key = info.stateTarget;
+    if (!clusters.has(key)) clusters.set(key, { stateTarget: key, members: [], tokens: [] });
+    const c = clusters.get(key);
+    c.members.push(info);
+    c.tokens.push(...info.nameTokens);
+  }
+  if (!clusters.size || !analyzed) return null;
+
+  const groups = [];
+  for (const c of clusters.values()) {
+    const openTok = c.members[0].token; // the open toggle on the stateTarget
+    const name = nameFromTokens(c.tokens) || humanize(c.stateTarget);
+    const gid = slug(name + "-" + c.stateTarget);
+
+    // OPEN phase: base → open (use each member's open timings).
+    // CLOSE phase: open → base (use each member's close timings).
+    const openMembers = c.members.map((m) => ({
+      id: m.member.id,
+      label: m.member.label,
+      selector: m.member.selector,
+      propertyTimings: m.openTimings,
+    }));
+    const closeMembers = c.members.map((m) => ({
+      id: m.member.id,
+      label: m.member.label,
+      selector: m.member.selector,
+      propertyTimings: m.closeTimings,
+    }));
+
+    const phases = [
+      {
+        id: gid + ":open",
+        phase: "open",
+        label: "Open",
+        stateTarget: c.stateTarget,
+        fromState: null,
+        toState: openTok,
+        members: openMembers,
+      },
+      {
+        id: gid + ":close",
+        phase: "close",
+        label: "Close",
+        stateTarget: c.stateTarget,
+        fromState: openTok,
+        toState: null,
+        members: closeMembers,
+      },
+    ];
+    groups.push({ id: gid, label: name, component: null, phases, provisional: true });
+  }
+  if (!groups.length) return null;
+
+  return {
+    groups,
+    summary: `Grouped ${groups.length} component${groups.length === 1 ? "" : "s"} (provisional — refining…).`,
+  };
+}
+
+export default groupDeterministic;

package/server/relay.mjs

@@ -31,6 +31,7 @@ import { delimiter, join } from "node:path";
 import { refineTimings, DURATION_TOKENS, SCALE_TOKENS, BLUR_TOKENS, SMOOTH_OUT } from "./motion-tokens.mjs";
 import { buildInjectModule } from "./inject.mjs";
 import { resolveAgentCmd } from "./agent-resolve.mjs";
+import { groupDeterministic } from "./group-deterministic.mjs";
 
 const PORT = Number(process.env.REFINE_RELAY_PORT) || 7331;
 const AUTO = process.env.REFINE_AUTO !== "0";
@@ -703,6 +704,26 @@ const server = createServer(async (req, res) => {
       : (job.request.mode || (llmAvailable() ? "llm" : "deterministic"));
     job.request.mode = mode;
 
+    // Provisional grouping: for a scan, try to group the components IN-PROCESS
+    // from the CSSOM harvest the browser already sent (entry.cssRules). This is
+    // the slow part — a cold agent turn — so showing a result in <1ms here makes
+    // the panel feel instant in BOTH wired and /refine-live modes. The real agent
+    // scan still runs below and OVERWRITES this when it lands (see answerJob /
+    // POST /jobs/:id/result), so final naming/grouping stays agent-quality. When
+    // the grouper isn't confident it returns null → unchanged, agent-only flow.
+    if (job.request.kind === "scan") {
+      try {
+        const prov = groupDeterministic(job.request.raw);
+        if (prov && prov.groups && prov.groups.length) {
+          job.result = { groups: prov.groups, summary: prov.summary, provisional: true };
+          job.updatedAt = now();
+          job.statusLog.push({ message: `Grouped ${prov.groups.length} component(s) — refining names…`, at: now() });
+        }
+      } catch (e) {
+        console.warn(`  provisional grouping failed (${String((e && e.message) || e).slice(0, 120)}) — deferring to agent`);
+      }
+    }
+
     if (!AUTO) {
       // External-poller-only mode: everything waits on GET /jobs/next.
     } else if (mode === "deterministic") {