transitions-refine 0.3.20 → 0.3.22

package/demo.html

@@ -2686,7 +2686,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 +2694,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 +2712,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 +2829,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 +3821,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 +3843,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 +3854,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;
@@ -4367,6 +4382,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 +4392,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 +4605,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.20",
+  "version": "0.3.22",
   "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";
@@ -138,13 +139,6 @@ const PENDING_TIMEOUT_MS = Number(process.env.REFINE_PENDING_TIMEOUT_MS) || 1200
 // 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;
-// While the Stop latch is held, a genuinely new `/refine live` session can resume
-// itself implicitly: only after polling has been *quiet* this long (the old loop
-// actually died) do we treat the next poll as a fresh session and auto-resume.
-// Must exceed a looping agent's poll gap, so an agent that ignores Stop and keeps
-// polling can never clear the latch — it just keeps getting {stop:true}. (An
-// updated agent also resumes explicitly via POST /poller/start, no wait needed.)
-const STOP_QUIET_MS = Number(process.env.REFINE_STOP_QUIET_MS) || 15000;
 
 /** @type {Map<string, Job>} */
 const jobs = new Map();
@@ -160,9 +154,6 @@ let lastPollAt = 0;
 // re-polls — can never silently revive the session. This is what makes the
 // panel's Stop button stick instead of flipping "Live" back on seconds later.
 let pollerStopped = false;
-// When did a poll last arrive *while latched*? Used to detect that the old loop
-// went quiet so a genuinely new session (or re-run) can auto-resume.
-let lastStoppedPollAt = 0;
 const pollerActive = () => !pollerStopped && now() - lastPollAt < POLLER_TTL_MS;
 const llmAvailable = () => Boolean(agentCmd()) || pollerActive();
 
@@ -713,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") {
@@ -740,21 +751,15 @@ 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") {
-    // Stopped latch: a Stop was issued and not yet resumed. Keep telling every
-    // poller to exit and report inactive until either an explicit POST
-    // /poller/start, or polling goes quiet for STOP_QUIET_MS (the old loop died)
-    // and a new poll arrives — only then is it a genuinely fresh session.
-    // A pending job always wins so we never drop real work on the edge.
+    // Stopped latch: a Stop was issued and not yet resumed. STICKY — every poll
+    // gets {stop:true} and the poller reports inactive until an explicit
+    // POST /poller/start (a fresh `/refine live` / loop announcing itself) or a
+    // relay restart. We deliberately do NOT auto-resume on a quiet gap: a stubborn
+    // agent's straggler poll arriving seconds later would be misread as a new
+    // session and flip the panel back to "Live" — which is exactly the bug where
+    // Stop "didn't stick". A pending job still wins so we never drop real work.
     if (pollerStopped && !nextPendingLlm()) {
-      if (lastStoppedPollAt && now() - lastStoppedPollAt >= STOP_QUIET_MS) {
-        // Quiet gap → the previous loop is gone. This poll is a fresh session.
-        pollerStopped = false;
-        lastStoppedPollAt = 0;
-        // fall through to normal handling below (counts as live again)
-      } else {
-        lastStoppedPollAt = now(); // a poller is still hammering us → hold the latch
-        return send(res, 200, { stop: true });
-      }
+      return send(res, 200, { stop: true });
     }
     lastPollAt = now();
     if (!lastJobAt) lastJobAt = now(); // seed idle window on the loop's first poll
@@ -762,8 +767,7 @@ const server = createServer(async (req, res) => {
     // loop to exit. A pending job always wins so we never drop real work.
     if ((stopRequested || (POLLER_IDLE_STOP_MS && now() - lastJobAt >= POLLER_IDLE_STOP_MS)) && !nextPendingLlm()) {
       stopRequested = false;
-      pollerStopped = true; // latch until /poller/start or a quiet gap
-      lastStoppedPollAt = 0;
+      pollerStopped = true; // latch until an explicit /poller/start
       lastJobAt = 0;
       lastPollAt = 0; // loop is exiting → report it inactive immediately on /health
       return send(res, 200, { stop: true });
@@ -773,8 +777,7 @@ const server = createServer(async (req, res) => {
       if (res.writableEnded) return;
       if (stopRequested && !nextPendingLlm()) {
         stopRequested = false;
-        pollerStopped = true; // latch until /poller/start or a quiet gap
-        lastStoppedPollAt = 0;
+        pollerStopped = true; // latch until an explicit /poller/start
         lastJobAt = 0;
         lastPollAt = 0; // loop is exiting → report it inactive immediately on /health
         return send(res, 200, { stop: true });
@@ -797,8 +800,7 @@ const server = createServer(async (req, res) => {
   if (method === "POST" && path === "/poller/stop") {
     const wasActive = now() - lastPollAt < POLLER_TTL_MS;
     stopRequested = true;
-    pollerStopped = true; // latch: stays stopped until /poller/start or a quiet gap
-    lastStoppedPollAt = 0;
+    pollerStopped = true; // latch: stays stopped until an explicit /poller/start
     lastPollAt = 0; // report inactive immediately; a straggler poll won't revive it
     return send(res, 200, { ok: true, stopping: wasActive });
   }
@@ -822,11 +824,10 @@ const server = createServer(async (req, res) => {
 
   // POST /poller/start — a fresh `/refine live` agent (or loop) announces itself
   // and clears the Stop latch so its polls count as live again. Without this an
-  // explicit re-run would have to wait out the quiet window. Call it once at loop
-  // startup, before the first GET /jobs/next.
+  // explicit re-run couldn't resume at all (the sticky latch tells every poll to
+  // stop). Call it once at loop startup, before the first GET /jobs/next.
   if (method === "POST" && path === "/poller/start") {
     pollerStopped = false;
-    lastStoppedPollAt = 0;
     stopRequested = false;
     lastJobAt = now();
     lastPollAt = now();