transitions-refine 0.1.2 → 0.2.0

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

@@ -1,6 +1,6 @@
 ---
 name: refine-live
-description: Become the live "Refine" agent for the Timeline Inspector. Use when the user runs `/refine live`, asks to "refine live", "go live", "answer refine jobs", or wants the timeline panel's Refine button (LLM mode) to be backed by a real agent. Long-polls the local refine relay, reasons about each CSS transition with the transitions-dev skill, and posts suggestions back to the browser panel.
+description: Become the live "Refine" agent for the Timeline Inspector. Use when the user runs `/refine live`, asks to "refine live", "go live", "answer refine jobs", or wants the timeline panel's Refine button (LLM mode), Accept button, or grouped scan to be backed by a real agent. Long-polls the local refine relay, reasons about each CSS transition with the transitions-dev skill, posts suggestions back to the browser panel, for "scan" jobs groups the page's transitions into components with open/close phases by reading the source, and for "apply" jobs writes the accepted timing changes into the user's source code.
 ---
 
 # Refine Live
@@ -54,6 +54,15 @@ never has to re-run `/refine live`.
      }
      ```
 
+   - **If `request.kind === "scan"`** this is not a suggestion job — the panel is
+     asking you to group the page's transitions by reading the source. Jump to
+     [`## Scan jobs`](#scan-jobs-group-from-source) and return `groups` instead of
+     suggestions.
+   - **If `request.kind === "apply"`** this is not a suggestion job — the user
+     pressed **Accept** to write changes to their code. Jump to
+     [`## Apply jobs`](#apply-jobs-write-to-source) and edit the source instead of
+     posting suggestions. Everything below (refineType, steps 3–4) is for the
+     normal Refine flow.
    - `refineType` chooses what kinds of suggestions to make (it mirrors the
      panel's two tabs):
      - `"small"` (or missing) → **Small refinements**: nudge the existing
@@ -171,6 +180,133 @@ never has to re-run `/refine live`.
    stop, tell them the LLM tab will go unavailable and how to restart
    (`/refine live`).
 
+## Scan jobs (group from source)
+
+When a claimed job has `request.kind === "scan"`, the panel wants you to turn a
+flat list of DOM-detected transitions into **components with phases**. A naive
+DOM scan only sees each element's *current* computed transition — it can't tell
+open from close, and lists related elements (panel, backdrop, staggered items)
+separately. You fix that by reading the source. The request looks like:
+
+```json
+{
+  "id": "uuid",
+  "request": {
+    "kind": "scan",
+    "url": "http://localhost:5173/",
+    "raw": [
+      { "label": "div.dropdown-panel", "selector": ".dropdown-panel",
+        "properties": ["opacity","transform"],
+        "timings": [{ "property": "opacity", "durationMs": 200, "delayMs": 0, "easing": "ease-out" }] }
+    ]
+  }
+}
+```
+
+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.
+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.
+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.**
+4. **Post the groups** (this completes the job):
+
+   ```bash
+   curl -s -X POST http://localhost:7331/jobs/<id>/result \
+     -H 'Content-Type: application/json' \
+     -d '{
+       "summary": "Grouped Dropdown into Open/Close.",
+       "groups": [
+         { "id": "dropdown", "label": "Dropdown", "component": "src/Dropdown.tsx",
+           "phases": [
+             { "id": "dropdown:open", "phase": "open", "label": "Open", "members": [
+               { "id": "panel", "label": "Panel", "selector": ".dropdown-panel", "toState": ".is-open",
+                 "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", "members": [
+               { "id": "panel", "label": "Panel", "selector": ".dropdown-panel", "toState": ".is-closing",
+                 "propertyTimings": [
+                   { "property": "opacity", "durationMs": 150, "delayMs": 0, "easing": "ease-in" }
+                 ] }
+             ] }
+           ] }
+       ]
+     }'
+   ```
+
+   If you can't confidently group anything, post `{"groups":[],"summary":"…"}` —
+   the panel keeps its flat DOM scan. Reserve `/jobs/<id>/error` for unexpected
+   failures.
+
+Then go back to step 1 of the loop.
+
+## Apply jobs (write to source)
+
+When a claimed job has `request.kind === "apply"`, the user accepted their current
+timeline values and wants them written to the codebase. The request looks like:
+
+```json
+{
+  "id": "uuid",
+  "request": {
+    "kind": "apply",
+    "label": "Dropdown · Close",
+    "selector": ".dropdown-panel",
+    "component": "src/Dropdown.tsx",
+    "group": "Dropdown",
+    "phase": "close",
+    "changes": [
+      { "property": "opacity", "member": "Panel", "selector": ".dropdown-panel",
+        "from": { "durationMs": 300, "delayMs": 0, "easing": "ease" },
+        "to": { "durationMs": 150, "delayMs": 0, "easing": "cubic-bezier(0.4, 0, 1, 1)" } }
+    ]
+  }
+}
+```
+
+Do this:
+
+1. **Locate the real declaration in the source.** The `selector` is a DOM-path
+   *hint*, not necessarily the source selector. Use the `component` hint and search
+   by the label/class names; handle whatever the project uses: plain CSS / CSS
+   Modules, styled-components or emotion template literals, Tailwind utilities
+   (`duration-300`, arbitrary `[transition-duration:300ms]`, or the
+   `tailwind.config` theme), inline `style={{ transition: … }}` objects, and
+   Motion/Framer variants. Match by the `from` values to disambiguate.
+   - **If `phase` is set** (e.g. `"open"`/`"close"`), edit only that state's rule
+     (the `.is-open` rule for open, the `.is-closing`/base rule for close) — not
+     the other phase. Each change's `member` + `selector` says which element.
+2. **Edit each change's property** to its `to` values (`durationMs` ms, `easing`,
+   `delayMs` ms) on the right member + phase. Keep the file's existing unit/format
+   (`0.25s` vs `250ms`) and touch only that property's timing. If a CSS variable /
+   design token backs the value, update it at the single most sensible place.
+3. **Minimal edit** — no reformatting or unrelated changes.
+4. **Post the outcome** (this completes the job):
+
+   ```bash
+   curl -s -X POST http://localhost:7331/jobs/<id>/result \
+     -H 'Content-Type: application/json' \
+     -d '{"applied":true,"summary":"Set .t-modal transition to 150ms ease-in","files":["src/Modal.css:42"]}'
+   ```
+
+   If you cannot confidently find the declaration, post
+   `{"applied":false,"summary":"<what you searched and why not found>"}` (still a
+   `result`, not an `error`). Reserve `/jobs/<id>/error` for unexpected failures.
+
+Then go back to step 1 of the loop.
+
 ## Suggestion shape (must match the panel)
 
 Each suggestion object:

package/README.md

@@ -2,7 +2,9 @@
 
 A live, agent-driven **Refine** panel for CSS and [Motion](https://motion.dev) transitions. One command injects a docked timeline + Refine panel onto your running app — no `npm install`, no source edits of your own — and every "Refine" click asks a coding agent to review the selected transition against the [transitions.dev](https://transitions.dev) motion tokens and suggest token-aligned values (or a whole-transition replacement from the library).
 
-The feedback shows up **in a panel that slides in from the right** — not in your chat — and you pick which suggestions to apply. Applied suggestions are **live overrides** (instant preview, reversible) — the same path as dragging the timeline bars.
+The feedback shows up **in a panel that slides in from the right** — not in your chat — and you pick which suggestions to apply. Applied suggestions are **live overrides** (instant preview, reversible) — the same path as dragging the timeline bars. When you're happy, **Accept** writes those values back into your source via the agent.
+
+Real components rarely live in one CSS rule. A dropdown has an **Open** and a **Close** phase, each animating several elements (panel, backdrop, staggered items) with different timings — and the close phase usually isn't even in the DOM while the panel is open. So when the panel opens it also asks the agent to **read your source and group** the page's transitions into components → phases → member elements. You then pick a whole phase (e.g. *Dropdown · Open*) and see every sub-transition as a labeled lane on one shared timeline; Play arms all of them together. If no agent is live, the panel falls back to the flat DOM scan with no regression.
 
 Inspired by the [impeccable.style](https://impeccable.style/live-mode/) "live" pattern: the browser drops a job in a tiny local relay, and the relay answers it with **one agent run per click**. No standing loop, nothing to start per click — you just keep the relay running.
 
@@ -54,11 +56,23 @@ REFINE_AGENT_CMD='cursor-agent -p' npm run relay   # or: codex exec -  |  claude
 
 The CLI must have the `transitions-dev` skill available (the prompt tells it to read the skill).
 
+## Grouped scan — Open / Close phases
+
+When the panel opens it posts a **scan job** to the relay; the agent reads your source and returns the page's animated components, each split into phases (`open`, `close`, …) with their **member elements** and the *real* per-state timings — including the close transition the DOM can't show you. The picker then groups by component, you select a phase, and the timeline renders one lane per member-property (each lane labeled with its member) on a single time axis so stagger and delays line up. **Play** arms every member of the phase at once (driving each element via its `toState` class/attribute), and **Accept** writes back to the correct state rule (`.is-open` vs `.is-closing`) per member.
+
+Grouping needs the agent (`/refine live`, `--llm`, or `REFINE_AGENT_CMD`); with no agent the panel just shows the flat DOM scan as before.
+
 ## Refine modes
 
 - **Small refinements** — keeps the transition, suggests motion-token tweaks (duration/easing), and may add a whole-transition replacement when one clearly fits better.
 - **Replace transition** — only whole-transition replacements from the transitions.dev library (no token tweaks). This path needs the agent; the deterministic answerer will tell you to switch to the LLM.
 
+## Accept — write changes to your code
+
+The **Accept** button (next to Refine) is enabled whenever the selected transition has unsaved changes — whether you edited the bars/easing by hand or applied a Refine suggestion. Pressing it sends an **apply job** to the relay: the agent finds where that transition is declared in your source (plain CSS, CSS Modules, styled-components/emotion, Tailwind, or inline styles), edits only the changed timings, and reports back. The button shows a spinner while saving and flips to **Done** on success.
+
+Like Replace, Accept needs the agent — run `/refine live` (or `--llm` / `REFINE_AGENT_CMD`). The deterministic answerer can't edit files. Play preview also no longer needs you to trigger the transition first: it recovers the end-state from your stylesheets (hover/focus pseudo-states and toggled classes like `.modal.open`), so opening the panel and pressing Play just works.
+
 ## Pieces
 
 | Piece | File | Role |
@@ -80,9 +94,9 @@ The CLI must have the `transitions-dev` skill available (the prompt tells it to
 | `REFINE_AUTO=0` | — | disable auto-answer and wait for an external poller |
 | `window.REFINE_RELAY_URL` | injected origin | browser override for the relay URL |
 
-Endpoints: `POST /jobs`, `GET /jobs/:id` (browser). In `REFINE_AUTO=0` mode an external poller also uses `GET /jobs/next` and `POST /jobs/:id/{status,result,error}`.
+Endpoints: `POST /jobs` (refine, `kind: "apply"`, or `kind: "scan"`), `GET /jobs/:id` (browser). In `REFINE_AUTO=0` mode an external poller also uses `GET /jobs/next` and `POST /jobs/:id/{status,result,error}` (the result body accepts `suggestions`, `groups`, or `applied`).
 
-Writing a value back to your source is a separate, explicit step (treat it like a normal edit / `transitions apply`).
+Refine suggestions stay as live overrides until you press **Accept**, which is the explicit step that writes them into your source.
 
 ## License
 

package/demo.html

@@ -164,7 +164,21 @@
     .tl-header .tl-ghost-btn,
     .tl-header .tl-icon-btn,
     .tl-header .tl-sec-btn,
+    .tl-header .tl-accept-btn,
     .tl-header .tl-refine-btn { border-radius: 60px; }
+    .tl-accept-btn { display: inline-flex; align-items: center; gap: 8px; height: 36px; padding: 0 14px;
+      border: none; cursor: pointer; font-weight: 500; font-size: 13px; line-height: 14px; color: #17181C;
+      background: #fff; box-shadow: 0 1px 3px 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.06), inset 0 0 0 1px rgba(196,196,196,0.10);
+      transition: background 140ms ease, scale 140ms ease, opacity 140ms ease; }
+    .tl-accept-btn > svg { width: 16px; height: 16px; color: #17181C; flex: none; }
+    .tl-accept-btn:hover:not(:disabled) { background: #f9f9f9; }
+    .tl-accept-btn:active:not(:disabled) { background: #f9f9f9; scale: 0.96; }
+    .tl-accept-btn:disabled { opacity: 0.5; cursor: default; }
+    .tl-accept-spin { width: 16px; height: 16px; flex: none; border-radius: 50%;
+      border: 2px solid rgba(0,0,0,0.15); border-top-color: #17181C; animation: tl-accept-rot 0.7s linear infinite; }
+    @keyframes tl-accept-rot { to { transform: rotate(360deg); } }
+    @media (prefers-reduced-motion: reduce) { .tl-accept-spin { animation-duration: 1.4s; } }
 
     /* ghost button: transparent, grey on hover/pressed (Figma #f7f7f7) */
     .tl-ghost-btn { position: relative; display: inline-flex; align-items: center; gap: 6px; height: 36px;
@@ -309,8 +323,15 @@
       position: relative; z-index: 5; cursor: grabbing; }
     .tl-prop-row.reordering .tl-prop-grip { color: var(--c-ruler); cursor: grabbing; }
     .tl-prop-label { font-size: 13px; font-weight: 500; line-height: 18px; color: var(--c-text-mut2); white-space: nowrap; overflow: hidden;
-      text-overflow: ellipsis; text-transform: capitalize; }
+      text-overflow: ellipsis; text-transform: capitalize; display: flex; align-items: center; gap: 6px; min-width: 0; }
     .tl-prop-row.selected .tl-prop-label { color: #171717; }
+    .tl-prop-member { flex: none; font-size: 11px; font-weight: 600; line-height: 14px; padding: 1px 6px; border-radius: 60px;
+      background: var(--c-sec, rgba(0,0,0,0.05)); color: var(--c-text-faint); text-transform: none; max-width: 96px;
+      overflow: hidden; text-overflow: ellipsis; }
+    .tl-prop-row.selected .tl-prop-member { color: var(--c-text-mut2); }
+    .tl-prop-prop { min-width: 0; overflow: hidden; text-overflow: ellipsis; }
+    .tl-insp-member { display: inline-block; font-size: 11px; font-weight: 600; line-height: 14px; padding: 1px 6px; border-radius: 60px;
+      background: var(--c-sec, rgba(0,0,0,0.05)); color: var(--c-text-faint); text-transform: none; margin-right: 6px; vertical-align: middle; }
     /* 16px left inset of the plot area (kept in sync with ruler/playhead/scrub) */
     .tl-prop-track { position: relative; flex: 1; user-select: none; margin-left: 16px; }
     /* timeline line — capsule (fully rounded), Figma #eeeeef default / #e9e9e9 hover */
@@ -534,6 +555,9 @@
     .tl-menu-help svg { display: block; }
     .tl-menu-check { display: flex; color: var(--c-text-strong); flex: none; }
     .tl-menu-empty { padding: 10px; color: var(--c-disabled); font-size: 13px; }
+    .tl-menu-section { padding: 8px 10px 4px; font-size: 11px; font-weight: 600; line-height: 14px;
+      letter-spacing: 0.02em; text-transform: uppercase; color: var(--c-text-faint); }
+    .tl-menu-section:not(:first-child) { margin-top: 2px; border-top: 1px solid var(--c-border, rgba(0,0,0,0.06)); padding-top: 8px; }
 
     /* ═════ transitions.dev — menu dropdown (verbatim) ═════ */
     .t-dropdown {
@@ -1101,36 +1125,103 @@
       return out;
     }
 
-    // ── registry (per-property overrides) ──
+    // ── registry (per-lane overrides) ──
+    // A "lane" is one animated property of one element. For flat DOM transitions
+    // a lane's id is just the property; for agent-grouped phases it is
+    // `memberId::property`, so two members can each animate e.g. `opacity`.
+    // Selectable items are either flat DOM entries (kind "flat") or one phase of
+    // an agent group (kind "phase"); a phase fans out into per-member lanes.
     class TransitionRegistry {
-      entries=new Map(); listeners=new Set(); propOverrides=new Map(); snapshot=[]; effectiveCache=new Map();
-      register(e){ this.entries.set(e.id,e); this._notify(); }
-      unregister(id){ this.entries.delete(id); this.propOverrides.delete(id); this._notify(); }
-      replaceAll(list){ this.entries.clear(); for(const e of list) this.entries.set(e.id,e); this._notify(); }
+      entries=new Map();        // flat DOM entries by id
+      groups=[];                // agent groups: [{id,label,component,phases:[{id,phase,label,members:[...]}]}]
+      claimedEntryIds=new Set();// flat entries covered by a group member (hidden from "Ungrouped")
+      listeners=new Set(); laneOverrides=new Map(); snapshot=[]; effectiveCache=new Map();
+      register(e){ this.entries.set(e.id,e); this._recomputeClaimed(); this._notify(); }
+      unregister(id){ this.entries.delete(id); this.laneOverrides.delete(id); this._recomputeClaimed(); this._notify(); }
+      replaceAll(list){ this.entries.clear(); for(const e of list) this.entries.set(e.id,e); this._recomputeClaimed(); this._notify(); }
+      setGroups(groups){ this.groups = Array.isArray(groups)?groups:[]; this._recomputeClaimed(); this._notify(); }
+      clearGroups(){ this.groups=[]; this.claimedEntryIds.clear(); this._notify(); }
       get(id){ return this.entries.get(id); }
       getAll(){ return this.snapshot; }
       getEffective(id){ return this.effectiveCache.get(id); }
-      setPropOverride(id, prop, o){
-        const m = this.propOverrides.get(id) || {};
-        m[prop] = { ...m[prop], ...o };
-        this.propOverrides.set(id, m);
+      // overrides are keyed by selectable-item id, then by laneId
+      setPropOverride(id, laneId, o){
+        const m = this.laneOverrides.get(id) || {};
+        m[laneId] = { ...m[laneId], ...o };
+        this.laneOverrides.set(id, m);
         this._notify();
       }
-      clearOverride(id){ this.propOverrides.delete(id); this._notify(); }
-      getPropOverrides(id){ return this.propOverrides.get(id); }
+      clearOverride(id){ this.laneOverrides.delete(id); this._notify(); }
+      getPropOverrides(id){ return this.laneOverrides.get(id); }
       subscribe(fn){ this.listeners.add(fn); return ()=>this.listeners.delete(fn); }
+      // A flat entry is "claimed" when every live element it is bound to is also
+      // matched by some group member's selector, so we don't list it twice.
+      _recomputeClaimed(){
+        this.claimedEntryIds.clear();
+        if(!this.groups.length||typeof document==="undefined")return;
+        const memberEls=new Set();
+        for(const g of this.groups)for(const ph of (g.phases||[]))for(const m of (ph.members||[])){
+          if(!m.selector)continue;
+          let els=[];try{els=Array.from(document.querySelectorAll(m.selector));}catch{}
+          for(const el of els)memberEls.add(el);
+        }
+        if(!memberEls.size)return;
+        for(const[id,entry]of this.entries){
+          const els=((entry.bindings&&entry.bindings.elements)||[]).map(w=>w.deref&&w.deref()).filter(Boolean);
+          if(els.length&&els.every(el=>memberEls.has(el)))this.claimedEntryIds.add(id);
+        }
+      }
+      _baseLanesFlat(entry){
+        const timings=(entry.propertyTimings||entry.properties.map(p=>({property:p,durationMs:entry.durationMs,delayMs:entry.delayMs,easing:entry.easing})));
+        return timings.map(t=>({laneId:t.property,property:t.property,memberId:null,member:null,selector:entry.bindings&&entry.bindings.selector,durationMs:t.durationMs,delayMs:t.delayMs,easing:t.easing,spring:t.spring}));
+      }
+      _baseLanesPhase(phase){
+        const out=[];
+        for(const m of (phase.members||[])){
+          for(const t of (m.propertyTimings||[])){
+            out.push({laneId:m.id+"::"+t.property,property:t.property,memberId:m.id,member:m.label||m.id,selector:m.selector,toState:m.toState,durationMs:t.durationMs,delayMs:t.delayMs,easing:t.easing,spring:t.spring});
+          }
+        }
+        return out;
+      }
+      _applyOverrides(baseLanes,po){
+        return baseLanes.map(t=>{const o=po[t.laneId];return {...t,durationMs:o?.durationMs??t.durationMs,delayMs:o?.delayMs??t.delayMs,easing:o?.easing??t.easing,spring:o?.spring??t.spring};});
+      }
       _notify(){
-        this.snapshot=Array.from(this.entries.values());
         this.effectiveCache.clear();
+        const items=[];
+        // 1) agent groups → one selectable item per phase
+        for(const g of this.groups){
+          for(const ph of (g.phases||[])){
+            const id=ph.id||(g.id+":"+(ph.phase||ph.label||"phase"));
+            const po=this.laneOverrides.get(id)||{};
+            const baseLanes=this._baseLanesPhase(ph);
+            const effTimings=this._applyOverrides(baseLanes,po);
+            const repDur=effTimings.reduce((mx,t)=>Math.max(mx,(t.durationMs||0)+(t.delayMs||0)),0);
+            const members=(ph.members||[]).map(m=>{
+              const mb=baseLanes.filter(l=>l.memberId===m.id);
+              return {memberId:m.id,label:m.label||m.id,selector:m.selector,toState:m.toState,
+                lanes:this._applyOverrides(mb,po),baseLanes:mb};
+            });
+            const item={id,kind:"phase",groupId:g.id,groupLabel:g.label||g.id,component:g.component||null,
+              phase:ph.phase||null,phaseLabel:ph.label||ph.phase||"Phase",
+              label:(g.label||g.id)+" · "+(ph.label||ph.phase||"Phase"),durationMs:repDur,
+              members,effectiveTimings:effTimings,baseLanes};
+            this.effectiveCache.set(id,item);
+            items.push(item);
+          }
+        }
+        // 2) flat DOM entries not claimed by a group → "Ungrouped"
         for(const[id,entry]of this.entries){
-          const po = this.propOverrides.get(id) || {};
-          const timings = (entry.propertyTimings || entry.properties.map(p=>({property:p,durationMs:entry.durationMs,delayMs:entry.delayMs,easing:entry.easing})));
-          const effTimings = timings.map(t => {
-            const o = po[t.property];
-            return { property:t.property, durationMs:o?.durationMs??t.durationMs, delayMs:o?.delayMs??t.delayMs, easing:o?.easing??t.easing, spring:o?.spring??t.spring };
-          });
-          this.effectiveCache.set(id, { ...entry, effectiveTimings: effTimings });
+          if(this.claimedEntryIds.has(id))continue;
+          const po=this.laneOverrides.get(id)||{};
+          const baseLanes=this._baseLanesFlat(entry);
+          const effTimings=this._applyOverrides(baseLanes,po);
+          const item={...entry,kind:"flat",groupId:null,groupLabel:null,effectiveTimings:effTimings,baseLanes};
+          this.effectiveCache.set(id,item);
+          items.push(item);
         }
+        this.snapshot=items;
         for(const fn of this.listeners) fn(this.snapshot);
       }
     }
@@ -1169,6 +1260,109 @@
       // capture phase + the bubbling transitionrun event reaches document
       document.addEventListener("transitionrun",_txOnRun,true);
     }
+    // from/to recovered from a previously observed real run
+    function _txCaptured(el,et){
+      const rec=_txCapture.get(el);if(!rec)return null;
+      const from={},to={};let n=0;
+      for(const t of et){const c=rec.get(t.property);if(c){from[t.property]=c.from;to[t.property]=c.to;n++;}}
+      return n?{from,to}:null;
+    }
+    // Discover the transition's end-state WITHOUT interaction by reading the
+    // stylesheets: find rules that set a transitioning prop and represent a
+    // *state* of the element (a :hover/:focus pseudo, or a toggled class/attr
+    // like `.modal.open`). from = current computed value, to = the rule's value.
+    const _TX_STATE_PSEUDO=/:{1,2}(hover|focus|focus-visible|focus-within|active|checked|enabled|disabled|target|visited|link|valid|invalid|placeholder-shown|default)\b(\([^)]*\))?/g;
+    function _txReduceLast(el,sel){
+      const parts=sel.split(/(\s*[>+~]\s*|\s+)/);
+      let i=parts.length-1;while(i>=0&&/^\s*[>+~]?\s*$/.test(parts[i]))i--;
+      if(i<0)return null;
+      const toks=parts[i].match(/[.#]?[\w-]+|\[[^\]]*\]|::?[\w-]+(?:\([^)]*\))?|\*/g)||[];
+      let dropped=false,hasId=false;
+      const kept=toks.filter(tk=>{
+        if(tk[0]==="."){const ok=el.classList.contains(tk.slice(1));if(ok)hasId=true;else dropped=true;return ok;}
+        if(tk[0]==="["){let ok;try{ok=el.matches(tk);}catch{ok=false;}if(ok)hasId=true;else dropped=true;return ok;}
+        if(tk[0]==="#"){const ok=el.id&&("#"+el.id)===tk;if(ok)hasId=true;else dropped=true;return ok;}
+        if(tk[0]===":"){dropped=true;return false;} // pseudo = the state delta
+        return true; // tag / *
+      });
+      // Only a real *variant of this element*: we must have removed a state token
+      // AND kept a class/id/attr that ties the rule to el. Dropping every class to
+      // land on a bare tag/`*` would falsely match unrelated rules.
+      if(!dropped||!hasId)return null;
+      parts[i]=kept.join("");
+      return parts.join("");
+    }
+    function _txIsStateOf(el,sel){
+      try{if(el.matches(sel))return false;}catch{return false;}
+      const noP=sel.replace(_TX_STATE_PSEUDO,"").trim();
+      if(noP&&noP!==sel){try{if(el.matches(noP))return true;}catch{}}
+      const red=_txReduceLast(el,sel);
+      if(red&&red!==sel){try{if(el.matches(red))return true;}catch{}}
+      return false;
+    }
+    function _txScanRules(rules,el,props,to){
+      for(const rule of rules){
+        // Read style rules directly. NOTE: in browsers with CSS Nesting a plain
+        // CSSStyleRule also has a (usually empty) .cssRules, so test selectorText
+        // first — don't treat every style rule as a grouping rule.
+        const decl=rule.style;
+        if(decl&&rule.selectorText){
+          let sets=false;for(const p of props){if(decl.getPropertyValue(p)){sets=true;break;}}
+          if(sets){
+            for(const sub of rule.selectorText.split(",")){
+              const s=sub.trim();if(!s)continue;
+              if(_txIsStateOf(el,s)){for(const p of props){const v=decl.getPropertyValue(p);if(v&&!(p in to))to[p]=v.trim();}}
+            }
+          }
+        }
+        // Recurse into @media / @supports / @layer and any nested rules.
+        if(rule.cssRules&&rule.cssRules.length){
+          try{if(rule.media&&!window.matchMedia(rule.media.mediaText).matches)continue;}catch{}
+          _txScanRules(rule.cssRules,el,props,to);
+        }
+      }
+    }
+    function _txDiscover(el,et){
+      if(typeof document==="undefined"||!el.matches)return null;
+      const props=et.map(t=>t.property).filter(p=>p&&p!=="all");
+      if(!props.length)return null;
+      const to={};
+      for(const sheet of Array.from(document.styleSheets||[])){
+        let rules;try{rules=sheet.cssRules;}catch{continue;} // cross-origin sheet
+        if(rules)_txScanRules(rules,el,props,to);
+      }
+      const keys=Object.keys(to);if(!keys.length)return null;
+      const cs=getComputedStyle(el);const from={};
+      for(const p of keys)from[p]=cs.getPropertyValue(p)||cs[_txCamel(p)]||"";
+      return {from,to};
+    }
+    // Toggle a phase's state class/attribute (e.g. ".is-open" or "[data-open]")
+    // and read the resulting computed values, so a phase plays its real end-state
+    // even when the source uses a toggled class the DOM isn't currently in.
+    function _txToState(el,et,toState){
+      if(typeof document==="undefined"||!el.matches||!toState)return null;
+      const props=et.map(t=>t.property).filter(p=>p&&p!=="all");
+      if(!props.length)return null;
+      const s=String(toState).trim();
+      let applied=null; // {undo}
+      try{
+        if(s[0]==="."){const c=s.slice(1);if(c&&!el.classList.contains(c)){el.classList.add(c);applied=()=>el.classList.remove(c);}}
+        else if(s[0]==="["){
+          const m=s.match(/^\[\s*([\w-]+)\s*(?:([~|^$*]?=)\s*"?([^"\]]*)"?\s*)?\]$/);
+          if(m){const name=m[1],val=m[3]!=null?m[3]:"";if(el.getAttribute(name)!==val){el.setAttribute(name,val);applied=()=>el.removeAttribute(name);}}
+        }
+      }catch{}
+      if(!applied)return null; // already in that state, or unparseable
+      const cs=getComputedStyle(el);const to={};
+      for(const p of props)to[p]=cs.getPropertyValue(p)||cs[_txCamel(p)]||"";
+      try{applied();}catch{}
+      const cs0=getComputedStyle(el);const from={};
+      for(const p of props)from[p]=cs0.getPropertyValue(p)||cs0[_txCamel(p)]||"";
+      const keys=Object.keys(to).filter(p=>to[p]!=null&&to[p]!==""&&to[p]!==from[p]);
+      if(!keys.length)return null;
+      const f={},t={};for(const p of keys){f[p]=from[p];t[p]=to[p];}
+      return {from:f,to:t};
+    }
 
     class PreviewController {
       state="idle"; listeners=new Set(); cleanups=[]; animations=[]; progressListeners=new Set(); _rafId=null; scanner=null; _gen=0;
@@ -1179,7 +1373,25 @@
       subscribe(fn){this.listeners.add(fn);return()=>this.listeners.delete(fn);}
       onProgress(fn){this.progressListeners.add(fn);return()=>this.progressListeners.delete(fn);}
       play(entry){this.stop();this._gen++;this._current=entry;
-        if(this.scanner)this.scanner.pause();if(entry.bindings.type==="css")this._playCss(entry,this._gen);this._setState("playing");}
+        if(this.scanner)this.scanner.pause();this._playCss(entry,this._gen);this._setState("playing");}
+      // Resolve a selectable item to a flat list of {el, et, toState} arm targets.
+      // Phase items fan out to their members (selector may match several elements,
+      // e.g. staggered items); flat items use their bound DOM elements.
+      _targets(entry){
+        const out=[];
+        if(entry.kind==="phase"){
+          for(const m of (entry.members||[])){
+            if(!m.selector||!m.lanes||!m.lanes.length)continue;
+            let els=[];try{els=Array.from(document.querySelectorAll(m.selector));}catch{}
+            for(const el of els)out.push({el,et:m.lanes,toState:m.toState});
+          }
+          return out;
+        }
+        if(!entry.bindings||entry.bindings.type!=="css")return out;
+        const et=entry.effectiveTimings||entry.properties.map(p=>({property:p,durationMs:entry.durationMs,delayMs:entry.delayMs,easing:entry.easing}));
+        for(const wr of entry.bindings.elements){const el=wr.deref&&wr.deref();if(el)out.push({el,et,toState:null});}
+        return out;
+      }
       pause(){if(this.state!=="playing")return;for(const a of this.animations){try{a.pause();}catch{}}this._stopPL();this._setState("paused");}
       resume(){if(this.state!=="paused")return;for(const a of this.animations){try{a.play();}catch{}}this._startPL();this._setState("playing");}
       stop(){this._stopPL();for(const a of this.animations){try{a.cancel();}catch{}}this.animations=[];for(const c of this.cleanups)c();this.cleanups=[];this._ep(0);if(this.scanner)this.scanner.unpause();this._setState("idle");}
@@ -1188,11 +1400,11 @@
         this.stop();this._gen++;const gen=this._gen;
         this._pendingSeek=seekMs;
         if(this.scanner)this.scanner.pause();
-        if(entry.bindings.type!=="css")return;
+        const targets=this._targets(entry);
+        if(!targets.length)return;
         this.animations=[];
-        const et=entry.effectiveTimings||entry.properties.map(p=>({property:p,durationMs:entry.durationMs,delayMs:entry.delayMs,easing:entry.easing}));
-        for(const wr of entry.bindings.elements){const el=wr.deref();if(!el)continue;
-          const restore=this._arm(el,et);
+        for(const {el,et,toState} of targets){
+          const restore=this._arm(el,et,toState);
           requestAnimationFrame(()=>{if(this._gen!==gen)return;const running=el.getAnimations();
             for(const a of running){a.pause();a.playbackRate=this.rate;this.animations.push(a);}
             const t=this._pendingSeek??seekMs;
@@ -1210,31 +1422,54 @@
         this._pendingSeek=timeMs;
       }
       _finish(){this._stopPL();if(this.animations.length>0){let end=0;for(const a of this.animations){const t=a.effect?.getTiming();const e=(t?.delay??0)+(Number(t?.duration)||0);if(e>end)end=e;}this._ep(end);}this.animations=[];for(const c of this.cleanups)c();this.cleanups=[];if(this.scanner)this.scanner.unpause();this._setState("idle");}
-      // Arm an element so its transition runs now. If we captured the real
-      // transition earlier, replay it from→to (no click, no side effects);
-      // otherwise fall back to clicking the element. Returns a restore fn.
-      _arm(el,et){
+      // Arm an element so its transition runs now, without needing the user to
+      // trigger it first. Priority:
+      //   1. a previously observed real run (exact),
+      //   2. end-state discovered from the stylesheets (hover/focus/toggled class),
+      //   3. a synthetic opacity/transform pulse to preview the timing,
+      //   4. click the element (last resort, may have side effects).
+      // Returns a restore fn.
+      _arm(el,et,toState){
         const saved=el.style.cssText;
         const tv=et.map(t=>`${t.property} ${formatCssTime(t.durationMs)} ${t.easing} ${formatCssTime(t.delayMs)}`).join(", ");
-        const rec=_txCapture.get(el);
-        const caps=rec?et.map(t=>[t.property,rec.get(t.property)]).filter(x=>x[1]):[];
-        if(caps.length){
-          el.style.transition="none";
-          for(const[p,v]of caps)el.style.setProperty(p,v.from);
-          void el.offsetWidth; // commit the from-state before transitioning
-          el.style.transition=tv;
-          for(const[p,v]of caps)el.style.setProperty(p,v.to);
-        }else{
-          el.style.transition=tv;el.click();
+        // toState (a phase's driving class/attr) is the most reliable source of
+        // the real end-state; fall back to a captured run, then CSSOM discovery.
+        const states=(toState&&_txToState(el,et,toState))||_txCaptured(el,et)||_txDiscover(el,et);
+        if(states){
+          const props=et.map(t=>t.property).filter(p=>states.from[p]!=null&&states.to[p]!=null);
+          if(props.length){
+            el.style.transition="none";
+            for(const p of props)el.style.setProperty(p,states.from[p]);
+            void el.offsetWidth; // commit the from-state before transitioning
+            el.style.transition=tv;
+            for(const p of props)el.style.setProperty(p,states.to[p]);
+            return ()=>{try{el.style.cssText=saved;}catch{}};
+          }
         }
+        const synth=et.filter(t=>t.property==="opacity"||t.property==="transform"||t.property==="all");
+        if(synth.length){
+          const dur=Math.max(...et.map(t=>(t.durationMs||0)+(t.delayMs||0)))||et[0].durationMs||300;
+          const ease=et[0].easing||"ease";
+          const hasOp=synth.some(t=>t.property!=="transform"),hasTr=synth.some(t=>t.property!=="opacity");
+          const k0={},k1={},k2={};
+          if(hasOp){k0.opacity=1;k1.opacity=0.35;k2.opacity=1;}
+          if(hasTr){k0.transform="none";k1.transform="translateY(8px)";k2.transform="none";}
+          try{el.animate([k0,k1,k2],{duration:dur,easing:ease,fill:"none"});return ()=>{};}catch{}
+        }
+        el.style.transition=tv;el.click();
         return ()=>{try{el.style.cssText=saved;}catch{}};
       }
-      _playCss(entry,gen){if(entry.bindings.type!=="css")return;this.animations=[];
-        const et = entry.effectiveTimings || entry.properties.map(p=>({property:p,durationMs:entry.durationMs,delayMs:entry.delayMs,easing:entry.easing}));
-        for(const wr of entry.bindings.elements){const el=wr.deref();if(!el)continue;
-          const restore=this._arm(el,et);
+      _playCss(entry,gen){
+        const targets=this._targets(entry);
+        this.animations=[];
+        if(!targets.length){this._finish();return;}
+        let pending=targets.length;
+        for(const {el,et,toState} of targets){
+          const restore=this._arm(el,et,toState);
           requestAnimationFrame(()=>{if(this._gen!==gen)return;const running=el.getAnimations();for(const a of running){a.playbackRate=this.rate;this.animations.push(a);}this._startPL();
-            if(running.length>0){Promise.allSettled(running.map(a=>a.finished)).then(()=>{if(this._gen!==gen||this.state!=="playing")return;if(this.loop&&this._current){this.play(this._current);}else{this._finish();}});}else{this._finish();}});
+            // resolve the whole group when every target's animations have settled
+            const onDone=()=>{if(this._gen!==gen||this.state!=="playing")return;pending--;if(pending>0)return;if(this.loop&&this._current){this.play(this._current);}else{this._finish();}};
+            if(running.length>0){Promise.allSettled(running.map(a=>a.finished)).then(onDone);}else{onDone();}});
           this.cleanups.push(restore);}}
       _startPL(){this._stopPL();const tick=()=>{if(this.animations.length>0){let cur=0;for(const a of this.animations){const c=Number(a.currentTime)||0;if(c>cur)cur=c;}this._ep(cur);}this._rafId=requestAnimationFrame(tick);};this._rafId=requestAnimationFrame(tick);}
       _stopPL(){if(this._rafId!==null){cancelAnimationFrame(this._rafId);this._rafId=null;}}
@@ -1642,10 +1877,46 @@
           h("div",{className:"tl-refine-foot"},foot)));
     }
 
-    function Header({entries,active,onSelect,onReset,onCopy,copied,loop,setLoop,snap,setSnap,onMinimize,onRefine,refineActive}){
+    // Diff the active item's effective (edited/refined) lanes against their
+    // originally-scanned values — the set of changes Accept writes to source.
+    // Each change carries member/selector/phase context so the agent can target
+    // the right state rule (e.g. .is-open vs .is-closing) for a grouped phase.
+    function computeChanges(active){
+      if(!active)return[];
+      const base=active.baseLanes||[];
+      const bmap=new Map(base.map(t=>[t.laneId,t]));
+      const out=[];
+      for(const t of (active.effectiveTimings||[])){
+        const b=bmap.get(t.laneId);if(!b)continue;
+        if(t.durationMs!==b.durationMs||t.delayMs!==b.delayMs||(t.easing||"")!==(b.easing||"")){
+          out.push({property:t.property,member:t.member||null,selector:t.selector||null,
+            from:{durationMs:b.durationMs,delayMs:b.delayMs,easing:b.easing},
+            to:{durationMs:t.durationMs,delayMs:t.delayMs,easing:t.easing}});
+        }
+      }
+      return out;
+    }
+
+    function Header({entries,active,onSelect,onReset,onCopy,copied,loop,setLoop,snap,setSnap,onMinimize,onRefine,refineActive,onAccept,acceptState,acceptDisabled,acceptError,scanning}){
       const[pick,setPick]=useState(false);
       const[setg,setSetg]=useState(false);
       const pickRef=useRef(null), gearRef=useRef(null);
+      // Split selectable items into agent groups (component → phases) and the
+      // flat, ungrouped DOM transitions, preserving order.
+      const groupList=[]; const groupMap=new Map(); const flatItems=[];
+      for(const e of entries){
+        if(e.kind==="phase"){
+          let g=groupMap.get(e.groupId);
+          if(!g){g={id:e.groupId,label:e.groupLabel,phases:[]};groupMap.set(e.groupId,g);groupList.push(g);}
+          g.phases.push(e);
+        }else flatItems.push(e);
+      }
+      const phaseItem=(e)=>h(MenuItem,{key:e.id,active:active&&e.id===active.id,onClick:()=>{onSelect(e.id);setPick(false);},
+        right:active&&e.id===active.id&&h("span",{className:"tl-menu-check"},h(Ic,{name:"check"}))},
+        h("span",null,e.phaseLabel,h("span",{className:"tl-menu-dim"}," "+e.durationMs+"ms")));
+      const flatItem=(e)=>h(MenuItem,{key:e.id,active:active&&e.id===active.id,onClick:()=>{onSelect(e.id);setPick(false);},
+        right:active&&e.id===active.id&&h("span",{className:"tl-menu-check"},h(Ic,{name:"check"}))},
+        h("span",null,e.label,h("span",{className:"tl-menu-dim"}," "+e.durationMs+"ms")));
       return h("div",{className:"tl-header"},
         h("span",{className:"tl-header-label"},"Selected"),
         h("button",{ref:pickRef,className:cx("tl-ghost-btn",pick&&"is-active"),disabled:!active,onClick:()=>setPick(v=>!v)},
@@ -1655,10 +1926,14 @@
         h(Dropdown,{open:pick,onClose:()=>setPick(false),triggerRef:pickRef,width:Math.max(240,(pickRef.current&&pickRef.current.offsetWidth)||240),align:"left"},
           entries.length===0
             ? h("div",{className:"tl-menu-empty"},"No transitions found")
-            : entries.map(e=>h(MenuItem,{key:e.id,active:active&&e.id===active.id,onClick:()=>{onSelect(e.id);setPick(false);},
-                right:active&&e.id===active.id&&h("span",{className:"tl-menu-check"},h(Ic,{name:"check"}))},
-                h("span",null,e.label,h("span",{className:"tl-menu-dim"}," "+e.durationMs+"ms")))) ),
-        h("span",{className:"tl-header-count"},entries.length+" transition"+(entries.length===1?"":"s")+" found"),
+            : h(React.Fragment,null,
+                ...groupList.map(g=>h(React.Fragment,{key:g.id},
+                  h("div",{className:"tl-menu-section"},g.label),
+                  ...g.phases.map(phaseItem))),
+                flatItems.length>0&&groupList.length>0&&h("div",{className:"tl-menu-section"},"Ungrouped"),
+                ...flatItems.map(flatItem))),
+        h("span",{className:"tl-header-count"},
+          scanning?"Grouping…":entries.length+" transition"+(entries.length===1?"":"s")+" found"),
         h("button",{ref:gearRef,className:cx("tl-icon-btn",setg&&"is-active"),title:"Settings",onClick:()=>setSetg(v=>!v)},h(Ic,{name:"gear"})),
         h(Dropdown,{open:setg,onClose:()=>setSetg(false),triggerRef:gearRef,width:210,align:"right"},
           h(MenuItem,{onClick:()=>setLoop(v=>!v),right:loop&&h("span",{className:"tl-menu-check"},h(Ic,{name:"check"}))},"Loop playback"),
@@ -1672,6 +1947,18 @@
               h("span",{className:"t-icon","data-icon":"a"},h(Ic,{name:"copy"})),
               h("span",{className:"t-icon","data-icon":"b"},h(Ic,{name:"check"})))),
           h("span",{className:"t-tt tl-tt-below",role:"tooltip"},copied?"Copied":"Copy values")),
+        h("span",{className:"t-tt-wrap"},
+          h("button",{className:cx("tl-accept-btn",acceptState==="saving"&&"is-saving",acceptState==="done"&&"is-done"),
+            disabled:!active||acceptDisabled||acceptState==="saving"||acceptState==="done",onClick:onAccept,"aria-label":"Accept changes to your code"},
+            acceptState==="saving"
+              ? h("span",{className:"tl-accept-spin","aria-hidden":"true"})
+              : h(Ic,{name:"check"}),
+            h("span",null,acceptState==="done"?"Done":"Accept")),
+          h("span",{className:"t-tt tl-tt-below",role:"tooltip"},
+            acceptState==="error"&&acceptError?acceptError
+              :acceptState==="done"?"Saved to your code"
+              :acceptDisabled?"No changes to save"
+              :"Save changes to your codebase")),
         h("button",{className:cx("tl-refine-btn",refineActive&&"is-active"),disabled:!active,onClick:onRefine},
             h(Ic,{name:"wand"}),
             h("span",{className:"tl-refine-sparks","aria-hidden":"true"},
@@ -1690,7 +1977,7 @@
       );
     }
 
-    function PropTrack({property, delayMs, durationMs, selected, dragging, onSelect, onReorder, onDelayChange, onDurationChange, snap, scaleMs, lockDuration}){
+    function PropTrack({property, member, delayMs, durationMs, selected, dragging, onSelect, onReorder, onDelayChange, onDurationChange, snap, scaleMs, lockDuration}){
       const trackRef=useRef(null);
       const grid = snap ? 25 : 1;
       const pxToMs=useCallback(px=>{if(!trackRef.current)return 0;const w=trackRef.current.getBoundingClientRect().width;return Math.round((px/w)*scaleMs/grid)*grid;},[grid,scaleMs]);
@@ -1720,7 +2007,9 @@
       return h("div",{className:cx("tl-prop-row",selected&&"selected",dragging&&"reordering",lockDuration&&"is-spring"),onClick:onSelect},
         h("div",{className:"tl-prop-head"},
           h("span",{className:"tl-prop-grip",title:"Drag to reorder",onMouseDown:onReorder},h(Ic,{name:"dots"})),
-          h("span",{className:"tl-prop-label"},property)),
+          h("span",{className:"tl-prop-label"},
+            member&&h("span",{className:"tl-prop-member"},member),
+            h("span",{className:"tl-prop-prop"},property))),
         h("div",{className:"tl-prop-track",ref:trackRef},
           h("div",{className:"tl-bar",style:{left:delPct+"%",width:durPct+"%"},onMouseDown:e=>startDrag("move",e),
             title:lockDuration?"Spring duration is derived \u2014 drag to move, resize is locked":undefined},
@@ -2136,44 +2425,44 @@
       return h("div",{className:"tl-scrub-zone",ref:areaRef,onMouseDown:startScrub});
     }
 
-    function Tracks({et, selProp, setSelProp, onPropChange, snap, scaleMs}){
+    function Tracks({et, selLane, setSelLane, onPropChange, snap, scaleMs}){
       const t = usePreviewTime();
       const ratio = Math.min(t / scaleMs, 1);
       const ROW_H = 48;
       const rowsRef = useRef(null);
       const [order, setOrder] = useState([]);
-      const [dragProp, setDragProp] = useState(null);
-      const propKey = et.map(x=>x.property).join("|");
+      const [dragLane, setDragLane] = useState(null);
+      const laneKey = et.map(x=>x.laneId).join("|");
       useEffect(()=>{
-        const props = et.map(x=>x.property);
+        const ids = et.map(x=>x.laneId);
         setOrder(prev=>{
-          const kept = prev.filter(p=>props.includes(p));
-          const added = props.filter(p=>!kept.includes(p));
+          const kept = prev.filter(p=>ids.includes(p));
+          const added = ids.filter(p=>!kept.includes(p));
           return [...kept, ...added];
         });
-      },[propKey]);
-      const orderedRows = order.map(p=>et.find(x=>x.property===p)).filter(Boolean);
-      const startReorder = useCallback((property,e)=>{
+      },[laneKey]);
+      const orderedRows = order.map(p=>et.find(x=>x.laneId===p)).filter(Boolean);
+      const startReorder = useCallback((laneId,e)=>{
         e.preventDefault(); e.stopPropagation();
-        setSelProp(property);
-        setDragProp(property);
+        setSelLane(laneId);
+        setDragLane(laneId);
         const top = rowsRef.current ? rowsRef.current.getBoundingClientRect().top : 0;
         const onMove = e2=>{
           const idx = Math.floor((e2.clientY - top) / ROW_H);
           setOrder(prev=>{
-            const cur = prev.indexOf(property);
+            const cur = prev.indexOf(laneId);
             if(cur<0) return prev;
             const target = Math.max(0, Math.min(prev.length-1, idx));
             if(target===cur) return prev;
             const next = prev.slice();
             next.splice(cur,1);
-            next.splice(target,0,property);
+            next.splice(target,0,laneId);
             return next;
           });
         };
-        const onUp = ()=>{ setDragProp(null); window.removeEventListener("mousemove",onMove); window.removeEventListener("mouseup",onUp); };
+        const onUp = ()=>{ setDragLane(null); window.removeEventListener("mousemove",onMove); window.removeEventListener("mouseup",onUp); };
         window.addEventListener("mousemove",onMove); window.addEventListener("mouseup",onUp);
-      },[setSelProp]);
+      },[setSelLane]);
       const majorStep = scaleMs <= 10000 ? 1000 : scaleMs <= 25000 ? 5000 : 10000;
       const minorStep = majorStep / 4;
       const ruler=[];
@@ -2191,13 +2480,13 @@
           h("div",{className:"tl-ruler"},...ruler)),
         h("div",{className:"tl-rows",ref:rowsRef},
           ...orderedRows.map(row=>h(PropTrack,{
-            key:row.property, property:row.property,
+            key:row.laneId, property:row.property, member:row.member,
             delayMs:row.delayMs, durationMs:row.durationMs, lockDuration:!!row.spring,
-            selected:row.property===selProp, dragging:row.property===dragProp, snap, scaleMs,
-            onSelect:()=>setSelProp(row.property),
-            onReorder:e=>startReorder(row.property,e),
-            onDelayChange:ms=>onPropChange(row.property,{delayMs:ms}),
-            onDurationChange:ms=>onPropChange(row.property,{durationMs:ms}),
+            selected:row.laneId===selLane, dragging:row.laneId===dragLane, snap, scaleMs,
+            onSelect:()=>setSelLane(row.laneId),
+            onReorder:e=>startReorder(row.laneId,e),
+            onDelayChange:ms=>onPropChange(row.laneId,{delayMs:ms}),
+            onDurationChange:ms=>onPropChange(row.laneId,{durationMs:ms}),
           }))),
         h(ScrubZone,{scaleMs}),
         h("div",{className:"tl-playhead-layer"},
@@ -2208,40 +2497,42 @@
       );
     }
 
-    function Inspector({entry, selProp, onPropChange, snap}){
+    function Inspector({entry, selLane, onPropChange, snap}){
       const et = entry.effectiveTimings || [];
-      const sel = et.find(t=>t.property===selProp) || et[0];
+      const sel = et.find(t=>t.laneId===selLane) || et[0];
       if(!sel) return h("div",{className:"tl-inspector"});
       const cubic = easingToCubic(sel.easing);
       const isSpring = !!sel.spring;
       return h("div",{className:"tl-inspector"},
-        h("div",{className:"tl-insp-title"},sel.property),
+        h("div",{className:"tl-insp-title"},
+          sel.member&&h("span",{className:"tl-insp-member"},sel.member),
+          h("span",null,sel.property)),
         h(ValueField,{label:"Duration",value:sel.durationMs,min:0,max:5000,step:25,tokens:DURATION_TOKENS,snap,
           readOnly:isSpring,
           readOnlyHint:"Duration is set by the spring. A spring's settle time is derived from its stiffness, damping and mass \u2014 so it can't be edited directly. Switch to the Easing tab to set a fixed duration.",
-          onChange:v=>onPropChange(sel.property,{durationMs:v})}),
+          onChange:v=>onPropChange(sel.laneId,{durationMs:v})}),
         h(ValueField,{label:"Delay",value:sel.delayMs,min:0,max:5000,step:25,tokens:DELAY_TOKENS,snap,
-          onChange:v=>onPropChange(sel.property,{delayMs:v})}),
-        h(EasingEditor,{easing:sel.easing, cubic, spring:sel.spring, durationMs:sel.durationMs, propKey:sel.property,
-          apply:partial=>onPropChange(sel.property,partial)}),
+          onChange:v=>onPropChange(sel.laneId,{delayMs:v})}),
+        h(EasingEditor,{easing:sel.easing, cubic, spring:sel.spring, durationMs:sel.durationMs, propKey:sel.laneId,
+          apply:partial=>onPropChange(sel.laneId,partial)}),
       );
     }
 
     function Body({entry, onPropChange, state, play, pause, resume, restart, stop, speed, setSpeed, snap}){
       const et = entry.effectiveTimings || [];
-      const [selProp, setSelProp] = useState(et[0]?.property ?? null);
+      const [selLane, setSelLane] = useState(et[0]?.laneId ?? null);
       const [zoom, setZoom] = useState(ZOOM_DEFAULT);
       const scaleMs = scaleFromZoom(zoom);
       useEffect(()=>{
-        if(et.length && !et.find(t=>t.property===selProp)) setSelProp(et[0]?.property);
-      },[et,selProp]);
+        if(et.length && !et.find(t=>t.laneId===selLane)) setSelLane(et[0]?.laneId);
+      },[et,selLane]);
 
       return h("div",{className:"tl-body"},
         h("div",{className:"tl-main"},
           h(Transport,{state,disabled:!entry,onPlay:play,onPause:pause,onResume:resume,onRestart:restart,onStop:stop,speed,setSpeed,zoom,setZoom}),
-          h(Tracks,{et,selProp,setSelProp,onPropChange,snap,scaleMs}),
+          h(Tracks,{et,selLane,setSelLane,onPropChange,snap,scaleMs}),
         ),
-        h(Inspector,{entry,selProp,onPropChange,snap}),
+        h(Inspector,{entry,selLane,onPropChange,snap}),
       );
     }
 
@@ -2295,6 +2586,12 @@
       const[refineSuggestions,setRefineSuggestions]=useState([]);
       const[refineSummary,setRefineSummary]=useState(null);
       const[refineError,setRefineError]=useState(null);
+      // ── accept (write to source) ──
+      const[acceptState,setAcceptState]=useState("idle"); // idle | saving | done | error
+      const[acceptError,setAcceptError]=useState(null);
+      // ── grouped scan (agent reads source → Open/Close phases) ──
+      const[groupScanState,setGroupScanState]=useState("idle"); // idle | scanning | done | error
+      const didGroupScanRef=useRef(false);
       const[refineLabel,setRefineLabel]=useState(null);
       const[appliedIds,setAppliedIds]=useState({});
       const[refineMode,setRefineMode]=useState("llm"); // llm (Agent) | deterministic
@@ -2328,8 +2625,11 @@
         const mode=(refineMode==="llm"&&!avail)?"deterministic":refineMode;
         if(mode!==refineMode)setRefineMode(mode);
         try{
-          const timings=(active.effectiveTimings||[]).map(t=>({property:t.property,durationMs:t.durationMs,delayMs:t.delayMs,easing:t.easing}));
-          const{id}=await relayCreateJob({transitionId:active.id,label:active.label,selector:active.bindings&&active.bindings.selector,timings,mode,refineType});
+          const et=active.effectiveTimings||[];
+          const timings=et.map(t=>({property:t.property,durationMs:t.durationMs,delayMs:t.delayMs,easing:t.easing}));
+          const selector=(active.bindings&&active.bindings.selector)||(et[0]&&et[0].selector)||null;
+          const{id}=await relayCreateJob({transitionId:active.id,label:active.label,selector,
+            phase:active.phase||null,group:active.groupLabel||null,timings,mode,refineType});
           setRefineJobId(id);
         }catch(e){
           setRefinePhase("error");
@@ -2361,9 +2661,15 @@
         if(p.durationMs!=null)o.durationMs=p.durationMs;
         if(p.delayMs!=null)o.delayMs=p.delayMs;
         if(p.easing!=null)o.easing=p.easing;
-        setPropOverride(p.property,o);
+        // map a property patch onto the matching lane(s) — for a grouped phase the
+        // same property can appear on several members, so apply to each.
+        const et=(active&&active.effectiveTimings)||[];
+        let lanes=p.property==="all"?et:et.filter(t=>t.property===p.property);
+        if(p.member)lanes=lanes.filter(t=>(t.member===p.member||t.memberId===p.member));
+        const ids=lanes.length?lanes.map(t=>t.laneId):[p.property];
+        for(const id of ids)setPropOverride(id,o);
         setAppliedIds(prev=>({...prev,[s.id]:true}));
-      },[setPropOverride]);
+      },[setPropOverride,active]);
       const applyAllSuggestions=useCallback(()=>{
         for(const s of refineSuggestions){if(!appliedIds[s.id])applySuggestion(s);}
       },[refineSuggestions,appliedIds,applySuggestion]);
@@ -2385,12 +2691,79 @@
       const copyValues=useCallback(()=>{
         if(!active)return;
         const et=active.effectiveTimings||[];
-        const css=et.map(t=>
-          `${t.property} ${formatCssTime(t.durationMs)} ${t.easing} ${formatCssTime(t.delayMs)}`
-        ).join(",\n       ");
-        navigator.clipboard.writeText("transition: "+css+";").then(()=>{setCopied(true);setTimeout(()=>setCopied(false),1500);});
+        const decl=t=>`${t.property} ${formatCssTime(t.durationMs)} ${t.easing} ${formatCssTime(t.delayMs)}`;
+        let text;
+        if(et.some(t=>t.member)){
+          // grouped phase: one transition block per member, labelled
+          const byMember=new Map();
+          for(const t of et){const k=t.memberId||t.member||"";if(!byMember.has(k))byMember.set(k,{member:t.member,selector:t.selector,lanes:[]});byMember.get(k).lanes.push(t);}
+          text=[...byMember.values()].map(m=>
+            `/* ${m.member||"element"}${m.selector?" — "+m.selector:""} */\ntransition: ${m.lanes.map(decl).join(",\n            ")};`
+          ).join("\n\n");
+        }else{
+          text="transition: "+et.map(decl).join(",\n       ")+";";
+        }
+        navigator.clipboard.writeText(text).then(()=>{setCopied(true);setTimeout(()=>setCopied(false),1500);});
       },[active]);
       const resetOverrides=useCallback(()=>{if(active)registry.clearOverride(active.id);},[registry,active]);
+      // Accept → send an "apply" job so the agent writes the edited timings into
+      // the user's source, then reflect saving / done / error on the button.
+      const onAccept=useCallback(async()=>{
+        const changes=computeChanges(active);
+        if(!active||!changes.length)return;
+        setAcceptState("saving");setAcceptError(null);
+        try{
+          const{id}=await relayCreateJob({kind:"apply",transitionId:active.id,label:active.label,
+            selector:active.bindings&&active.bindings.selector,
+            group:active.groupLabel||null,phase:active.phase||null,component:active.component||null,
+            changes});
+          let settled=false;
+          for(let i=0;i<240&&!settled;i++){
+            await new Promise(r=>setTimeout(r,500));
+            const job=await relayGetJob(id);
+            if(job.status==="done"){settled=true;
+              if(job.result&&job.result.applied===false){
+                setAcceptState("error");setAcceptError((job.result&&job.result.summary)||"The agent couldn't find this transition in your source.");
+              }else{
+                setAcceptState("done");setTimeout(()=>setAcceptState("idle"),2500);
+              }
+            }else if(job.status==="error"){settled=true;setAcceptState("error");setAcceptError(job.error||"The agent reported an error.");}
+          }
+          if(!settled){setAcceptState("error");setAcceptError("Timed out waiting for the agent.");}
+        }catch(e){
+          setAcceptState("error");
+          setAcceptError("Couldn't reach the relay. Run: npx transitions-refine live");
+        }
+      },[active]);
+      // reset Accept feedback when switching transitions
+      useEffect(()=>{setAcceptState("idle");setAcceptError(null);},[active&&active.id]);
+      // Auto-run the grouped scan once, after the flat DOM scan has populated.
+      // The agent reads the source and returns Open/Close phases; if no agent is
+      // live (or the relay is down) we silently keep the flat DOM scan.
+      useEffect(()=>{
+        if(didGroupScanRef.current||!entries.length)return;
+        didGroupScanRef.current=true;
+        let cancelled=false;
+        (async()=>{
+          setGroupScanState("scanning");
+          const flat=registry.getAll().filter(e=>e.kind!=="phase");
+          const raw=flat.map(e=>({label:e.label,selector:e.bindings&&e.bindings.selector,
+            properties:e.properties,
+            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<240&&!cancelled;i++){
+              await new Promise(r=>setTimeout(r,500));
+              const job=await relayGetJob(id);
+              if(cancelled)return;
+              if(job.status==="done"){const groups=(job.result&&job.result.groups)||[];if(groups.length)registry.setGroups(groups);setGroupScanState("done");return;}
+              if(job.status==="error"){setGroupScanState("error");return;}
+            }
+            if(!cancelled)setGroupScanState("error");
+          }catch(e){ if(!cancelled)setGroupScanState("error"); /* relay down → stay flat */ }
+        })();
+        return ()=>{cancelled=true;};
+      },[entries.length,registry]);
 
       // whole-component open/close uses the transitions.dev panel reveal:
       // keep the panel mounted while it animates, flip data-open on the next
@@ -2439,7 +2812,9 @@
           h("div",{className:"tl-panel-body"},
             h("div",{className:"tl-panel-main"},
               h(Header,{entries,active,onSelect:setActiveId,onReset:resetOverrides,onCopy:copyValues,copied,
-                loop,setLoop,snap,setSnap,onMinimize:()=>setMinimized(true),onRefine:openRefine,refineActive:refineOpen}),
+                loop,setLoop,snap,setSnap,onMinimize:()=>setMinimized(true),onRefine:openRefine,refineActive:refineOpen,
+                onAccept,acceptState,acceptDisabled:computeChanges(active).length===0,acceptError,
+                scanning:groupScanState==="scanning"}),
               active
                 ?h(Body,{entry:active,onPropChange:(prop,o)=>setPropOverride(prop,o),
                     state,play,pause,resume,restart,stop,speed,setSpeed,snap})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transitions-refine",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Live, agent-driven Refine panel for CSS/Motion transitions — injects a timeline + Refine UI and runs transitions.dev suggestions via your coding agent.",
   "type": "module",
   "bin": {

package/server/relay.mjs

@@ -140,24 +140,43 @@ function buildPrompt(job) {
   return lines.join("\n");
 }
 
-function parseAgentOutput(stdout) {
+function parseJsonish(stdout) {
   let s = (stdout || "").trim();
   const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/i);
   if (fence) s = fence[1].trim();
-  let obj;
   try {
-    obj = JSON.parse(s);
+    return JSON.parse(s);
   } catch {
     const a = s.indexOf("{");
     const b = s.lastIndexOf("}");
-    if (a >= 0 && b > a) obj = JSON.parse(s.slice(a, b + 1));
-    else throw new Error("agent output was not JSON");
+    if (a >= 0 && b > a) return JSON.parse(s.slice(a, b + 1));
+    throw new Error("agent output was not JSON");
   }
+}
+
+function parseAgentOutput(stdout) {
+  const obj = parseJsonish(stdout);
   if (!obj || !Array.isArray(obj.suggestions)) throw new Error("agent output missing suggestions[]");
   return { suggestions: obj.suggestions, summary: obj.summary ?? null };
 }
 
-function runAgentCmd(cmd, prompt) {
+// Apply jobs ask the agent to edit the user's source, so the result is an
+// outcome, not suggestions.
+function parseApplyOutput(stdout) {
+  const obj = parseJsonish(stdout);
+  if (!obj || typeof obj.applied === "undefined") throw new Error("agent output missing `applied`");
+  return { applied: Boolean(obj.applied), summary: obj.summary ?? null, files: Array.isArray(obj.files) ? obj.files : null };
+}
+
+// Scan jobs ask the agent to read the source and group related transitions into
+// components with open/close phases and member elements.
+function parseScanOutput(stdout) {
+  const obj = parseJsonish(stdout);
+  if (!obj || !Array.isArray(obj.groups)) throw new Error("agent output missing groups[]");
+  return { groups: obj.groups, summary: obj.summary ?? null };
+}
+
+function runAgentCmd(cmd, prompt, parse = parseAgentOutput) {
   return new Promise((resolve, reject) => {
     const child = spawn("sh", ["-c", cmd], { stdio: ["pipe", "pipe", "pipe"] });
     let out = "";
@@ -176,7 +195,7 @@ function runAgentCmd(cmd, prompt) {
       clearTimeout(timer);
       if (code !== 0) return reject(new Error(`agent exited ${code}: ${err.slice(0, 300)}`));
       try {
-        resolve(parseAgentOutput(out));
+        resolve(parse(out));
       } catch (e) {
         reject(new Error(`${e.message} — got: ${out.slice(0, 200)}`));
       }
@@ -186,6 +205,50 @@ function runAgentCmd(cmd, prompt) {
   });
 }
 
+// Prompt for an "apply" job: the agent edits the user's source so the selected
+// transition uses the approved timings.
+function buildApplyPrompt(job) {
+  const r = job.request || {};
+  return [
+    "You are APPLYING an approved transition change to the user's SOURCE CODE. Edit files; do not just suggest.",
+    "",
+    "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.",
+    "",
+    "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.",
+    "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:',
+    '{"applied":true,"summary":"Set .modal transition to 250ms ease-out","files":["src/Modal.css:42"]}',
+    'If you cannot confidently locate the declaration, output {"applied":false,"summary":"<what you looked for and why it was not found>"}.',
+  ].join("\n");
+}
+
+// Prompt for a "scan" job: the agent reads the source and groups the raw,
+// DOM-detected transitions into components with open/close phases and members.
+function buildScanPrompt(job) {
+  const r = job.request || {};
+  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:",
+    JSON.stringify({ url: r.url, raw: r.raw }, null, 2),
+    "",
+    "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.",
+    "3. For each phase, list its MEMBER elements (panel, backdrop, the staggered items…). Give each member a stable `id`, a human `label`, a CSS `selector` that resolves in the live DOM, an optional `toState` hint (the class/attribute that drives that phase, e.g. `.is-open`), and its real `propertyTimings` (durationMs, delayMs, easing per animated property). Quote the real timings from source — never invent.",
+    "",
+    "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","members":[{"id":"panel","label":"Panel","selector":".dropdown-panel","toState":".is-open","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","members":[{"id":"panel","label":"Panel","selector":".dropdown-panel","toState":".is-closing","propertyTimings":[{"property":"opacity","durationMs":150,"delayMs":0,"easing":"ease-in"}]}]}]}]}',
+    "If you cannot confidently group anything, return an empty groups array with a short summary; the panel keeps its flat DOM scan.",
+  ].join("\n");
+}
+
 function refineDeterministic(job) {
   // Whole-transition replacement needs usage inference + recipe selection, which
   // only the agent (LLM) path can do. Deterministic can only snap to tokens.
@@ -207,13 +270,50 @@ function refineDeterministic(job) {
 async function answerJob(job) {
   job.status = "working";
   job.updatedAt = now();
+  const isApply = job.request?.kind === "apply";
+  const isScan = job.request?.kind === "scan";
   const label = job.request?.label || job.request?.selector || "transition";
   // The browser picks the mode per job via the LLM / Deterministic tabs.
   // Default: LLM when a command is configured, otherwise deterministic.
   const mode = job.request?.mode || (AGENT_CMD ? "llm" : "deterministic");
-  job.statusLog.push({ message: `Scanning "${label}"…`, at: now() });
+  job.statusLog.push({
+    message: isApply ? `Writing "${label}" to your code…` : isScan ? "Grouping transitions from your source…" : `Scanning "${label}"…`,
+    at: now(),
+  });
   try {
     let result;
+    if (isApply) {
+      // Editing source can only be done by the agent.
+      if (!AGENT_CMD) {
+        throw new Error(
+          "Saving to your code needs the agent. Run `/refine live` in your editor, " +
+            "or start the relay with REFINE_AGENT_CMD set."
+        );
+      }
+      job.statusLog.push({ message: "Editing source files…", at: now() });
+      result = await runAgentCmd(AGENT_CMD, buildApplyPrompt(job), parseApplyOutput);
+      job.result = { applied: result.applied, summary: result.summary, files: result.files };
+      job.status = "done";
+      job.updatedAt = now();
+      console.log(`  ✓ apply ${job.id.slice(0, 8)} — applied=${result.applied}`);
+      return;
+    }
+    if (isScan) {
+      // Reading source to group transitions can only be done by the agent.
+      if (!AGENT_CMD) {
+        throw new Error(
+          "Grouping transitions needs the agent. Run `/refine live` in your editor, " +
+            "or start the relay with REFINE_AGENT_CMD set."
+        );
+      }
+      job.statusLog.push({ message: "Reading components from source…", at: now() });
+      result = await runAgentCmd(AGENT_CMD, buildScanPrompt(job), parseScanOutput);
+      job.result = { groups: result.groups, summary: result.summary };
+      job.status = "done";
+      job.updatedAt = now();
+      console.log(`  ✓ scan ${job.id.slice(0, 8)} — ${result.groups.length} group(s)`);
+      return;
+    }
     if (mode === "llm") {
       if (!AGENT_CMD) {
         throw new Error(
@@ -313,7 +413,10 @@ const server = createServer(async (req, res) => {
       return send(res, 400, { error: "Body must be { request: {...} }" });
     }
     const job = createJob(body.request);
-    const mode = job.request.mode || (llmAvailable() ? "llm" : "deterministic");
+    // Apply and scan jobs read/edit source — agent only, never deterministic.
+    const mode = (job.request.kind === "apply" || job.request.kind === "scan")
+      ? "llm"
+      : (job.request.mode || (llmAvailable() ? "llm" : "deterministic"));
     job.request.mode = mode;
 
     if (!AUTO) {
@@ -386,9 +489,17 @@ const server = createServer(async (req, res) => {
 
     if (method === "POST" && sub === "result") {
       const body = await readJson(req);
-      const suggestions = body && Array.isArray(body.suggestions) ? body.suggestions : null;
-      if (!suggestions) return send(res, 400, { error: "Body must be { suggestions: [...] }" });
-      job.result = { suggestions, summary: body.summary ?? null };
+      if (body && Array.isArray(body.suggestions)) {
+        job.result = { suggestions: body.suggestions, summary: body.summary ?? null };
+      } else if (body && Array.isArray(body.groups)) {
+        // scan-job result from a `/refine live` agent
+        job.result = { groups: body.groups, summary: body.summary ?? null };
+      } else if (body && typeof body.applied !== "undefined") {
+        // apply-job result from a `/refine live` agent
+        job.result = { applied: Boolean(body.applied), summary: body.summary ?? null, files: Array.isArray(body.files) ? body.files : null };
+      } else {
+        return send(res, 400, { error: "Body must be { suggestions: [...] }, { groups: [...] }, or { applied, summary }" });
+      }
       job.status = "done";
       job.updatedAt = now();
       return send(res, 200, { ok: true });