retake-dev 0.5.0 → 0.5.1

package/src/server/mcp.js

@@ -8,6 +8,9 @@
 // Finds the dev server from --url / RETAKE_URL, else <cwd or a parent>/.retake/server.json.
 import fs from "node:fs"
 import path from "node:path"
+import { fmt, parseTime, readRecording, report } from "./moments.js"
+import { cleanSource, isCompiled, resolveSource } from "./sourcemap.js"
+import { animFromClip, animationReport, animationSummary, elementBlock, animationBlock, noteText, primaryOf } from "../note-text.js"
 
 const PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"]
 const PKG = JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8"))
@@ -17,7 +20,7 @@ function findServerInfo(from = process.cwd()) {
     const f = path.join(dir, ".retake", "server.json")
     if (fs.existsSync(f)) {
       try {
-        return JSON.parse(fs.readFileSync(f, "utf8"))
+        return { ...JSON.parse(fs.readFileSync(f, "utf8")), root: dir }
       } catch {}
     }
     if (path.dirname(dir) === dir) return null
@@ -26,7 +29,7 @@ function findServerInfo(from = process.cwd()) {
 
 /** @param {{ url?: string | null, token?: string }} [options] */
 export function createClient({ url, token } = {}) {
-  /** @type {{ url: string, token?: string } | null} */
+  /** @type {{ url: string, token?: string, root?: string } | null} */
   let info = null
   const base = () => {
     if (url) return url.replace(/\/$/, "")
@@ -60,7 +63,13 @@ export function createClient({ url, token } = {}) {
   }
   return {
     base,
+    // The project folder (where .retake/ is), to make source paths relative.
+    root: () => {
+      info = info || findServerInfo()
+      return (info && info.root) || process.cwd()
+    },
     session: () => call("GET", "/__retake/session"),
+    recording: (branchId) => call("GET", `/__retake/recording/${encodeURIComponent(branchId)}`),
     notes: () => call("GET", "/__retake/notes"),
     note: (id) => call("GET", `/__retake/notes/${encodeURIComponent(id)}`),
     patch: (id, body) => call("PATCH", `/__retake/notes/${encodeURIComponent(id)}`, body),
@@ -101,11 +110,6 @@ export function createClient({ url, token } = {}) {
 
 // ---- presenting notes -----------------------------------------------------------
 
-const fmt = (ms) => {
-  const s = Math.max(0, Number(ms) || 0) / 1000
-  return `${String(Math.floor(s / 60)).padStart(2, "0")}:${(s % 60).toFixed(2).padStart(5, "0")}`
-}
-
 // Older sessions named timelines "Main" and "Take N"; the dock now shows
 // those defaults as "Timeline N" (migratedName in shell/10-dock.js).
 function withNames(session) {
@@ -124,21 +128,49 @@ function summary(n, session) {
     at: fmt(n.t),
     selector: n.selector || (n.el && n.el.selector) || null,
     component: n.component || (n.el && n.el.components && n.el.components[0]) || null,
-    source: n.source ? `${n.source.file}${n.source.line ? ":" + n.source.line : ""}` : null,
+    source: n.source ? (unmapped(n.source) ? "unknown (compiled bundle; get_note tries its source map)" : `${n.source.file}${n.source.line ? ":" + n.source.line : ""}`) : null,
+    ...(n.range ? { range: `${fmt(n.range.from)} → ${fmt(n.range.to)}` } : {}),
+    ...(animationSummary(n) ? { animation: animationSummary(n) } : {}),
     replies: (n.replies || []).length,
   }
 }
 
-function clipText(c) {
+// A source that is only a compiled bundle's line (no source map read yet).
+const unmapped = (src) => !!src && !!(src.compiled || isCompiled(src.file))
+
+function clipText(c, t) {
   const name = c.label ? `${c.label} ` : ""
   const at = `${Math.round(Number(c.offset) || 0)}ms into`
-  return Number(c.duration) > 0 ? `${at} a ${Math.round(c.duration)}ms ${name}animation (clip ${c.id})` : `${at} a running ${name}animation (clip ${c.id})`
+  const start = c.start != null ? c.start : t - (Number(c.offset) || 0)
+  const end = c.end !== undefined ? c.end : Number(c.duration) > 0 ? start + Number(c.duration) : null
+  const span = `; it runs ${fmt(start)} → ${end != null ? fmt(end) : "still running"}`
+  return Number(c.duration) > 0 ? `${at} a ${Math.round(c.duration)}ms ${name}animation (clip ${c.id}${span})` : `${at} a running ${name}animation (clip ${c.id}${span})`
+}
+
+// Where the element was written, as one line: the note's own source, the
+// original file:line behind a compiled bundle's (see resolveSourceOf), or why
+// it isn't known.
+function sourceLine(n, resolved) {
+  const src = n.source
+  if (!src) return null
+  if (resolved && resolved.file) return `Source: ${resolved.file}${resolved.line ? ":" + resolved.line : ""} (through the source map of the bundle it was served in)`
+  if (unmapped(src)) {
+    const by = [n.component || (n.el && n.el.components && n.el.components[0]), n.selector || (n.el && n.el.selector)].filter(Boolean)
+    return `Source: not known. The note only has a line of a compiled bundle${resolved && resolved.library ? ", which maps into library code" : ", with no source map to read it by"}; find the element by ${by.length > 1 ? `its component (${by[0]}) and selector` : by.length ? by[0] : "its selector"} instead.`
+  }
+  return `Source: ${src.file}${src.line ? ":" + src.line : ""}`
 }
 
-// Everything an agent needs to act on one note, as readable text.
-function describe(n, session) {
+// Everything an agent needs to act on one note, as readable text. A note
+// that says which animations it is about (anims, from the dock) is written by
+// the same formatter as the dock's Copy for agent (src/note-text.js).
+function describe(n, session, resolved = null) {
   const b = (session.branches || []).find((x) => String(x.id) === String(n.branchId))
   const parent = b && (session.branches || []).find((x) => String(x.id) === String(b.parentId))
+  if (Array.isArray(n.anims)) {
+    const text = noteText(n, { start: 0, timeline: b ? b.name : String(n.branchId), parent: parent ? parent.name : null, forkAt: parent ? b.forkAt : null, sourceLine: sourceLine(n, resolved) || undefined, status: true })
+    return `${text}\n\nThe note is pinned to ${fmt(n.range ? n.range.from : n.t)} in the recording of that timeline. get_moment with id "${n.id}" shows what happened around it; get_animation with id "${n.id}" maps any recording time onto the animation's own clock.`
+  }
   const el = n.el || {}
   const lines = [
     `Note ${n.id} (${n.status || "pending"}) on timeline "${b ? b.name : n.branchId}" at ${fmt(n.t)}`,
@@ -149,11 +181,13 @@ function describe(n, session) {
     `Element: ${el.label || ""}${el.text ? ` "${el.text}"` : ""}`.trim(),
     `Selector: ${n.selector || el.selector || "?"}`,
     n.component || (el.components && el.components.length) ? `Component: ${n.component || el.components.join(" < ")}` : null,
-    n.source ? `Source: ${n.source.file}${n.source.line ? ":" + n.source.line : ""}` : null,
+    sourceLine(n, resolved),
     n.classes && n.classes.length ? `Classes: ${[].concat(n.classes).join(" ")}` : null,
     n.rect ? `Box: ${Math.round(n.rect.w)}×${Math.round(n.rect.h)} at (${Math.round(n.rect.x)}, ${Math.round(n.rect.y)})` : null,
-    n.clip ? `During an animation: ${clipText(n.clip)}` : null,
+    n.clip ? `During an animation: ${clipText(n.clip, n.t)}` : null,
     el.page ? `Page: ${el.page}` : null,
+    "",
+    `The note is pinned to ${fmt(n.t)} in the recording of that timeline: the user means what was on screen then. get_moment with id "${n.id}" shows what happened around it (actions, animations on this element with their start and end, requests); check it before asking the user about timing.`,
   ]
   if ((n.replies || []).length) {
     lines.push("", "Conversation:")
@@ -175,6 +209,52 @@ const TOOLS = [
     description: "Everything about one note: what the user asked, the element (selector, React component, source file:line, classes, size), the moment and timeline, and the conversation so far.",
     inputSchema: { type: "object", properties: { id: { type: ["string", "number"] } }, required: ["id"] },
   },
+  {
+    name: "get_moment",
+    description:
+      "What happened in the recording around a note's moment (or any moment of a timeline): the user's actions, route changes and requests with their times, the animations on or near the noted element (start, end, duration, what they animate between, how far along at the moment), other animations, and when the screen changed most. Use it before asking the user about timing: a note is pinned to a moment, and the answer is usually in the recording.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: ["string", "number"], description: "A note id: the moment, timeline and element come from the note" },
+        timeline: { type: ["string", "number"], description: "Without a note: a timeline's name or id (default: the active one)" },
+        at: { type: ["string", "number"], description: "Without a note: the moment, as the dock shows it (00:10.91)" },
+        selector: { type: "string", description: "Without a note: an element to focus on" },
+        before_seconds: { type: "number", description: "How far back to look (default 5)" },
+        after_seconds: { type: "number", description: "How far ahead to look (default 5)" },
+      },
+    },
+  },
+  {
+    name: "get_animation",
+    description:
+      "One animation in detail: what it is and where it is defined, what started it, its timing (delay, duration, iterations, easing) and every keyframe, and recording times mapped onto its own clock (local ms after its delay, progress, eased progress, the keyframe segment) with the conversion to CSS %, Motion `times` and GSAP seconds. Values and boxes are included where the note sampled them. Give a note id (its primary animation, or `clip` to pick another of its animations), or a timeline and a clip id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: ["string", "number"], description: "A note id: its primary animation and its moment or range" },
+        clip: { type: "string", description: "A clip id (from get_moment / get_timeline_events / the note)" },
+        timeline: { type: ["string", "number"], description: "Without a note: a timeline's name or id (default: the active one)" },
+        at: { type: ["string", "number"], description: "A recording time to map (00:01.20)" },
+        from: { type: ["string", "number"], description: "Start of a range to map" },
+        to: { type: ["string", "number"], description: "End of a range to map" },
+      },
+    },
+  },
+  {
+    name: "get_timeline_events",
+    description: "Everything recorded on a timeline between two times: the user's actions, routes, page loads, requests, animations (optionally around one element) and screen changes, in order. Times as the dock shows them (00:10.91).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        timeline: { type: ["string", "number"], description: "A timeline's name or id (default: the active one)" },
+        from: { type: ["string", "number"], description: "Start of the window (default: the start)" },
+        to: { type: ["string", "number"], description: "End of the window (default: the end)" },
+        selector: { type: "string", description: "Focus on the animations on or near this element" },
+        limit: { type: "number", description: "Most events to list (default 60, max 200)" },
+      },
+    },
+  },
   {
     name: "get_active_timeline",
     description: "Which timeline the user is looking at in the Retake dock, how it relates to the others (branch point, code version) and its open notes.",
@@ -202,6 +282,30 @@ const TOOLS = [
   },
 ]
 
+// The guide every coding agent gets at initialize (also in skills/retake-notes).
+const INSTRUCTIONS = `Notes are change requests the user left on elements of their app in the Retake timeline, each pinned to a moment (or a range) of a recording of the running app. list_notes, then get_note for details; get_moment shows what happened around a note's moment (actions, animations on the element, requests), so check it before asking the user about timing. acknowledge when you start, resolve with a summary when done.
+
+Animations. A note on an animated element names the animation (its kind, where it is defined, its timing and every keyframe) and the exact point or range the user meant on that animation's own clock: local ms after its delay, progress (local / duration), eased progress (after the effect's easing; keyframe offsets apply to this), and the keyframe segment it falls in, with the computed values and the element's box there and one frame either side. Numbers the user typed ("at 100ms", "200-400 ms") are local time of that animation unless the note says otherwise. Change only what the note scopes: keep the values at every other point and the total duration.
+Most notes end with an "Exact edit": the animation's keyframes again on plain time, with the note's point or range edges as keyframes of their own and the matching part of each curve on both sides. Put it in place of the original (it moves exactly as before), then change only the marked part. If it says the @keyframes is shared, it gives this element its own copy; keep that unless the user meant every element.
+- CSS @keyframes: add stops at the range edges as % (local / duration) with the edge values given, so the rest doesn't move; change only what is between them. animation-timing-function inside a keyframe applies to the segment after it (default ease). A hold = two stops with the same value. If the duration changes, recompute every %. If the selector matches several elements, scope the change unless all were meant.
+- CSS transition: one segment only. For a hold, a two-step motion or a sub-range, use linear(...) stops or a cubic-bezier, or replace it with a keyframes animation started by the same trigger (given).
+- WAAPI (element.animate): add { offset, ...values, easing } at the edges. With an effect-level easing, offsets apply after it: set the effect easing to linear and move easing onto each keyframe first.
+- Motion: values are arrays with times (0-1 of the duration, delay excluded) and an ease array (one per segment); insert entries at local / duration. A spring has no ms range: convert it to keyframes + times, or tune stiffness/damping/bounce.
+- GSAP: retime with the position parameter ("<", "-=0.4", seconds); change part of a tween by splitting it into two .to() calls at the edge values.
+- Script-driven (inline style writes): edit the code at the given location and gate the change on the same elapsed time, or move it into keyframes.
+- SVG stroke draw: the dash offset is linear in progress; "pause halfway" = two equal stops around 50%.
+- Scroll-driven: the axis is scroll progress, not time; edit the keyframe % or animation-range. For JS parallax, clamp to a scroll range instead of changing the factor.
+- canvas / WebGL: Retake can't see inside; edit the per-frame code, gated on the same elapsed time.
+get_animation maps any recording time onto an animation's clock and into CSS %, Motion times and GSAP seconds. After editing, check the values at the range edges and one frame either side against the note's.`
+
+// For get_moment on a note: which recorded clips the note says are its element's.
+function knownOf(note) {
+  const rel = new Map()
+  for (const a of note.anims || []) if (a.id) rel.set(String(a.id), a.relation === "on" ? "on" : a.relation || "on")
+  for (const c of note.inside || []) if (c.id && !rel.has(String(c.id))) rel.set(String(c.id), "inside")
+  return { rel, running: (note.anims || []).map((a) => a.name || a.kind) }
+}
+
 const isOpen = (n) => !n.status || n.status === "pending" || n.status === "acknowledged"
 
 export function createTools(client) {
@@ -213,6 +317,34 @@ export function createTools(client) {
     })
     return note
   }
+  // A timeline by name or id (default: the active one) and its recording.
+  const timelineOf = (session, which) => {
+    const branches = session.branches || []
+    const b = which == null || which === "" ? branches.find((x) => String(x.id) === String(session.activeId)) || branches[0] : branches.find((x) => String(x.id) === String(which)) || branches.find((x) => String(x.name).toLowerCase() === String(which).toLowerCase())
+    if (!b) throw new Error(which == null ? "no timelines yet: record something in the dock first" : `no timeline "${which}"; get_active_timeline lists them`)
+    return b
+  }
+  const recordingOf = async (b) => {
+    const json = await client.recording(b.id).catch((err) => {
+      if (/→ 404/.test(err.message)) throw new Error(`timeline "${b.name}" has no saved recording yet (the dock saves it when paused); ask the user to pause, then try again`)
+      throw err
+    })
+    return readRecording(json)
+  }
+  const resolved = new Map()
+  const resolveSourceOf = async (n) => {
+    const src = n.source
+    if (!src || !unmapped(src)) return null
+    const key = `${src.file}:${src.line}:${src.col || ""}`
+    if (!resolved.has(key)) resolved.set(key, resolveSource(src, { base: client.base(), root: client.root() }).catch(() => null))
+    return resolved.get(key)
+  }
+  // An absolute source path inside the project reads better relative to it.
+  const relSource = (n) => {
+    if (!n.source || !n.source.file || !String(n.source.file).startsWith("/")) return n
+    const file = cleanSource(n.source.file, { root: client.root() })
+    return file === n.source.file ? n : { ...n, source: { ...n.source, file } }
+  }
   const handlers = {
     async list_notes({ status = "open" } = {}) {
       const session = await readSession()
@@ -221,7 +353,71 @@ export function createTools(client) {
     },
     async get_note({ id }) {
       const [session, note] = await Promise.all([readSession(), byId(id)])
-      return describe(note, session)
+      return describe(relSource(note), session, await resolveSourceOf(note))
+    },
+    async get_moment(/** @type {any} */ { id, timeline, at, selector, before_seconds = 5, after_seconds = 5 } = {}) {
+      const session = await readSession()
+      const before = Math.min(Math.max(Number(before_seconds) || 0, 0), 120) * 1000
+      const after = Math.min(Math.max(Number(after_seconds) || 0, 0), 120) * 1000
+      if (id != null && id !== "") {
+        const note = await byId(id)
+        const b = timelineOf(session, note.branchId)
+        const rec = await recordingOf(b)
+        const sel = note.selector || (note.el && note.el.selector) || null
+        const component = note.component || (note.el && note.el.components && note.el.components[0]) || null
+        const title = `Timeline "${b.name}" around note ${note.id} ("${note.text}") on ${sel || "an element"}:`
+        if (!Array.isArray(note.anims)) return report(rec, { at: note.t, from: note.t - before, to: note.t + after, selector: sel, component, title })
+        // The note knows which animations are its element's (by their recorded
+        // path): the element section and the verdict come from it, so this and
+        // get_note can't disagree.
+        const t0 = note.range ? note.range.from : note.t
+        const t1 = note.range ? note.range.to : note.t
+        const ctx = { start: rec.start || 0 }
+        const head = [...elementBlock(note, ctx), "", ...animationBlock(note, ctx)].join("\n")
+        const ctxReport = report(rec, { at: note.t, from: t0 - before, to: t1 + after, selector: sel, component, title, known: knownOf(note) })
+        return `Note ${note.id}'s element:\n${head}\n\n${ctxReport}`
+      }
+      if (at == null || at === "") throw new Error("get_moment needs a note id, or a timeline moment (at, like 00:10.91)")
+      const b = timelineOf(session, timeline)
+      const rec = await recordingOf(b)
+      const t = parseTime(at) + (rec.start || 0)
+      return report(rec, { at: t, from: t - before, to: t + after, selector: selector || null, title: `Timeline "${b.name}" around ${fmt(t - (rec.start || 0))}:` })
+    },
+    async get_animation(/** @type {any} */ { id, clip, timeline, at, from, to } = {}) {
+      const session = await readSession()
+      const times = (rec) => [at, from, to].filter((v) => v != null && v !== "").map((v) => parseTime(v) + (rec.start || 0))
+      if (id != null && id !== "") {
+        const note = await byId(id)
+        const anims = note.anims || []
+        let a = clip ? anims.find((x) => String(x.id) === String(clip)) : primaryOf(note)
+        const b = timelineOf(session, note.branchId)
+        const rec = await recordingOf(b).catch(() => null)
+        if (!a && rec) {
+          const c = (rec.clips || []).find((x) => String(x.id) === String(clip || (note.clip && note.clip.id)))
+          if (c) a = animFromClip(c)
+        }
+        if (!a) return `Note ${note.id} has no animation${anims.length ? ` with clip id ${clip}` : ""}: nothing animated on its element at its moment. get_moment with id "${note.id}" lists what animated nearby.`
+        const sampled = [a.at, a.from, a.to, ...(a.samples || [])].filter(Boolean)
+        const Ts = rec && times(rec).length ? times(rec) : sampled.length ? [...new Set([a.at, a.from, a.to].filter(Boolean).map((p) => p.T))] : []
+        return `Animation of note ${note.id} on ${note.selector || (note.el && note.el.selector) || "its element"}:\n${animationReport(a, Ts, { start: rec ? rec.start || 0 : 0, sampled })}`
+      }
+      if (!clip) throw new Error("get_animation needs a note id, or a clip id (with a timeline)")
+      const b = timelineOf(session, timeline)
+      const rec = await recordingOf(b)
+      const c = (rec.clips || []).find((x) => String(x.id) === String(clip))
+      if (!c) throw new Error(`no clip ${clip} on timeline "${b.name}"; get_timeline_events lists them`)
+      return `Timeline "${b.name}", clip ${c.id} on ${c.selector || "?"}:\n${animationReport(animFromClip(c), times(rec), { start: rec.start || 0 })}`
+    },
+    async get_timeline_events(/** @type {any} */ { timeline, from, to, selector, limit = 60 } = {}) {
+      const session = await readSession()
+      const b = timelineOf(session, timeline)
+      const rec = await recordingOf(b)
+      const s = rec.start || 0
+      const lo = from == null || from === "" ? null : parseTime(from) + s
+      const hi = to == null || to === "" ? null : parseTime(to) + s
+      if (lo != null && hi != null && hi < lo) throw new Error("`to` is before `from`")
+      const n = Math.min(Math.max(Number(limit) || 60, 1), 200)
+      return report(rec, { from: lo, to: hi, selector: selector || null, limit: n, title: `Timeline "${b.name}":` })
     },
     async get_active_timeline() {
       const session = await readSession()
@@ -286,7 +482,8 @@ export async function runMcp({ url } = {}) {
         protocolVersion: PROTOCOLS.includes(asked) ? asked : PROTOCOLS[0],
         capabilities: { tools: { listChanged: false } },
         serverInfo: { name: "retake", version: PKG.version },
-        instructions: "Notes are change requests the user left on elements of their prototype in the Retake timeline. list_notes, then get_note for details; acknowledge when you start, resolve with a summary when done.",
+        instructions:
+          INSTRUCTIONS,
       })
     }
     if (method === "notifications/initialized" || (method && method.startsWith("notifications/"))) return

package/src/server/moments.js

@@ -0,0 +1,317 @@
+// What happened over time in a stored recording (.retake/recordings), as
+// short readable text for `retake mcp`: the user's actions, animations on or
+// near an element (with what they animate between), requests, page loads and
+// how much of the screen changed, around a moment or over a window. Times
+// read like the dock's (00:10.91, from the recording's start).
+// The recording's format is the runtime's (src/runtime/30-recorder.js).
+
+/** ms → "00:10.91" */
+export const fmt = (ms) => {
+  const s = Math.max(0, Number(ms) || 0) / 1000
+  return `${String(Math.floor(s / 60)).padStart(2, "0")}:${(s % 60).toFixed(2).padStart(5, "0")}`
+}
+/** ms → "0.21s" / "1.20s" / "350ms" */
+const dur = (ms) => (Math.abs(ms) < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(2)}s`)
+
+/** "00:10.91", "10.91", "10.91s", "1:02.5", "350ms" or a number of ms → ms. */
+export function parseTime(v) {
+  if (v == null || v === "") return null
+  if (typeof v === "number") return v
+  const s = String(v).trim()
+  let m
+  if ((m = /^(\d+):(\d+(?:\.\d+)?)$/.exec(s))) return (Number(m[1]) * 60 + Number(m[2])) * 1000
+  if ((m = /^(\d+(?:\.\d+)?)\s*ms$/.exec(s))) return Number(m[1])
+  if ((m = /^(\d+(?:\.\d+)?)\s*s?$/.exec(s))) return Number(m[1]) * 1000
+  throw new Error(`can't read the time "${v}"; use the dock's format, like 00:10.91`)
+}
+
+/** A recording as the server keeps it (v1, or packed v2/v3) → plain v1 form. */
+export function readRecording(json) {
+  const o = typeof json === "string" ? JSON.parse(json) : { ...json }
+  if (!o || typeof o !== "object") return null
+  if (o.v === 2 && o.paths) {
+    const P = o.paths
+    o.events = (o.events || []).map((ev) => {
+      const out = { ...ev }
+      if ("p" in out) (out.path = P[out.p]), delete out.p
+      if ("rp" in out) (out.related = P[out.rp]), delete out.rp
+      return out
+    })
+  } else if (o.v === 3) {
+    const P = o.paths || []
+    const S = o.strs || []
+    const frames = o.frames || []
+    let lastF = 0
+    o.events = (o.events || []).map((ev) => {
+      const out = { ...ev }
+      out.type = S[out.y]
+      delete out.y
+      if ("p" in out) (out.path = P[out.p]), delete out.p
+      if ("rp" in out) (out.related = P[out.rp]), delete out.rp
+      if ("c" in out) (out.css = S[out.c]), delete out.c
+      if ("f" in out) {
+        lastF += out.f
+        out.t = frames[lastF]
+        delete out.f
+      }
+      return out
+    })
+    o.clips = (o.clips || []).map((c) => {
+      const out = { ...c }
+      if ("s" in out) (out.selector = S[out.s]), delete out.s
+      if ("co" in out) (out.component = S[out.co]), delete out.co
+      if ("l" in out) (out.label = S[out.l]), delete out.l
+      if ("p" in out) (out.path = P[out.p]), delete out.p
+      return out
+    })
+  }
+  delete o.paths
+  delete o.strs
+  o.v = 1
+  o.events = o.events || []
+  o.clips = o.clips || []
+  return o
+}
+
+// ---- elements --------------------------------------------------------------------------
+// Clip selectors and note selectors are built the same way (an id, else
+// tag.class chains with :nth-of-type), but classes change over time
+// (".off" → ".on"), so they're also compared without classes.
+const bare = (sel) => String(sel || "").replace(/::?(before|after|marker|placeholder|backdrop)$/, "").replace(/\.[\w-]+(?:\\.[\w-]*)*/g, "")
+const under = (a, b) => a.startsWith(b + " > ") // a is inside b
+/** How a clip's element relates to the noted one: "on" | "inside" | "around" | null. */
+export function relation(clipSel, noteSel) {
+  if (!clipSel || !noteSel) return null
+  const c = String(clipSel).replace(/::?(before|after|marker|placeholder|backdrop)$/, "")
+  const n = String(noteSel)
+  if (c === n || bare(c) === bare(n)) return "on"
+  if (under(c, n) || under(bare(c), bare(n))) return "inside"
+  if (under(n, c) || under(bare(n), bare(c))) {
+    const depth = bare(n).slice(bare(c).length).split(" > ").length - 1
+    return depth <= 4 ? "around" : null
+  }
+  return null
+}
+
+// ---- what happened -------------------------------------------------------------------
+const SECRET = /pass|pwd|secret|token|card|cvv|cvc|ssn|otp/i
+const MODS = ["ctrlKey", "metaKey", "altKey", "shiftKey"]
+const NAMED_KEYS = /^(Enter|Escape|Tab|Backspace|Delete|ArrowUp|ArrowDown|ArrowLeft|ArrowRight|Home|End|PageUp|PageDown| )$/
+const quote = (s, n = 40) => {
+  const t = String(s ?? "").replace(/\s+/g, " ").trim()
+  return `"${t.length > n ? t.slice(0, n - 1) + "…" : t}"`
+}
+const pathOfUrl = (u) => {
+  try {
+    const x = new URL(u)
+    x.searchParams.delete("__wb")
+    return x.pathname + x.search + x.hash
+  } catch {
+    return String(u || "")
+  }
+}
+
+/** The user's actions, routes, page loads and requests, as [{ t, end?, kind, text, selector? }]. */
+export function happenings(rec) {
+  const out = []
+  const start = rec.start || 0
+  /** @type {any} */
+  let burst = null
+  /** @type {any} */
+  let keys = null
+  /** @type {any} */
+  let scroll = null
+  for (const ev of rec.events) {
+    if (ev.t == null || ev.t < start) continue
+    if (ev.type === "click") {
+      const prev = out[out.length - 1]
+      if (prev && prev.kind === "focus" && prev.selector === ev.css && ev.t - prev.t < 1000) out.pop()
+      out.push({ t: ev.t, kind: "click", text: `click ${ev.label ? quote(ev.label) + " " : ""}(${ev.css || "?"})`, selector: ev.css })
+    } else if (ev.type === "submit") out.push({ t: ev.t, kind: "submit", text: `submit ${ev.css || "a form"}`, selector: ev.css })
+    else if (ev.type === "focusin" && ev.editable) {
+      const prev = out[out.length - 1]
+      if (!(prev && prev.kind === "click" && prev.selector === ev.css && ev.t - prev.t < 50)) out.push({ t: ev.t, kind: "focus", text: `focus ${ev.label ? quote(ev.label) + " " : ""}(${ev.css || "a field"})`, selector: ev.css })
+    } else if (ev.type === "input") {
+      const typed = /^insert/.test(ev.inputType || "insertText") ? (ev.data ? ev.data.length : 1) : 0
+      const hide = SECRET.test(`${ev.css || ""} ${ev.label || ""}`)
+      if (burst && burst.selector === ev.css && ev.t - burst.end < 800) {
+        burst.end = ev.t
+        burst.chars += typed
+      } else {
+        burst = { t: ev.t, end: ev.t, kind: "type", chars: typed, selector: ev.css, hide }
+        out.push(burst)
+      }
+      burst.value = ev.value
+    } else if (ev.type === "change" && (ev.checked != null || /select/i.test(ev.css || ""))) {
+      const text = ev.checked != null ? `${ev.checked ? "checked" : "unchecked"} ${ev.css || "a box"}` : `chose ${quote(ev.value)} in ${ev.css}`
+      out.push({ t: ev.t, kind: "change", text, selector: ev.css })
+    } else if (ev.type === "keydown" && !ev.inField && ev.key && (NAMED_KEYS.test(ev.key) || MODS.some((m) => ev[m]))) {
+      if (/^(Control|Meta|Alt|Shift)$/.test(ev.key)) continue
+      const name = [...MODS.filter((m) => ev[m]).map((m) => ({ ctrlKey: "Ctrl", metaKey: "⌘", altKey: "Alt", shiftKey: "Shift" })[m]), ev.key === " " ? "Space" : ev.key].join("+")
+      if (keys && keys.name === name && ev.t - keys.end < 1000) {
+        keys.end = ev.t
+        keys.n++
+      } else out.push((keys = { t: ev.t, end: ev.t, kind: "key", name, n: 1 }))
+    } else if (ev.type === "nav") out.push({ t: ev.t, kind: "nav", text: `back/forward to ${pathOfUrl(ev.url)}` })
+    else if (ev.type === "scroll") {
+      const where = ev.path === "d" ? "the page" : "an element"
+      if (scroll && scroll.where === where && ev.t - scroll.end < 600) {
+        scroll.end = ev.t
+        scroll.top = ev.top
+      } else out.push((scroll = { t: ev.t, end: ev.t, kind: "scroll", where, top: ev.top }))
+    }
+  }
+  for (const h of out) {
+    if (h.kind === "type") {
+      h.text = `typed ${h.chars} char${h.chars === 1 ? "" : "s"} in ${h.selector || "a field"}${h.hide || h.value == null || /</.test(h.value) ? "" : ` (now ${quote(h.value)})`}`
+      delete h.value
+    } else if (h.kind === "key") h.text = `key ${h.name}${h.n > 1 ? ` ×${h.n}` : ""}`
+    else if (h.kind === "scroll") h.text = `scrolled ${h.where} to ${Math.round(h.top || 0)}px`
+    if (h.end === h.t) delete h.end
+  }
+  for (const r of rec.routes || []) if (r.t >= start && r.t > 0) out.push({ t: r.t, kind: "route", text: `route → ${r.path}` })
+  for (const s of rec.segments || []) out.push({ t: s.t, kind: "load", text: `page loaded: ${pathOfUrl(s.url)}` })
+  out.push(...requests(rec))
+  // At the same moment, what the user did comes before what it set off.
+  const rank = (h) => (h.kind === "request" ? 2 : h.kind === "route" || h.kind === "load" ? 1 : 0)
+  return out.sort((a, b) => a.t - b.t || rank(a) - rank(b))
+}
+
+// Recorded requests: when they went out, when they finished, how they ended.
+function requests(rec) {
+  const ends = new Map()
+  for (const ev of rec.events) if (ev.type === "net" && (ev.kind === "end" || ev.kind === "done" || ev.kind === "close")) ends.set(`${ev.list}:${ev.i}`, ev.t)
+  const out = []
+  const kinds = { fetches: "", xhrs: "XHR ", sses: "EventSource ", sockets: "WebSocket " }
+  for (const list of Object.keys(kinds)) {
+    ;(rec[list] || []).forEach((e, i) => {
+      if (!e || e.t0 == null) return
+      const key = String(e.key || "").replace(/ (rsc|next-router-[\w-]+|next-action)=\S+/g, (m) => (/next-action/.test(m) ? " (server action)" : /rsc/.test(m) ? " (RSC)" : ""))
+      const end = ends.get(`${list}:${i}`)
+      const how = e.fail ? `failed (${e.fail})` : e.error ? "failed" : e.status ? `${e.status}` : list === "fetches" || list === "xhrs" ? "no answer recorded" : "opened"
+      out.push({ t: e.t0, end, kind: "request", text: `${kinds[list]}${key} → ${how}${end != null && end > e.t0 ? ` (${dur(end - e.t0)})` : ""}` })
+    })
+  }
+  return out
+}
+
+// "css-animation `fade-in` (opacity, transform)", "opacity transition"
+function clipName(c) {
+  const what = c.kind === "transition" ? `${c.property || "?"} transition` : c.kind === "css-animation" ? `animation \`${c.label}\`${c.property ? ` (${c.property})` : ""}` : `animation (${c.property || c.label || "waapi"})`
+  return what
+}
+function values(c) {
+  if (!c.from || !c.to) return ""
+  const keys = [...new Set([...Object.keys(c.from), ...Object.keys(c.to)])]
+  return keys.map((k) => `${k} ${c.from[k] ?? "?"} → ${c.to[k] ?? "?"}`).join(", ")
+}
+const clipEnd = (c, rec) => (c.end == null ? Math.max(rec.end || 0, c.start) : c.end)
+
+function clipLine(c, rec, at) {
+  const s = rec.start || 0
+  const loops = c.iterations === "infinite"
+  const span = c.end == null ? `${fmt(c.start - s)} → ${loops ? `looping${c.dur ? ` (${dur(c.dur)} each)` : ""}` : "still running"}` : `${fmt(c.start - s)} → ${fmt(c.end - s)} (${dur(c.end - c.start)}${c.iterations > 1 ? `, ${c.iterations}×` : ""})`
+  const bits = [`${span} ${clipName(c)} on ${c.selector || "?"}${c.component ? ` [${c.component}]` : ""}`]
+  const v = values(c)
+  if (v) bits.push(v)
+  if (c.delay) bits.push(`after a ${dur(c.delay)} delay`)
+  if (at != null) {
+    const end = clipEnd(c, rec)
+    if (at < c.start) bits.push(`starts ${dur(c.start - at)} after the moment`)
+    else if (at > end) bits.push(`ended ${dur(at - end)} before the moment`)
+    else if (c.end != null && c.end > c.start) bits.push(`running at the moment, ${Math.round(((at - c.start) / (c.end - c.start)) * 100)}% through`)
+    else bits.push("running at the moment")
+  }
+  return `- ${bits.join("; ")} (clip ${c.id})`
+}
+
+/**
+ * The report. Either a moment (`at`, with a window around it) or a window.
+ * @param {any} rec a readRecording() result
+ * @param {{ at?: number | null, from?: number | null, to?: number | null, selector?: string | null, component?: string | null,
+ *   title?: string, limit?: number, known?: { rel: Map<string, string>, running: string[] } | null }} opts times in the recording's own clock (ms);
+ *   `known`: a note's own word on which clips are its element's (by recorded path) and what was running, used instead of selectors
+ */
+export function report(rec, { at = null, from = null, to = null, selector = null, component = null, title = "", limit = 40, known = null } = {}) {
+  const s = rec.start || 0
+  const end = Math.max(rec.end || 0, s)
+  const lo = Math.max(s, from ?? s)
+  const hi = Math.min(end, to ?? end)
+  const lines = []
+  if (title) lines.push(title)
+  lines.push(`Window: ${fmt(lo - s)} → ${fmt(hi - s)} of a ${fmt(end - s)} recording${at != null ? `; the moment is ${fmt(at - s)}` : ""}.`)
+
+  // Animations on or near the element.
+  const overlaps = (c) => c.start <= hi && clipEnd(c, rec) >= lo
+  if (selector) {
+    const relOf = (c) => (known ? known.rel.get(String(c.id)) || null : relation(c.selector, selector) || (component && c.component === component ? "same component" : null))
+    const near = rec.clips.map((c) => ({ c, rel: relOf(c) })).filter((x) => x.rel)
+    const inWin = near.filter((x) => overlaps(x.c))
+    lines.push("", `Animations on or near ${selector}${component ? ` [${component}]` : ""}:`)
+    if (!inWin.length) lines.push("- none in this window")
+    const order = { on: 0, inside: 1, around: 2, "same component": 3 }
+    inWin.sort((a, b) => (order[a.rel] ?? 0.5) - (order[b.rel] ?? 0.5) || a.c.start - b.c.start)
+    for (const { c, rel } of inWin.slice(0, 12)) lines.push(clipLine(c, rec, at).replace(/^- /, `- (${rel}) `))
+    if (inWin.length > 12) lines.push(`- …and ${inWin.length - 12} more`)
+    const outside = near.filter((x) => !overlaps(x.c) && x.rel === "on")
+    if (outside.length) lines.push(`Outside the window this element also animates at: ${outside.slice(0, 6).map(({ c }) => `${fmt(c.start - s)} (${c.kind === "transition" ? `${c.property} transition` : c.label})`).join(", ")}${outside.length > 6 ? `, +${outside.length - 6} more` : ""}.`)
+    if (known) lines.push(known.running.length ? `At the note's moment it is mid-animation (the note says): ${known.running.join(", ")}.` : "At the note's moment nothing on it is animating (the note says so; see above for what came before and after).")
+    else if (at != null) {
+      const running = inWin.filter(({ c, rel }) => (rel === "on" || rel === "inside") && c.start <= at && at <= clipEnd(c, rec))
+      lines.push(running.length ? `At the moment it is mid-animation: ${running.map(({ c }) => clipName(c)).join(", ")}.` : "At the moment nothing on it is animating (see above for what came before and after).")
+    }
+  }
+
+  // What happened, in order.
+  const all = happenings(rec).filter((h) => h.t <= hi && (h.end ?? h.t) >= lo)
+  let shown = all
+  let dropped = 0
+  if (all.length > limit) {
+    const ref = at ?? (lo + hi) / 2
+    shown = [...all].sort((a, b) => Math.abs(a.t - ref) - Math.abs(b.t - ref)).slice(0, limit).sort((a, b) => a.t - b.t)
+    dropped = all.length - shown.length
+  }
+  lines.push("", "What happened (user actions, routes, page loads, requests):")
+  /** @type {Array<{ t: number, line: string, moment?: boolean }>} */
+  const marks = shown.map((h) => ({ t: h.t, line: `- ${fmt(h.t - s)}${h.end != null && h.kind !== "request" ? `–${fmt(h.end - s)}` : ""} ${h.text}` }))
+  if (at != null) marks.push({ t: at, line: `- ${fmt(at - s)} ◆ the moment`, moment: true })
+  marks.sort((a, b) => a.t - b.t || (a.moment ? 1 : b.moment ? -1 : 0))
+  if (!shown.length) lines.push("- nothing recorded in this window")
+  lines.push(...marks.map((m) => m.line))
+  if (dropped) lines.push(`(${dropped} more not shown, the furthest from ${at != null ? "the moment" : "the middle"}; ask for a narrower window)`)
+  if (at != null) {
+    const acts = happenings(rec).filter((h) => ["click", "submit", "type", "key", "change", "focus", "nav"].includes(h.kind))
+    const before = acts.filter((h) => h.t <= at).pop()
+    const after = acts.find((h) => h.t > at)
+    lines.push(`Last action before the moment: ${before ? `${before.text} at ${fmt(before.t - s)} (${dur(at - before.t)} earlier)` : "none"}. Next after: ${after ? `${after.text} at ${fmt(after.t - s)}` : "none"}.`)
+  }
+
+  // Animations elsewhere on the page.
+  const others = rec.clips.filter((c) => overlaps(c) && !(selector && (known ? known.rel.has(String(c.id)) : relation(c.selector, selector))))
+  if (others.length) {
+    const groups = new Map()
+    for (const c of others) {
+      const key = `${clipName(c)} on ${c.selector}`
+      const g = groups.get(key) || { c, n: 0 }
+      g.n++
+      groups.set(key, g)
+    }
+    const list = [...groups.values()].sort((a, b) => (at != null ? Math.abs(a.c.start - at) - Math.abs(b.c.start - at) : a.c.start - b.c.start))
+    lines.push("", `${selector ? "Other animations" : "Animations"} in this window (${others.length}):`)
+    for (const g of list.slice(0, selector ? 6 : 15)) lines.push(clipLine(g.c, rec, at) + (g.n > 1 ? ` ×${g.n}` : ""))
+    if (list.length > (selector ? 6 : 15)) lines.push(`- …and ${list.length - (selector ? 6 : 15)} more kinds`)
+  }
+
+  // How much of the screen changed: the biggest moments.
+  const act = rec.activity
+  if (act && Array.isArray(act.v)) {
+    const peaks = act.v
+      .map((v, i) => ({ t: act.start + i * act.step, v }))
+      .filter((p) => p.t >= lo && p.t <= hi && p.v >= 10)
+      .sort((a, b) => b.v - a.v)
+      .slice(0, 3)
+      .sort((a, b) => a.t - b.t)
+    if (peaks.length) lines.push("", `Screen changed most at: ${peaks.map((p) => `${fmt(p.t - s)} (${p.v}% of the view)`).join(", ")}.`)
+  }
+  return lines.join("\n")
+}