transitions-refine 0.1.2 → 0.1.3

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) or Accept button 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, and for "apply" jobs writes the accepted timing changes into the user's source code.
 ---
 
 # Refine Live
@@ -54,6 +54,11 @@ never has to re-run `/refine live`.
      }
      ```
 
+   - **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 +176,53 @@ never has to re-run `/refine live`.
    stop, tell them the LLM tab will go unavailable and how to restart
    (`/refine live`).
 
+## 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": "div.modal.t-modal",
+    "selector": "div.modal > button.close",
+    "changes": [
+      { "property": "opacity", "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. Search by the label/class names and
+   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), and inline
+   `style={{ transition: … }}` objects. Match by the `from` values to disambiguate.
+2. **Edit each change's property** to its `to` values (`durationMs` ms, `easing`,
+   `delayMs` ms). 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,7 @@
 
 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.
 
 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.
 
@@ -59,6 +59,12 @@ The CLI must have the `transitions-dev` skill available (the prompt tells it to
 - **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 +86,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 or `kind: "apply"`), `GET /jobs/:id` (browser). In `REFINE_AUTO=0` mode an external poller also uses `GET /jobs/next` and `POST /jobs/:id/{status,result,error}`.
 
-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;
@@ -1169,6 +1183,82 @@
       // 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};
+    }
 
     class PreviewController {
       state="idle"; listeners=new Set(); cleanups=[]; animations=[]; progressListeners=new Set(); _rafId=null; scanner=null; _gen=0;
@@ -1210,23 +1300,39 @@
         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 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){
         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();
+        const states=_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=[];
@@ -1642,7 +1748,25 @@
           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 transition's effective (edited/refined) timings against its
+    // originally-scanned values — the set of changes Accept writes to source.
+    function computeChanges(active){
+      if(!active)return[];
+      const base=active.propertyTimings||(active.properties||[]).map(p=>({property:p,durationMs:active.durationMs,delayMs:active.delayMs,easing:active.easing}));
+      const bmap=new Map(base.map(t=>[t.property,t]));
+      const out=[];
+      for(const t of (active.effectiveTimings||[])){
+        const b=bmap.get(t.property);if(!b)continue;
+        if(t.durationMs!==b.durationMs||t.delayMs!==b.delayMs||(t.easing||"")!==(b.easing||"")){
+          out.push({property:t.property,
+            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}){
       const[pick,setPick]=useState(false);
       const[setg,setSetg]=useState(false);
       const pickRef=useRef(null), gearRef=useRef(null);
@@ -1672,6 +1796,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"},
@@ -2295,6 +2431,9 @@
       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);
       const[refineLabel,setRefineLabel]=useState(null);
       const[appliedIds,setAppliedIds]=useState({});
       const[refineMode,setRefineMode]=useState("llm"); // llm (Agent) | deterministic
@@ -2391,6 +2530,35 @@
         navigator.clipboard.writeText("transition: "+css+";").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,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]);
 
       // 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 +2607,8 @@
           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}),
               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.1.3",
   "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,35 @@ 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 };
+}
+
+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 +187,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 +197,27 @@ 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, changes: r.changes }, null, 2),
+    "",
+    "Steps:",
+    "1. Find where this transition is defined in the source. Search by the selector/label/class names. Handle plain CSS, CSS Modules, styled-components/emotion template literals, Tailwind utilities/config, and inline style objects — 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. 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");
+}
+
 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 +239,30 @@ function refineDeterministic(job) {
 async function answerJob(job) {
   job.status = "working";
   job.updatedAt = now();
+  const isApply = job.request?.kind === "apply";
   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…` : `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 (mode === "llm") {
       if (!AGENT_CMD) {
         throw new Error(
@@ -313,7 +362,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 jobs edit source — agent only, never deterministic.
+    const mode = job.request.kind === "apply"
+      ? "llm"
+      : (job.request.mode || (llmAvailable() ? "llm" : "deterministic"));
     job.request.mode = mode;
 
     if (!AUTO) {
@@ -386,9 +438,14 @@ 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 && 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: [...] } or { applied, summary }" });
+      }
       job.status = "done";
       job.updatedAt = now();
       return send(res, 200, { ok: true });