transitions-refine 0.1.3 → 0.3.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) 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.
+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,10 @@ 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
@@ -176,6 +180,78 @@ 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
@@ -186,10 +262,14 @@ timeline values and wants them written to the codebase. The request looks like:
   "id": "uuid",
   "request": {
     "kind": "apply",
-    "label": "div.modal.t-modal",
-    "selector": "div.modal > button.close",
+    "label": "Dropdown · Close",
+    "selector": ".dropdown-panel",
+    "component": "src/Dropdown.tsx",
+    "group": "Dropdown",
+    "phase": "close",
     "changes": [
-      { "property": "opacity", "from": { "durationMs": 300, "delayMs": 0, "easing": "ease" },
+      { "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)" } }
     ]
   }
@@ -199,15 +279,19 @@ timeline values and wants them written to the codebase. The request looks like:
 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.
+   *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). 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.
+   `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):
 

package/README.md

@@ -4,6 +4,10 @@ A live, agent-driven **Refine** panel for CSS and [Motion](https://motion.dev) t
 
 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.
 
+There's **no play button or scrubber** — the running component *is* the preview. Any edit (a dragged bar, an inspector tweak, or an applied suggestion) is written straight onto the live element as an inline `transition`, so you see it the next time you trigger the transition (open the dropdown, hover the card, …). Reset reverts the element to its source.
+
+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. 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,6 +58,12 @@ 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. Editing any lane applies **live** as an inline `transition` on that member element, so triggering the component yourself (open/close it) previews the whole phase with your values; **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.
@@ -63,7 +73,7 @@ The CLI must have the `transitions-dev` skill available (the prompt tells it to
 
 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.
+Like Replace, Accept needs the agent — run `/refine live` (or `--llm` / `REFINE_AGENT_CMD`). The deterministic answerer can't edit files.
 
 ## Pieces
 
@@ -86,7 +96,7 @@ Like Replace, Accept needs the agent — run `/refine live` (or `--llm` / `REFIN
 | `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` (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}`.
+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`).
 
 Refine suggestions stay as live overrides until you press **Accept**, which is the explicit step that writes them into your source.