retake-dev 0.4.0 → 0.5.1

package/src/plugin.js

@@ -12,7 +12,7 @@ import { createBus, sessionApi } from "./server/api.js"
 import { frontRuntime } from "./server/detect.js"
 
 // The site's deployed build (apps/site/app/retake-dock, retake-runtime) and the tests import these from here.
-export { runtimeSource, shellHtml, runtimeTag, injectHtml } from "./core.js"
+export { runtimeSource, shellHtml, runtimeTag, injectHtml, markSvg } from "./core.js"
 
 const NESTED_DEST = new Set(["iframe", "frame", "embed", "object"])
 const pageKind = new AsyncLocalStorage()
@@ -30,6 +30,8 @@ export function retake(options = {}) {
   options = { ...options, token: options.token || crypto.randomBytes(16).toString("hex") }
   const bus = createBus()
   let ssr = false
+  /** @type {string | undefined} */
+  let viteRoot
   // The dock for a top-level page load, the runtime injected into the dock's
   // frame (Sec-Fetch-Dest: iframe; isAppFrame() tells it from an app's own
   // iframe), and anything else left alone. Which one a request is stays known
@@ -43,7 +45,7 @@ export function retake(options = {}) {
     if (url.pathname.startsWith("/__retake/") || mode !== "navigate" || optOut) return pageKind.run("plain", next)
     if (req.method === "GET" && dest === "document" && req.headers["sec-fetch-site"] !== "cross-site") {
       res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" })
-      return res.end(shellHtml({ ...options, marker: "header" }))
+      return res.end(shellHtml({ root: viteRoot, ...options, marker: "header" }))
     }
     if (dest !== "iframe" && dest !== "frame") return pageKind.run("plain", next)
     delete req.headers["accept-encoding"]
@@ -62,6 +64,8 @@ export function retake(options = {}) {
     },
     configureServer(server) {
       if (options.enabled === false) return
+      // Source paths in notes are given relative to the project.
+      viteRoot = options.root || server.config.root
       // No index.html: a framework renders the pages itself (React Router,
       // SvelteKit, Astro, TanStack Start...), and transformIndexHtml never sees
       // them. Then pages are told apart by their Sec-Fetch-* headers, like the
@@ -109,7 +113,7 @@ export function retake(options = {}) {
         // `?retake=0` opts a page load out entirely.
         if (params.get("retake") === "0") return
         if (params.get("__wb") === "plain") return
-        if (params.get("__wb") !== "app") return shellHtml(options)
+        if (params.get("__wb") !== "app") return shellHtml({ root: viteRoot, ...options })
         return [{ tag: "script", attrs: { "data-retake": "" }, children: runtimeSource(), injectTo: "head-prepend" }]
       },
     },

package/src/runtime/10-animations.js

@@ -186,8 +186,17 @@ function reclaimNative() {
   }
 }
 
+// Where the app (or the library it uses) called element.animate(): the stack,
+// kept per animation so its clip can say where it is defined (65-timeline.js).
+const madeAt = new WeakMap()
 Element.prototype.animate = function (...args) {
   const a = orig.animate.apply(this, args)
+  try {
+    const limit = Error.stackTraceLimit
+    Error.stackTraceLimit = 30
+    madeAt.set(a, new Error().stack)
+    Error.stackTraceLimit = limit
+  } catch {}
   adopt(a, true)
   return a
 }

package/src/runtime/60-preview.js

@@ -72,7 +72,9 @@ function logMutations(records) {
     if (r.type === "attributes" && r.attributeName === HOVER_ATTR) continue // our :hover stand-in
     if (r.type === "attributes") {
       const next = later((x) => x.type === "attributes" && x.target === r.target && x.attributeName === r.attributeName)
-      domLog.push({ t, kind: "attr", node: r.target, name: r.attributeName, old: r.oldValue, now: next ? next.oldValue : r.target.getAttribute(r.attributeName) })
+      const now = next ? next.oldValue : r.target.getAttribute(r.attributeName)
+      domLog.push({ t, kind: "attr", node: r.target, name: r.attributeName, old: r.oldValue, now })
+      if (r.attributeName === "style") noteStyleWrite(r.target, t, r.oldValue, now) // script-driven motion (62-motion.js)
     } else if (r.type === "characterData") {
       const next = later((x) => x.type === "characterData" && x.target === r.target)
       domLog.push({ t, kind: "text", node: r.target, old: r.oldValue, now: next ? next.oldValue : r.target.data })

package/src/runtime/62-motion.js

@@ -0,0 +1,106 @@
+// Script-driven motion: an element whose inline style a script rewrites frame
+// after frame (GSAP, Motion's x/y/scale, a parallax handler). It never shows
+// up as an Animation, so it's read off the DOM log (logMutations hands every
+// style attribute change here): writes on one element less than MOTION_GAP
+// apart are one clip, kind "js", with the properties that changed and their
+// first and last inline values; once it is a clip, a still stretch of up to
+// MOTION_HOLD is part of it (clip.holds: [from, to] pairs). A clip is recorded from its third write (one
+// style change is a state, not motion). Where it's written comes from one
+// stack per element, taken at its first write through the style setters.
+
+const MOTION_GAP = 120
+const MOTION_HOLD = 1000
+const MOTION_MIN_WRITES = 3
+const MOTION_PROPS = /^(transform|translate|scale|rotate|opacity|top|left|right|bottom|width|height|filter|clip-path)$/
+const motionRuns = new WeakMap() // element -> { c, last, writes, from, to }
+const styleStack = new WeakMap() // CSSStyleDeclaration -> stack at its first write
+
+function parseInline(s) {
+  const out = {}
+  for (const part of String(s || "").split(";")) {
+    const i = part.indexOf(":")
+    if (i > 0) out[part.slice(0, i).trim().toLowerCase()] = part.slice(i + 1).trim()
+  }
+  return out
+}
+
+// The properties that moved (a reset to none that was never set isn't motion).
+const movedProps = (run) => Object.keys(run.from).filter((p) => !((run.from[p] === "" || run.from[p] === "none") && (run.to[p] === "" || run.to[p] === "none")))
+
+function noteStyleWrite(el, t, old, now) {
+  if (!rec || previewing || hasFuture() || clock.seeking || !el || el.nodeType !== 1) return
+  const a = parseInline(old)
+  const b = parseInline(now)
+  const changed = [...new Set([...Object.keys(a), ...Object.keys(b)])].filter((p) => a[p] !== b[p] && MOTION_PROPS.test(p))
+  if (!changed.length) return
+  let run = motionRuns.get(el)
+  // A pause of up to MOTION_HOLD inside a clip is a hold of the same motion
+  // (Motion keyframes with a plateau write nothing while the value stays).
+  if (run && run.c && t - run.last > MOTION_GAP && t - run.last <= MOTION_HOLD) (run.c.holds || (run.c.holds = [])).push([run.last, t])
+  else if (!run || t - run.last > MOTION_GAP) {
+    run = { c: null, start: t, last: t, writes: 0, from: {}, to: {}, first: b }
+    motionRuns.set(el, run)
+  }
+  run.last = t
+  run.writes++
+  for (const p of changed) {
+    if (!(p in run.from)) run.from[p] = a[p] || ""
+    run.to[p] = b[p] || ""
+  }
+  if (!run.c && run.writes >= MOTION_MIN_WRITES) {
+    const clips = rec.clips || (rec.clips = [])
+    const props = movedProps(run)
+    if (!props.length) return
+    const pick = (o) => Object.fromEntries(props.map((p) => [p, o[p]]))
+    /** @type {Record<string, any>} */
+    const c = { id: `c${clips.length + 1}`, kind: "js", start: run.start, end: t, label: props.join(", "), selector: selectorOf(el), component: componentOf(el) || undefined, property: props.join(", "), path: pathOf(el), from: pick(run.from), to: pick(run.to), first: pick(run.first) }
+    if (c.component === undefined) delete c.component
+    const frames = stackFrames(styleStack.get(el.style))
+    if (frames.length) c.stack = frames
+    clips.push(c)
+    run.c = c
+  } else if (run.c) {
+    const props = movedProps(run)
+    run.c.end = t
+    run.c.label = run.c.property = props.join(", ")
+    run.c.from = Object.fromEntries(props.map((p) => [p, run.from[p]]))
+    run.c.to = Object.fromEntries(props.map((p) => [p, run.to[p]]))
+  }
+}
+
+// One stack per element: the first write to one of these through its style.
+;(function wrapStyleSetters() {
+  const SP = typeof CSSStyleDeclaration !== "undefined" ? CSSStyleDeclaration.prototype : null
+  if (!SP) return
+  // The property accessors live on the style object's own interface (CSSStyleProperties in newer browsers).
+  const owner = (p) => {
+    for (let o = Object.getPrototypeOf(document.documentElement.style); o; o = Object.getPrototypeOf(o)) if (Object.prototype.hasOwnProperty.call(o, p)) return o
+    return null
+  }
+  const keep = (decl) => {
+    if (styleStack.has(decl)) return
+    try {
+      const limit = Error.stackTraceLimit
+      Error.stackTraceLimit = 30
+      styleStack.set(decl, new Error().stack)
+      Error.stackTraceLimit = limit
+    } catch {}
+  }
+  for (const p of ["transform", "translate", "scale", "rotate", "opacity", "top", "left", "width", "height"]) {
+    const proto = owner(p)
+    const d = proto && Object.getOwnPropertyDescriptor(proto, p)
+    if (!d || !d.set || !d.configurable) continue
+    Object.defineProperty(proto, p, {
+      ...d,
+      set(v) {
+        keep(this)
+        d.set.call(this, v)
+      },
+    })
+  }
+  const setProperty = SP.setProperty
+  SP.setProperty = function (name, ...rest) {
+    if (MOTION_PROPS.test(String(name))) keep(this)
+    return setProperty.call(this, name, ...rest)
+  }
+})()

package/src/runtime/65-timeline.js

@@ -154,6 +154,30 @@ function recordedStart(a) {
   return best.start
 }
 
+const KF_SKIP = ["offset", "easing", "composite", "computedOffset"]
+function keyframeValues(k) {
+  const out = {}
+  let n = 0
+  for (const p of Object.keys(k)) {
+    if (KF_SKIP.includes(p) || n >= 4 || k[p] == null) continue
+    const v = String(k[p])
+    if (v.length <= 80) (out[p] = v), n++
+  }
+  return out
+}
+// The frames of an element.animate() stack that aren't Retake's own (an
+// inline script in this document): [{ url, line, col }], innermost first.
+function stackFrames(stack) {
+  const here = location.href.replace(/#.*$/, "")
+  const out = []
+  for (const line of String(stack || "").split("\n").slice(1)) {
+    const m = /\(?((?:https?|file|webpack-internal):\/\/[^\s()]+?):(\d+):(\d+)\)?\s*$/.exec(line)
+    if (!m || m[1] === here) continue
+    out.push({ url: m[1], line: Number(m[2]), col: Number(m[3]) })
+    if (out.length >= 12) break
+  }
+  return out
+}
 function recordClip(e) {
   if (!rec || hasFuture() || clock.seeking) return // replaying: rec.clips already has it
   const clips = rec.clips || (rec.clips = [])
@@ -162,8 +186,23 @@ function recordClip(e) {
   const iters = e.timing && e.timing.iterations
   if (iters === Infinity) c.iterations = "infinite"
   else if (iters > 1) c.iterations = iters
+  const timing = e.timing || {}
+  if ((iters ?? 1) !== 1 && Number(timing.duration) > 0) c.dur = Math.round(Number(timing.duration))
+  if (Number(timing.delay) > 0) c.delay = Math.round(Number(timing.delay))
+  // What it animates between (first and last keyframe), so a reader of the
+  // recording knows what was visible: { opacity: "0" } → { opacity: "1" }.
+  const kf = e.keyframes || []
+  if (kf.length >= 2) {
+    c.from = keyframeValues(kf[0])
+    c.to = keyframeValues(kf[kf.length - 1])
+  }
   if (c.property === undefined) delete c.property
   if (c.component === undefined) delete c.component
+  const stack = madeAt.get(e.anim)
+  if (stack) {
+    const frames = stackFrames(stack)
+    if (frames.length) c.stack = frames
+  }
   clips.push(c)
   clipOfEntry.set(e, c)
 }

package/src/runtime/67-csssource.js

@@ -163,6 +163,73 @@ function locate(hit) {
   return out
 }
 
+// A rule in a <link rel=stylesheet> (Next, Nuxt, SvelteKit...): its text and
+// source map fetched once per sheet (index maps with sections too, as
+// Turbopack writes them), then the same lookup as locate().
+const linkedCache = new Map() // href -> Promise<{ text, lines, sources, offsets } | null>
+function linkedSheet(href) {
+  if (linkedCache.has(href)) return linkedCache.get(href)
+  // As a stylesheet: Vite answers a bare fetch of a .css URL with a JS module
+  // that wraps the CSS in a string (every rule on one line).
+  const p = real
+    .fetch(href, { headers: { accept: "text/css,*/*;q=0.1" } })
+    .then((r) => (r.ok ? r.text() : null))
+    .then(async (text) => {
+      if (text == null) return null
+      const out = { text, sections: [] }
+      const m = /\/\*# sourceMappingURL=([^\s*]+)\s*\*\//.exec(text)
+      if (!m) return out
+      let map = null
+      try {
+        if (m[1].startsWith("data:")) map = JSON.parse(new TextDecoder().decode(fromB64(m[1].split(",").pop())))
+        else {
+          const r = await real.fetch(new URL(m[1], href).href)
+          map = r.ok ? await r.json() : null
+        }
+      } catch {}
+      if (!map) return out
+      const parts = Array.isArray(map.sections) ? map.sections.map((s) => ({ line: (s.offset && s.offset.line) || 0, map: s.map })) : [{ line: 0, map }]
+      for (const part of parts) if (part.map && part.map.mappings != null) out.sections.push({ line: part.line, sources: part.map.sources || [], lines: decodeMappings(part.map.mappings) })
+      return out
+    })
+    .catch(() => null)
+  linkedCache.set(href, p)
+  return p
+}
+async function locateLinked(hit, out) {
+  const sheet = await linkedSheet(hit.sheet.href)
+  if (!sheet) return out
+  const head = hit.rule instanceof CSSKeyframesRule ? `@keyframes ${hit.rule.name}` : hit.rule.selectorText
+  let idx = sheet.text.indexOf(head)
+  if (idx < 0) idx = sheet.text.indexOf(head.split(",")[0].trim())
+  if (idx < 0) return out
+  const before = sheet.text.slice(0, idx)
+  const genLine = before.split("\n").length - 1
+  const genCol = idx - before.lastIndexOf("\n") - 1
+  // Turbopack names each part: /* [project]/app/globals.css [app-client] (css) */
+  const named = [...before.matchAll(/\/\* \[project\]\/([^\s*]+)[^*]*\*\//g)].pop()
+  if (named) out.file = named[1]
+  // No source map and not a bundle: the served file is the source (plain CSS from a dev server).
+  else if (!sheet.sections.length) out.line = genLine + 1
+  let sec = null
+  for (const s of sheet.sections) if (s.line <= genLine) sec = s
+  const segs = sec && sec.lines[genLine - sec.line]
+  if (!segs || !segs.length) return out
+  let seg = null
+  for (const sg of segs) if (sg[0] <= genCol) seg = sg
+  if (!seg) seg = segs[0]
+  out.line = seg[2] + 1
+  const srcName = sec.sources[seg[1]]
+  if (srcName) {
+    try {
+      out.file = srcName.startsWith("file://") ? decodeURIComponent(new URL(srcName).pathname) : srcName.replace(/^turbopack:\/\/\/?(\[project\]\/)?/, "").replace(/^webpack:\/\/[^/]*\//, "")
+    } catch {
+      out.file = srcName
+    }
+  }
+  return out
+}
+
 // A Tailwind utility (e.g. .animate-pulse) from Tailwind's generated CSS?
 function tailwindUtility(hit) {
   const sel = hit.selector.replace(/\\/g, "")
@@ -213,9 +280,14 @@ async function cssSourceFor(x) {
   }
   if (!hit) return null
   const out = locate(hit)
+  if (out.line == null && hit.sheet.href) await locateLinked(hit, out)
   if (t.kind === "css-animation" && t.name) {
     const kf = findKeyframes(t.name)
-    if (kf) out.keyframes = { name: t.name, ...locate(kf) }
+    if (kf) {
+      const k = locate(kf)
+      if (k.line == null && kf.sheet.href) await locateLinked(kf, k)
+      out.keyframes = { name: t.name, ...k }
+    }
   }
   const utility = tailwindUtility(hit)
   if (utility) {

package/src/runtime/70-boot.js

@@ -112,7 +112,7 @@ function record() {
 }
 
 Object.assign(PT, {
-  version: "0.4.0",
+  version: "0.5.1",
   now: () => clock.now,
   record,
   // Play from here: replays the recorded future, then carries on live.
@@ -363,6 +363,25 @@ try {
   }
 } catch {}
 
+// A link or redirect to another site (GitHub, npm, a sign-in page) can't load
+// inside the dock's frame: most sites refuse to be framed. A click the user
+// makes opens it in a new tab, so the timeline stays; anything else (a
+// redirect) goes to the top window, as it would without Retake. Frames being
+// built or replayed never leave.
+try {
+  if (W.navigation && shell) {
+    W.navigation.addEventListener("navigate", (e) => {
+      if (!e.cancelable || e.downloadRequest || !e.destination) return
+      const url = new URL(e.destination.url)
+      if (url.origin === location.origin || !/^https?:$/.test(url.protocol)) return
+      e.preventDefault()
+      if (clock.seeking || !onShow()) return
+      if (e.userInitiated) W.open(url.href, "_blank", "noopener")
+      else W.top.location.assign(url.href)
+    })
+  }
+} catch {}
+
 // A reload (or navigation) fires beforeunload first; a frame the dock removes
 // doesn't. Only a reload leaves its recording on the shell to resume.
 let unloading = false
@@ -383,7 +402,14 @@ function boot() {
   findSmil(document)
   syncSmil(clock.now, null, segmentAt(clock.now).t)
   if (shell) shell.attach(PT)
-  if (shell) W.addEventListener("blur", () => shell.meta && shell.meta(false))
+  // This window losing focus lets go of ⌘ (a ⌘-shortcut took it away), but
+  // only the frame on show's: one built behind, or one being swapped out,
+  // blurs on its own while ⌘ is still held (F99).
+  if (shell)
+    W.addEventListener("blur", () => {
+      if (typeof shell.shows === "function" && !shell.shows(W)) return
+      if (shell.meta) shell.meta(false)
+    })
   // Let the first render settle on real frames before time starts moving.
   real.raf(() =>
     real.raf(async () => {

package/src/server/api.js

@@ -8,6 +8,7 @@
 //   GET      /__retake/notes/:id
 //   PATCH    /__retake/notes/:id          { status?, reply? }
 //   GET      /__retake/events             SSE: note-updated, code-version, active-changed, session
+//   GET      /__retake/map?url=&line=&col= a compiled chunk on disk (a server component's) → { file, line }
 //
 // Mutating requests need `x-retake-token`. The token is injected into the
 // shell page and written to <root>/.retake/server.json for local tools (MCP).
@@ -15,6 +16,8 @@ import fs from "node:fs"
 import path from "node:path"
 import zlib from "node:zlib"
 import { promisify } from "node:util"
+import { fileURLToPath } from "node:url"
+import { cleanSource, isLibrary, originalPosition } from "./sourcemap.js"
 
 const gzip = promisify(zlib.gzip)
 const gunzip = promisify(zlib.gunzip)
@@ -110,7 +113,15 @@ function readBody(req) {
         req.destroy()
       } else chunks.push(c)
     })
-    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")))
+    req.on("end", () => {
+      const body = Buffer.concat(chunks)
+      // The dock gzips large uploads (a Next.js middleware takes 10 MB at most).
+      if (!/^\s*gzip\s*$/i.test(String(req.headers["content-encoding"] || ""))) return resolve(body.toString("utf8"))
+      gunzip(body, { maxOutputLength: MAX_BODY }).then(
+        (b) => resolve(b.toString("utf8")),
+        (err) => reject(Object.assign(err, { status: err instanceof RangeError ? 413 : 400 })),
+      )
+    })
     req.on("error", reject)
   })
 }
@@ -151,6 +162,66 @@ export function writeServerInfo({ root, url, token, base = "/" }) {
   }
 }
 
+/**
+ * Where a line of a compiled chunk on disk came from (a server component's
+ * element: React's stack names `file:///…/.next/server/…chunk.js`, which the
+ * dock can't fetch). Only .js files inside the project, and maps next to them
+ * or inlined. → { file, line } or { file: null }.
+ * @param {string} root
+ * @param {URLSearchParams} q
+ */
+export function mapChunk(root, q) {
+  const none = { file: null, line: null }
+  const line = Number(q.get("line"))
+  const col = Number(q.get("col")) || null
+  let file
+  try {
+    const u = String(q.get("url") || "").replace(/^about:\/\/React\/Server\//, "").replace(/[?#].*$/, "")
+    file = path.resolve(u.startsWith("file:") ? fileURLToPath(u) : u)
+  } catch {
+    return none
+  }
+  const inside = (f) => {
+    const real = (() => {
+      try {
+        return fs.realpathSync(f)
+      } catch {
+        return f
+      }
+    })()
+    const r = (() => {
+      try {
+        return fs.realpathSync(root)
+      } catch {
+        return root
+      }
+    })()
+    return real === r || real.startsWith(r + path.sep)
+  }
+  if (!(line > 0) || !/\.(m|c)?js$/.test(file) || !inside(file) || !fs.existsSync(file)) return none
+  try {
+    const code = fs.readFileSync(file, "utf8")
+    const refs = [...code.matchAll(/\/\/[#@] sourceMappingURL=(\S+)/g)]
+    const ref = refs.length ? refs[refs.length - 1][1] : null
+    let json
+    if (ref && ref.startsWith("data:")) {
+      const comma = ref.indexOf(",")
+      const body = ref.slice(comma + 1)
+      json = /;base64/.test(ref.slice(0, comma)) ? Buffer.from(body, "base64").toString("utf8") : decodeURIComponent(body)
+    } else {
+      const mapFile = ref ? path.resolve(path.dirname(file), decodeURIComponent(ref)) : file + ".map"
+      if (!inside(mapFile) || !fs.existsSync(mapFile)) return none
+      json = fs.readFileSync(mapFile, "utf8")
+    }
+    const pos = originalPosition(JSON.parse(json), line, col)
+    if (!pos) return none
+    const src = cleanSource(pos.source, { root, sources: pos.sources })
+    return isLibrary(src) ? none : { file: src, line: pos.line }
+  } catch {
+    return none
+  }
+}
+
 /**
  * The /__retake/ API as a plain `(req, res, next)` handler, for any Node HTTP
  * server (Vite's middleware stack, the front server, a bare http.Server).
@@ -198,6 +269,7 @@ export function createSessionHandler({ root, token, bus }) {
       }
       return send(res, 200, { config })
     }
+    if (route[0] === "map" && route.length === 1 && req.method === "GET") return send(res, 200, mapChunk(root, url.searchParams))
     const known = ["session", "recording", "notes", "events"].includes(route[0])
     if (!known) return next() // e.g. /__retake/version and /checkout (code-versions)
     if (mutating && req.headers["x-retake-token"] !== token) return send(res, 403, { error: "missing or wrong x-retake-token" })

package/src/server/front.js

@@ -245,6 +245,8 @@ export async function startFront(options) {
     headers["X-Forwarded-Host"] = req.headers.host || ""
     headers["X-Forwarded-Proto"] = req.socket.encrypted ? "https" : "http"
     headers["X-Forwarded-Port"] = String(req.socket.localPort)
+    // An app with Retake in its own middleware (retake-dev/next) leaves it to us.
+    headers["X-Retake-Front"] = "1"
     if (frame) {
       for (const k of Object.keys(headers)) if (/^(accept-encoding|if-none-match|if-modified-since)$/i.test(k)) delete headers[k]
       headers["Accept-Encoding"] = "identity"
@@ -533,7 +535,7 @@ export async function startFront(options) {
 
   function dock(res, marker) {
     res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" })
-    res.end(shellHtml({ token, marker, docs: true }))
+    res.end(shellHtml({ token, marker, docs: true, root }))
   }
 
   // ---- WebSockets (HMR): a raw pipe -----------------------------------------