retake-dev 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,7 +1,62 @@
 # Changelog
 
-## 0.5.0
+## 0.5.1
 
+- Notes on animations work the way web animation does: per element, on the
+  animation's own clock. ⌘-click an element and it gets a row on the track with
+  its own animations; open one to see its clock (0 after the delay), its
+  keyframes and what it moves, and the path it takes on the app. Click to pin a
+  note at a point ("at 100ms (20%) of fadeUp"), drag to pin it over a range
+  ("200–400ms"), or Shift+drag the timeline first. Numbers typed in the note are
+  read on that clock. Copy for agent and `get_note` now give the animation's
+  keyframes and timing, the exact point or range with its keyframe segment, the
+  values and the box there, and how to change only that part.
+- Each animation note now carries an exact edit: the keyframes again, on plain
+  time, with the note's point or range edges as keyframes of their own and the
+  exact part of each curve on both sides (written for CSS `@keyframes`,
+  `element.animate()` or Motion's `times`/`ease`). Change the marked part and the
+  rest of the motion stays as it was, even when the easing is on the whole
+  effect. A `@keyframes` that runs on several elements says so, and the edit
+  gives the noted element its own copy.
+- Motion keyframes (`x: [0, 120, 120, 240]` with `times`) are read off the
+  motion element's props: every keyframe, its times and the ease of each
+  segment, so a range over a hold is on one clip and the exact edit is in
+  Motion's own terms. A CSS transition's exact edit is its timing as `linear()`
+  stops with the range edges marked. Two animations over the same time on one
+  element (a transform and an opacity transition) stack on its row, so either
+  can be opened.
+- Script-driven motion is recorded: GSAP tweens, Motion's `x`/`y`/`scale` and
+  react-spring write inline styles every frame, and now show as clips (kind
+  `js`) with their first and last values. Motion and GSAP are named, with
+  Motion's `animate`/`transition` props in the note; `element.animate()` clips
+  say where they were called. A note after an animation ended is about its end
+  state. CSS animations from `<link>` stylesheets (Next, any framework) get
+  their `@keyframes` file and line, and source paths are relative to the project.
+- ⌘-click picks what you can see under the pointer: text, media, a control or a
+  painted box come first; empty overlays (glows, stretched links, scrims) and
+  invisible layers (opacity 0, a closed menu sheet) are a wheel step away, shown
+  dimmed with why. The highlight and the note always agree (⌘ pressed with the
+  pointer already still, or a build swapping in while ⌘ is held). An svg icon is
+  the `<svg>` or its button, not the section around it; shadow DOM and embedded
+  iframes are pickable (an embed gets no clicks while paused). A note's clip is
+  only ever its own element's (or an ancestor's that moves it). Selectors leave
+  out generated ids and classes that came and went during the recording, so they
+  find the element on a fresh load. A server component's element gets its own
+  source line (`GET /__retake/map`), or "unknown", never its client parent's.
+  Next's layout components are left out of component names. A second ⌘-click on
+  a pinned spot makes a new note there.
+- `retake mcp`: `get_animation` maps recording times onto an animation's own
+  clock (and into CSS %, Motion `times`, GSAP seconds); `get_moment` on a note
+  takes the note's word for which animations are its element's, so it can't
+  disagree with `get_note`; `list_notes` shows each note's range and animation.
+  The server's instructions carry a short guide to editing each kind of animation.
+- Next.js: the timeline on your usual dev URL. Add `proxy.ts` with
+  `export { default } from "retake-dev/next"` (Next 16), or `middleware.ts` with the
+  Node.js runtime (Next 15), and run `next dev` as always: no second port. Already
+  have one? `export default withRetake(yourMiddleware)`. Sessions, notes and
+  `retake mcp` work as with the CLI. Dev only: `next build` output has no dock or
+  runtime. `npx retake-dev .` still works without installing anything.
+- Large recordings upload gzipped (a Next.js middleware reads 10 MB of a request at most).
 - The dock is open on a first visit, and folds away: drag its divider down (or
   press ⌥T) and the timeline becomes a round button, bottom-right at first. The
   dock follows the pointer all the way down; let go near the bottom and it eases
@@ -31,6 +86,26 @@
 - Leaving the page while recording (a new address typed in) no longer loses the
   seconds since the last save: they're kept in the tab's sessionStorage and the
   timeline carries on from them.
+- `retake mcp` reads the recording: `get_moment` (around a note's moment, or any
+  moment of a timeline) and `get_timeline_events` (a stretch of a timeline) list
+  the user's actions, requests, route changes, the animations on or near an
+  element with their start, end and what they animate between, and when the
+  screen changed most. `get_note` gives the animation's start and end too, and
+  points to `get_moment`.
+- A note's source in a bundled app (Next.js on Turbopack or webpack) is the
+  app's file and line: the dock reads the chunk's source map, index maps
+  included, and skips frames that land in the bundled JSX runtime. With no map
+  it says the source isn't known (`retake mcp` tries the map again) instead of
+  naming the chunk.
+- "Copy for agent" starts with two lines saying what a Retake note is and how to
+  see what happened around its moment.
+- Recorded animations keep their first and last keyframe values (`from`/`to`),
+  delay and per-iteration duration.
+- A second skill, `retake-notes`: how a coding agent works through notes.
+
+## 0.5.0
+
+The dock folds into an icon you can drag anywhere, notes show only when paused, and timelines are named Timeline 1, Timeline 2. Everything above builds on it.
 
 ## 0.4.0
 

package/README.md

@@ -51,6 +51,60 @@ export default defineConfig({
 
 `retake()` only runs in `vite dev`; `vite build` output has no Retake code in it.
 
+### Next.js: on your usual dev URL
+Install `retake-dev` (above) and add one file in the project root (in `src/` if
+your app lives in `src/app`). Then run `next dev` / `npm run dev` as always: the
+timeline shows on your normal dev URL (http://localhost:3000), no second port.
+
+```ts
+// proxy.ts (Next 16)
+export { default } from "retake-dev/next"
+```
+
+```ts
+// middleware.ts (Next 15.5)
+import retake from "retake-dev/next"
+export default retake
+export const config = { runtime: "nodejs" }
+```
+
+Install it from the registry (or a tarball, `npm i ../retake-dev-0.5.1.tgz`): a
+`file:` or linked install is a symlink, which Turbopack doesn't follow out of the
+project, and `retake-dev/next` isn't found.
+
+Next 15 needs the Node.js runtime (Retake keeps `.retake/` on disk). It only runs in
+`next dev`: in `next build` / `next start` every request goes straight on, and the
+build has no dock or runtime in it.
+
+Already have a proxy or middleware? Wrap yours:
+
+```ts
+import { withRetake } from "retake-dev/next"
+
+export default withRetake(async (req) => {
+  // ...your middleware, as before
+})
+```
+
+Next reads `config` from your file as written (it can't be re-exported). Without one
+the proxy runs for every request and passes everything but page loads on. With a
+`matcher` of your own, add Retake's two entries to it:
+
+```ts
+export const config = {
+  matcher: [
+    "/__retake/:path*",
+    { source: "/((?!_next/static|_next/image).*)", has: [{ type: "header", key: "sec-fetch-mode", value: "navigate" }] },
+    // ...your entries
+  ],
+}
+```
+
+`withRetake` hands every request it doesn't answer to your function, so with a
+merged matcher your function also sees page loads it didn't match before.
+No install at all: `npx retake-dev .` runs `next dev` behind Retake's own port
+(3014) instead.
+
 ### Connect your coding agent (MCP)
 Notes you leave in the dock can go straight to your coding agent. Register the
 MCP server once, from the app folder. With Claude Code:
@@ -63,10 +117,26 @@ Any other MCP client (Cursor, Codex, Windsurf...) takes the same command,
 `npx -y retake-dev mcp`, in its MCP settings.
 
 With the dev server running, the agent can `list_notes`, `get_note`,
-`get_active_timeline`, `acknowledge`, `resolve`, `reply` and `watch_notes`.
+`get_moment`, `get_animation`, `get_timeline_events`, `get_active_timeline`,
+`acknowledge`, `resolve`, `reply` and `watch_notes`.
 It finds the server through `.retake/server.json` (or pass `--url http://localhost:3014`).
 Acknowledging and resolving show up on the note in the dock right away.
 
+A note is pinned to a moment of a recording. `get_moment` (a note id, or a
+timeline and a time like `00:10.91`) reads that recording around it: the user's
+clicks, keys, typing and route changes, the requests, the animations on or near
+the element (start, end, duration, what they animate between, how far along at
+the moment) and when the screen changed most. `get_timeline_events` lists the
+same for any stretch of a timeline. A note whose source is only a line of a
+compiled bundle (a Next.js chunk) is mapped back to the app's file and line
+through the bundle's source map.
+
+A note on an animation says exactly which part of it you mean (see
+[Notes on animations](#notes-on-animations)). `get_animation` gives that
+animation's timing and every keyframe, and maps any recording time onto its own
+clock, in CSS %, Motion `times` and GSAP seconds. `get_note`, `get_moment` and
+Copy for agent describe the element and its animation with the same words.
+
 ### The first 60 seconds
 1. **Use your app** for a few seconds: it's being recorded already.
 2. **Pause** with space (or ⌥P, or the play button). The app goes view-only:
@@ -81,9 +151,71 @@ Acknowledging and resolving show up on the note in the dock right away.
    the element, its React component, source file:line and CSS; or let your
    agent pick it up over MCP.
 
+### Picking an element
+Hold ⌘ over the paused app: a chip by the pointer lists what's under it, and the
+pick is what you can see there: text, an image or icon, a control, a painted box.
+Empty overlays (a glow, a stretched card link, a scrim) and invisible layers
+(opacity 0, a closed menu) stay in the list, dimmed with why, one wheel step or
+Tab away. On an icon you get the `<svg>` (or the button it's the icon of), with
+the shape inside it a step away; inside an open shadow root, the element itself;
+an embedded iframe is one element (and gets no clicks while paused). A second
+⌘-click on a pinned spot makes another note there.
+
+The note's selector finds the element again on a fresh load: no generated ids
+(`:r1:`, `radix-…`), no classes that came and went during the recording (`in`,
+`is-open`, `opacity-100`), test ids, labels and hrefs where they're unique. Its
+source is where the element itself was written, a server component's line too
+(the dev server reads the chunk's source map), never just the parent it was
+passed into; Next's own layout components aren't listed as yours.
+
+### Notes on animations
+Web animations aren't edited on a global timeline: each one belongs to an
+element, runs on its own clock (0 is the end of its delay), and moves the
+element between keyframes. Notes work the same way.
+
+- **⌘-click an element** and it gets a row on the track under the timelines, with
+  its own animations (and an ancestor's that moves it). Nothing moving on it?
+  The row says so and lists what animates inside it; click one to switch. Two
+  animations at once (a transform and an opacity transition) stack in thinner
+  rows; hover one to see its name.
+- **Click an animation** on that row to open it: a ruler on its own clock (the
+  delay hatched before 0), a diamond where each keyframe is reached, and small
+  lines of what it moves (x, y, scale, rotation, opacity, size). The hint reads
+  where the playhead is on it: `fadeUp · 100ms of 500 · 20% · seg 0→40% ease-out ·
+  x 248 y 568 · 320×64`. On the app, dashed boxes show where the element starts and
+  ends, and a dotted line the path it takes.
+- **A point**: click on the open animation (or step with ←/→ a frame at a time,
+  Shift+←/→ keyframe to keyframe). The note is pinned there: "at 100ms (20%) of
+  fadeUp on `<h1.title>`".
+- **A range**: drag across the open animation ("200–400ms · 40–80% of fadeUp").
+  It snaps to keyframes and 10ms steps (hold ⌥ to drag freely); drag past the
+  end for "from here to the end". Shift+drag on the timeline selects a range of
+  the recording first, then ⌘-click any element.
+- **Typed numbers** ("at 100ms", "between 200 and 400 ms", "after 40%") are read
+  on the open animation's own clock; a chip under the note says how, and a click
+  switches it to recording time.
+- Esc closes the open animation, then the note.
+
+The note carries, for that animation: its kind and where it's defined, timing,
+every keyframe, the point or both range edges on its own clock (local ms,
+progress, eased progress, the keyframe segment), the values and the element's
+box there and one frame either side, samples across a range, and what to change
+for its kind (CSS keyframes, transitions, `element.animate()`, Motion, GSAP,
+scroll-driven). It ends with an exact edit: the keyframes again on plain time,
+the point or range edges as keyframes of their own, each piece keeping its part
+of the curve, so an agent changes only the marked part and the rest moves as
+before. A `@keyframes` shared with other elements is flagged, and the edit gives
+the noted element its own copy. Motion written as inline styles every frame
+(GSAP, Motion's `x`, react-spring) is recorded too, with its first and last
+values and the library named; Motion keyframes come with every keyframe, their
+`times` and each segment's ease, read off the component's props. A CSS
+transition's exact edit is its timing as `linear()` stops.
+
 ### The dock
-- **Keys**: space or ⌥P plays and pauses, ←/→ step, F fits everything, + starts
-  a new timeline at the playhead, M drops a bookmark, ⌥T folds the dock away.
+- **Keys**: space or ⌥P plays and pauses, ←/→ step (on an open animation: its
+  frames; Shift: its keyframes), F fits everything, + starts a new timeline at
+  the playhead, M drops a bookmark, ⌥T folds the dock away, Esc closes an open
+  animation, a selected range, then the note.
 - **Resize** by dragging the divider at its top. Drag it all the way down and
   the timeline folds into a round button (bottom-right at first): the whole
   window is the app's, and recording carries on. Drag the button anywhere; it
@@ -98,7 +230,7 @@ npm uninstall retake-dev          # or pnpm remove / yarn remove / bun remove
 rm -rf .retake                    # Retake's session and recordings
 claude mcp remove retake          # if you added the MCP server (or remove it in your client's MCP settings)
 ```
-Remove `retake()` from `vite.config` if you added it.
+Remove `retake()` from `vite.config`, or Retake's `proxy.ts` / `middleware.ts` (or `withRetake`), if you added it.
 
 ## Commands
 ```sh
@@ -108,7 +240,7 @@ retake <project> --code-branches     # each timeline keeps its own version of th
 retake <project> -- --host           # anything after -- goes to the dev server
 retake -- <dev command>              # run that command with the timeline in front (retake -- next dev)
 retake http://localhost:3000         # put the timeline in front of a dev server that's already running
-retake init                          # print the vite.config lines
+retake init                          # print the vite.config / proxy.ts lines
 retake mcp                           # the MCP server your coding agent runs
 ```
 `--root <dir>` puts `.retake/` somewhere else; `--verbose` logs every request the
@@ -135,7 +267,7 @@ the package manager its lockfile names):
 | Framework | Run | Notes |
 |---|---|---|
 | Vite SPA (React, Vue, Svelte, plain) | `npx retake-dev .` | or `plugins: [retake()]` in `vite.config` |
-| Next.js | `npx retake-dev .` | tested on 16.3 (app and pages router, server actions) and 15.5 (app router), Turbopack |
+| Next.js | `proxy.ts` / `middleware.ts` ([above](#nextjs-on-your-usual-dev-url)) and your usual `next dev`, or `npx retake-dev .` | tested on 16.3 (app and pages router, server actions) and 15.5 (app router), Turbopack and webpack |
 | React Router 7 framework mode | `npx retake-dev .` | or `plugins: [retake(), reactRouter()]` and your usual `npm run dev`; tested on 7.18 |
 | Remix 2 (Vite) | `npx retake-dev .` | tested on 2.17 |
 | Astro | `npx retake-dev .` | tested on 7.3 with React islands and `<ClientRouter />` |
@@ -170,7 +302,9 @@ through the same front server and should work; open an issue if one doesn't.
   loaded chunks) run at their recorded moment, the dev server's own traffic (HMR)
   is left out of the recording, and a rebuilt moment gets the page's HTML as it
   was recorded (kept in `.retake/docs/`), not rendered again. Native `import()`
-  (Vite's lazy routes, Astro islands) can't be held to its moment.
+  (Vite's lazy routes, Astro islands) can't be held to its moment. With Next's
+  `proxy.ts` the same holds, except that a rebuilt moment's page is rendered again
+  (what the server renders differently each time, like the time, can differ).
 - **The dock covers the bottom of the app.** It floats over the bottom of
   the app (a cookie banner's buttons, Next's dev badge). Drag the dock's divider
   down (all the way down folds it into a button in the corner, as does ⌥T), or

package/bin/retake.js

@@ -38,7 +38,8 @@ Usage:
   retake http://localhost:3000      put the timeline in front of a running dev server
   retake -- <dev command>           run that command with the timeline in front
                                     (e.g. retake -- next dev, retake -- pnpm dev)
-  retake init                       print the vite.config lines instead
+  retake init                       print the lines for vite.config or Next's
+                                    proxy.ts instead
   retake mcp [--url http://localhost:3014]
                                     MCP server for coding agents (stdio)
 
@@ -289,6 +290,18 @@ function init() {
   })
 
 Options: retake({ codeBranches: true }) gives each timeline its own version of the code.
+
+Next.js: one file in the project root (src/ if your app is in src/app), dev only; the timeline
+shows on your usual dev URL:
+
+  // proxy.ts (Next 16)
+  export { default } from "retake-dev/next"
+
+  // middleware.ts (Next 15)
+  import retake from "retake-dev/next"
+  export default retake
+  export const config = { runtime: "nodejs" }
+
 Or leave the project untouched and run:  npx retake-dev .
 (Next, Nuxt, React Router, SvelteKit, Astro... too: it puts Retake in front of your dev server.)`)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retake-dev",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Retake: a time machine for your dev server (Vite, Next.js, React Router, Remix, Astro, SvelteKit, Nuxt). Drag back on a timeline and your app is at that moment; branch a new take from there.",
   "homepage": "https://retake-omega.vercel.app",
   "repository": {
@@ -21,6 +21,11 @@
     "./client": {
       "types": "./types/client.d.ts"
     },
+    "./next": {
+      "types": "./types/next.d.ts",
+      "default": "./src/next.js"
+    },
+    "./next-dev": "./src/next-dev.js",
     "./package.json": "./package.json"
   },
   "bin": {

package/src/core.js

@@ -56,6 +56,8 @@ export function shellHtml(options = {}) {
     // No Retake server behind it (a static or serverless deploy): the dock
     // never asks /__retake/ for anything and keeps the session in memory.
     ...(options.server === false ? { server: false } : {}),
+    // The project folder: source paths in notes are given relative to it.
+    ...(options.root ? { root: options.root } : {}),
   }
   return read("shell", "shell.html")
     .replace(
@@ -66,10 +68,21 @@ export function shellHtml(options = {}) {
     .replace("/*CSS*/", () => read("shell", "shell.css"))
     .replace("/*JS*/", () => {
       const files = setFiles("shell")
-      return `;(function () {\n"use strict";\n${files.map((f) => read("shell", f)).join("\n")}\n})();`
+      return `;(function () {\n"use strict";\n${noteTextSource()}\n${files.map((f) => read("shell", f)).join("\n")}\n})();`
     })
 }
 
+// src/note-text.js (the note as text for an agent, shared with `retake mcp`)
+// for the dock: its exports as one const, `NT`.
+export function noteTextSource() {
+  const src = read("note-text.js")
+  const names = new Set()
+  const body = src
+    .replace(/^export (?:async )?(function|const|let) (\w+)/gm, (_, kind, name) => (names.add(name), `${kind} ${name}`))
+    .replace(/^export \{([^}]*)\}\s*$/gm, (_, list) => (list.split(",").forEach((n) => n.trim() && names.add(n.trim())), ""))
+  return `const NT = (function () {\n${body}\nreturn { ${[...names].join(", ")} }\n})();`
+}
+
 // The script a server injects into a page it can't tell apart from the app's
 // own frames (any iframe document). It takes itself out of the DOM first (so an
 // app hydrating the whole document never sees it), then runs the runtime only

package/src/next-dev.js

@@ -0,0 +1,183 @@
+// The dev side of `retake-dev/next` (next.js): Retake from a Next.js app's
+// own middleware (Next 16's proxy.ts, Next 15's middleware.ts with the
+// Node.js runtime), on the app's own dev server. Loaded by next.js at run time
+// in `next dev` only. Per request, like the front server (server/front.js):
+//
+//   x-retake-internal / x-retake-front   passed on (our own fetch below, or
+//                                        Retake's front server in front)
+//   /__retake/*                          the session API (api.js), in <cwd>/.retake
+//   Service-Worker: script               404 (a worker would take the dock's origin over)
+//   a top-level page load                the dock (header marker)
+//   the dock's frame (Sec-Fetch-Dest: iframe)
+//                                        the page, fetched from this server with
+//                                        x-retake-internal, the runtime injected
+//                                        as its first script
+//   anything else                        passed on
+//
+// What a middleware module holds is lost when Next compiles it again, so the
+// token and the session API live on globalThis for the life of the server.
+import crypto from "node:crypto"
+import { Readable } from "node:stream"
+import { injectHtml, runtimeScript, runtimeTag, shellHtml } from "./core.js"
+import { createBus, createSessionHandler, writeServerInfo } from "./server/api.js"
+import { frontRuntime } from "./server/detect.js"
+import { adaptCsp, hostAllowed } from "./server/front.js"
+
+const INTERNAL = "x-retake-internal"
+const FRONT = "x-retake-front"
+const HOP = new Set(["connection", "keep-alive", "proxy-connection", "transfer-encoding", "upgrade", "te", "trailer", "proxy-authenticate", "proxy-authorization", "host", "content-length"])
+const NESTED = new Set(["iframe", "frame"])
+const VARY = "Sec-Fetch-Dest, Sec-Fetch-Mode"
+const KEY = Symbol.for("retake-dev/next")
+
+/**
+ * @typedef {{ root: string, token: string, api: ReturnType<typeof createSessionHandler>, rt: import("../types/index.js").RuntimeConfig, url: string | null }} State
+ */
+/** @returns {State} */
+function state() {
+  const g = /** @type {any} */ (globalThis)
+  if (g[KEY]) return g[KEY]
+  const root = process.env.RETAKE_ROOT || process.cwd()
+  const token = crypto.randomBytes(16).toString("hex")
+  const bus = createBus()
+  return (g[KEY] = { root, token, api: createSessionHandler({ root, token, bus }), rt: { ...frontRuntime("next", root), marker: /** @type {"header"} */ ("header") }, url: null })
+}
+
+// .retake/server.json, for `retake mcp`: the dev server's URL as the browser uses it.
+function announce(s, req) {
+  const url = new URL(req.url).origin
+  if (s.url === url) return
+  const first = !s.url
+  s.url = url
+  writeServerInfo({ root: s.root, url, token: s.token })
+  if (first) console.log(`\n  \x1b[1mRetake\x1b[0m  timeline docked at ${url}\n`)
+}
+
+/**
+ * Retake's answer to a request in `next dev`, or null to pass it on.
+ * @param {Request} req
+ * @returns {Promise<Response | null>}
+ */
+export async function handle(req) {
+  const h = req.headers
+  if (h.get(INTERNAL) === "1" || h.get(FRONT) === "1") return null
+  const url = new URL(req.url)
+  const p = url.pathname
+  const allowed = hostAllowed(h.get("host") ?? url.host)
+  if (p.startsWith("/__retake/")) {
+    if (!allowed) return new Response("Blocked request: this host is not allowed.", { status: 403 })
+    const s = state()
+    announce(s, req)
+    return api(s, req, url)
+  }
+  if (h.get("service-worker") === "script") return new Response("retake: service workers are off while Retake is docked", { status: 404 })
+  const mode = h.get("sec-fetch-mode")
+  const dest = h.get("sec-fetch-dest")
+  if (mode !== "navigate" || !allowed || url.searchParams.get("retake") === "0") return null
+  // The dock: a top-level page load. A cross-site one (an OAuth callback) gets the plain page.
+  if (req.method === "GET" && dest === "document" && h.get("sec-fetch-site") !== "cross-site") {
+    const s = state()
+    announce(s, req)
+    return new Response(shellHtml({ token: s.token, marker: "header", root: s.root }), {
+      headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", vary: VARY },
+    })
+  }
+  if (dest && NESTED.has(dest)) return frame(state(), req, url)
+  return null
+}
+
+// The dock's frame: the page as this server renders it, with the runtime first in <head>.
+async function frame(s, req, url) {
+  const headers = new Headers()
+  for (const [k, v] of req.headers) if (!HOP.has(k) && !/^(accept-encoding|if-none-match|if-modified-since)$/.test(k)) headers.set(k, v)
+  headers.set(INTERNAL, "1")
+  headers.set("accept-encoding", "identity")
+  const body = req.method === "GET" || req.method === "HEAD" ? undefined : await req.arrayBuffer()
+  const r = await fetch(url, { method: req.method, headers, body, redirect: "manual", cache: "no-store" })
+  const out = new Headers(r.headers)
+  const type = out.get("content-type") || ""
+  const bodyless = req.method === "HEAD" || r.status === 204 || r.status === 304 || !r.body
+  if (!/^\s*text\/html\b/i.test(type) || bodyless) return new Response(r.body, { status: r.status, statusText: r.statusText, headers: out })
+  const script = runtimeScript(s.rt)
+  /** @type {string | null} */
+  let nonce = null
+  const csp = out.get("content-security-policy")
+  if (csp) {
+    const a = adaptCsp(csp, script)
+    nonce = a.nonce
+    if (a.csp) out.set("content-security-policy", a.csp)
+    else out.delete("content-security-policy")
+  }
+  // Framing: SAMEORIGIN already lets the dock (same origin) frame it.
+  const xfo = (out.get("x-frame-options") || "").toLowerCase()
+  if (xfo && xfo !== "sameorigin") out.delete("x-frame-options")
+  // (fetch has decoded the body already.)
+  for (const k of ["content-encoding", "content-length", "etag"]) out.delete(k)
+  out.set("cache-control", "no-store")
+  out.set("vary", VARY)
+  if (!/charset=/i.test(type)) out.set("content-type", `${type.trim()}; charset=utf-8`)
+  const t = injectHtml(runtimeTag({ script, nonce }))
+  const src = Readable.fromWeb(/** @type {any} */ (r.body))
+  src.on("error", (err) => t.destroy(err))
+  src.pipe(t)
+  return new Response(/** @type {any} */ (Readable.toWeb(t)), { status: r.status, statusText: r.statusText, headers: out })
+}
+
+// The session API (api.js's Node handler) for a web Request: a Node-shaped
+// request and response around it. Event streams stay open until the browser
+// goes (the response body is cancelled).
+function api(s, req, url) {
+  return new Promise((resolve) => {
+    const nodeReq = /** @type {any} */ (req.body ? Readable.fromWeb(/** @type {any} */ (req.body)) : Readable.from([]))
+    nodeReq.method = req.method
+    nodeReq.url = url.pathname + url.search
+    nodeReq.headers = Object.fromEntries(req.headers)
+    /** @type {ReadableStreamDefaultController<Uint8Array> | null} */
+    let ctl = null
+    let closed = false
+    const stream = new ReadableStream({
+      start(c) {
+        ctl = c
+      },
+      cancel() {
+        closed = true
+        nodeReq.emit("close")
+      },
+    })
+    const head = new Headers()
+    let sent = false
+    const res = {
+      statusCode: 200,
+      setHeader: (k, v) => head.set(k, String(v)),
+      getHeader: (k) => head.get(k),
+      writeHead(code, h) {
+        res.statusCode = code
+        for (const [k, v] of Object.entries(h || {})) head.set(k, String(v))
+        start()
+        return res
+      },
+      write(chunk) {
+        start()
+        if (!closed && chunk != null) ctl?.enqueue(typeof chunk === "string" ? new TextEncoder().encode(chunk) : new Uint8Array(chunk))
+        return true
+      },
+      end(chunk) {
+        if (chunk != null) res.write(chunk)
+        else start()
+        if (!closed) {
+          closed = true
+          ctl?.close()
+        }
+        return res
+      },
+    }
+    function start() {
+      if (sent) return
+      sent = true
+      resolve(new Response(stream, { status: res.statusCode, headers: head }))
+    }
+    Promise.resolve(s.api(nodeReq, res)).catch((err) => {
+      if (!sent) resolve(new Response(JSON.stringify({ error: err.message }), { status: 500, headers: { "content-type": "application/json" } }))
+    })
+  })
+}

package/src/next.js

@@ -0,0 +1,81 @@
+// Retake on a Next.js app's own dev server, from its middleware: Next 16's
+// `proxy.ts` or Next 15's `middleware.ts`.
+//
+//   export { default } from "retake-dev/next"
+//
+// Next 15's middleware.ts needs the Node.js runtime (Retake reads its files and
+// keeps .retake/ on disk), and imports it (Next 15.5's Turbopack puts a
+// re-exported default on the Edge runtime):
+//
+//   import retake from "retake-dev/next"
+//   export default retake
+//   export const config = { runtime: "nodejs" }
+//
+// With a middleware of your own:
+//
+//   import { withRetake } from "retake-dev/next"
+//   export default withRetake(yourMiddleware)
+//
+// In `next dev` it does what the front server (server/front.js) does on a port
+// of its own: a top-level page load gets the dock, the dock's frame gets the
+// page with the runtime as its first script, /__retake/* is the session API,
+// and everything else passes through. Anywhere else (next build, next start)
+// it does nothing: it hands every request on and never loads the rest of
+// Retake.
+//
+// This file stays free of Node imports, so it bundles into any middleware. The
+// work is in next-dev.js, loaded at run time in dev only, from node_modules as
+// it is: never bundled (it reads the runtime and the dock from its own files).
+
+const DEV = process.env.NODE_ENV === "development"
+
+/** @type {Promise<typeof import("./next-dev.js")> | null} */
+let loading = null
+let warned = false
+const devHandler = () => (loading ||= import(/* webpackIgnore: true */ /* turbopackIgnore: true */ "retake-dev/next-dev"))
+
+/**
+ * Retake's answer to this request, or undefined to let it through.
+ * @param {Request} req
+ * @returns {Promise<Response | undefined>}
+ */
+export async function retakeResponse(req) {
+  if (!DEV) return undefined
+  if (typeof (/** @type {any} */ (globalThis).EdgeRuntime) === "string") {
+    if (!warned) console.warn('[retake] the timeline needs the Node.js runtime: add `export const config = { runtime: "nodejs" }` to middleware.ts')
+    warned = true
+    return undefined
+  }
+  try {
+    return (await (await devHandler()).handle(req)) || undefined
+  } catch (err) {
+    console.error("[retake]", err instanceof Error ? err.message : err)
+    return undefined
+  }
+}
+
+/**
+ * Wraps a middleware of your own: Retake answers first (in dev, for page loads
+ * and /__retake/*), everything else goes to yours.
+ * @template {(...args: any[]) => any} M
+ * @param {M} [middleware]
+ * @returns {(req: Request, event?: any) => Promise<any>}
+ */
+export function withRetake(middleware) {
+  return async function retakeMiddleware(req, event) {
+    if (DEV) {
+      const res = await retakeResponse(req)
+      if (res) return res
+    }
+    return middleware ? middleware(req, event) : undefined
+  }
+}
+
+export default withRetake()
+
+// Next reads a middleware's `config` from the file itself (it can't be
+// re-exported), so there's none here. Without one Next runs it for every
+// request, and it hands everything but page loads and /__retake/* straight on.
+// A matcher of your own needs these two entries, as written:
+//   "/__retake/:path*",
+//   { source: "/((?!_next/static|_next/image).*)", has: [{ type: "header", key: "sec-fetch-mode", value: "navigate" }] },