playthrough 0.5.1 → 0.6.0

package/INSTRUCTIONS.md

@@ -6,7 +6,7 @@ to its end; each command then says what's next.
   playthrough start <review>             once its flows are written, try the setup and keep Before: the app as it is
   playthrough record <review>            record the round being worked on, every flow, the way a person would use it
   playthrough wait <review>              hand the round over, then wait for the notes to answer
-  playthrough walk <review>              walk the person's steps in the app again, on the app as it is now
+  playthrough forks <review>             run each fork of a note made in the app, on the app as it is now
   playthrough open [<review>]            open the viewer on this machine
 
 THE LOOP
@@ -28,12 +28,16 @@ THE LOOP
    background, so you're told when it ends. Each note comes with a picture of what it's on, or what the person did in
    the app. Change the app, record the next round, and answer each note in its round.json, under "replies", in its
    "words": its "on" is where Playthrough found the note's thing on this round, so leave it. Where the answer moves,
-   like an animation, add "watch": "<the title of the step it's seen in>". For a note made in the app, record walks the
-   person's steps again and puts your answer where they lead: answer it in words, not with a new flow, and check your
-   fix with playthrough walk <review>. Where their steps stop short, fix that, or say why they changed.
+   like an animation, add "watch": "<the title of the step it's seen in>". A note made in the app comes with what the
+   person did there: write that as a fork of the flow they took over (FORKS, below), and record puts your answer on it.
 
 The person can only judge what the flows show, so keep them true to how a person uses the app.
 
+A bug you can't make happen is still a round to hand over: record the flow that does what the report says, give it a
+"line" in round.json saying you couldn't make it happen and how you tried, and hand it over. The person can take the
+flow over where it goes wrong and show you: what they do there comes back as a note made in the app, and its fork, run
+every round, shows you the bug and them your fix.
+
 THE APP
 
 The first time, add playthrough to the app's devDependencies with the app's own package manager, and run
@@ -56,7 +60,8 @@ another at its address, takes the address it always has, or a copy on a port of
 
 Flows run several at once. Where a page shows what every run made, as a blog's index lists every post, add
 "oneAtATime": true. Recording on Before sets your work aside with git stash for a minute, puts the app as it was in its
-place, with playthrough/ as it is now, and puts your work back after, even when Playthrough is stopped.
+place, with playthrough/ as it is now, and puts your work back after, even when Playthrough is stopped; anything saved
+meanwhile is kept in a stash of its own.
 
 FLOWS
 
@@ -91,6 +96,23 @@ something outside the app that mustn't happen again, like sending an email, say
 
   test("Invite Sam", { annotation: { type: "reaches outside", description: "sends Sam an email" } }, async ({ page }) => {
 
+FORKS
+
+Where the person took a flow over in the app and made a note there, what they did is yours to write, as a fork of that
+flow, in its file, after it: steps as a flow's, by role and label, for the notes it shows:
+
+  test.fork("Remind Alder Dental", { notes: ["isikhse8"] }, async ({ page }) => {
+    await test.step("Open the reminder", async () => {
+      await page.getByRole("row", { name: /Alder Dental/ }).click();
+      await page.getByRole("button", { name: "Write a reminder" }).click();
+    });
+  });
+
+Record runs the flow to where they took it over, then the fork, and puts your answer on what the note is on, where the
+fork first shows it. It's run every round until its notes are settled, and the person watches it as a fork off the flow,
+not a flow of its own: keep it doing what they did, on the app as it is now. playthrough forks <review> runs it while you
+work. A round whose note has no fork, or whose fork fails, isn't recorded.
+
 WHAT EVERY FLOW STARTS FROM
 
 A flow has to start from the same place every round, or the comparison finds changes nobody made. Playthrough starts

package/README.md

@@ -22,7 +22,7 @@ The agent does the rest. The first time, it adds Playthrough to your app and wri
 npx playthrough open
 ```
 
-Reviews stay in `.playthrough/` in your app's repo, recordings and all; nothing is uploaded. Playthrough needs Node 24 or later.
+Reviews stay in `.playthrough/` in your app's repo, recordings and all; nothing is uploaded. Playthrough needs Node 22.18 or later.
 
 You can teach your agent Playthrough once, so “Show me this change” is enough from then on:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playthrough",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Review what your coding agent built in your web app by watching recordings of it.",
   "keywords": [
     "coding-agent",
@@ -25,7 +25,7 @@
     "directory": "packages/cli"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=22.18"
   },
   "bin": {
     "playthrough": "src/playthrough.js"

package/src/{flows-vi0amwSo.js → flows-CbrwgoHB.js}

@@ -1,4 +1,4 @@
-import { A as quote, b as Reviews, h as readingsOf, k as list, m as glimpsesOf, p as firstLine, y as Refused } from "./reporter-S9fOk0za.js";
+import { A as quote, b as Reviews, h as readingsOf, k as list, m as glimpsesOf, p as firstLine, y as Refused } from "./reporter-DlS7qehW.js";
 import * as modules from "node:module";
 import { createRequire } from "node:module";
 import { existsSync, readFileSync, watch, writeFileSync } from "node:fs";
@@ -239,7 +239,9 @@ async function setupIn(file, written) {
 	if (!existsSync(file)) return {};
 	const href = pathToFileURL(file).href;
 	asModule(href);
-	const module = await import(`${href}${written ? `?${written}` : ""}`);
+	const module = await import(`${href}${written ? `?${written}` : ""}`).catch((error) => {
+		throw twoPlaywrights(error, file) ?? error;
+	});
 	const inner = typeof module.default === "object" ? module.default : void 0;
 	const use = module.use ?? inner?.use;
 	const ours = Object.keys(use ?? {}).filter((option) => OURS.includes(option));
@@ -252,6 +254,16 @@ async function setupIn(file, written) {
 		...use && { use }
 	};
 }
+function twoPlaywrights(error, file) {
+	if (!/Requiring @playwright\/test second time/.test(String(error?.message))) return;
+	const version = (from) => {
+		try {
+			return modules.createRequire(from)("@playwright/test/package.json").version;
+		} catch {}
+	};
+	const theirs = version(file);
+	return new Refused([`playthrough/setup.ts loads the app's own Playwright${theirs ? ` (${theirs})` : ""} beside Playthrough's (${version(import.meta.url)}), and Playwright can't run twice at once.`, `Import only types from @playwright/test there (import type { Page } from "@playwright/test"), and expect, if it needs it, from playthrough/test. Then run this again.`]);
+}
 const setups = /* @__PURE__ */ new Set();
 function asModule(href) {
 	if (!setups.size) modules.registerHooks({ load: (url, context, next) => next(url, setups.has(url.split("?")[0]) ? {
@@ -928,6 +940,26 @@ const elementOf$1 = (thing, name) => ({
 	name: thing.name || name,
 	...thing.node !== void 0 && { node: thing.node }
 });
+function sameWords(one, other) {
+	const [few, many] = [wordsOf(one), wordsOf(other)].sort((a, b) => a.length - b.length);
+	return !few.length || few.filter((word) => many.includes(word)).length * 2 >= few.length;
+}
+const wordsOf = (name) => name.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+function firstShown(element, seen) {
+	const noted = wordsOf(element.name);
+	if (!noted.length) return void 0;
+	const closeness = (thing) => {
+		const words = wordsOf(thing.name);
+		return words.filter((word) => noted.includes(word)).length / Math.max(words.length, noted.length);
+	};
+	for (const glimpse of seen.toSorted((a, b) => a.at - b.at)) {
+		const thing = glimpse.things.filter((thing) => thing.role === element.role && sameWords(thing.name, element.name)).toSorted((a, b) => closeness(b) - closeness(a))[0];
+		if (thing) return {
+			at: glimpse.at,
+			element: elementOf$1(thing, element.name)
+		};
+	}
+}
 // src/changes.ts
 const TABLES = /^(table|grid|treegrid|listbox)$/;
 const REFLOWS = /^(dialog|alertdialog|status|alert|menu|box)$/;
@@ -2228,7 +2260,7 @@ async function writtenNow(repo) {
 }
 // src/flows.ts
 const recorder = join(dirname(createRequire(import.meta.url).resolve("@rrweb/record")), "record.umd.min.cjs");
-const WALKED = "walked.json";
+const FORK_RAN = "fork.json";
 const ALONGSIDE = Symbol.for("playthrough: flows taken over here");
 const REACHES_OUTSIDE = "reaches outside";
 const waitsFor = ({ before }) => before ? 3e3 : 1e4;
@@ -2398,7 +2430,7 @@ async function runOnce(run) {
 		await rm(folder, { recursive: true });
 	}
 }
-async function walkFork(repo, id, walk) {
+async function runFork(repo, id, fork) {
 	const app = await repo.app();
 	const { started } = await repo.reviews.get(id);
 	const folder = await mkdtemp(join(tmpdir(), "playthrough-"));
@@ -2412,20 +2444,19 @@ async function walkFork(repo, id, walk) {
 			before: false,
 			taken: [],
 			started,
-			walk
+			fork
 		});
-		const text = await readFile(join(folder, WALKED), "utf8").catch(() => void 0);
+		const text = await readFile(join(folder, FORK_RAN), "utf8").catch(() => void 0);
 		if (!text) return void 0;
-		const walked = JSON.parse(text);
-		const files = await Promise.all([...new Set(Object.values(walked.assets))].map(async (name) => ({
+		const ran = JSON.parse(text);
+		const files = await Promise.all([...new Set(Object.values(ran.assets))].map(async (name) => ({
 			name,
 			bytes: await readFile(join(folder, name))
 		})));
-		const pictures = await Promise.all(walk.look.map((_, i) => readFile(join(folder, `look-${i}.png`)).catch(() => void 0)));
 		return {
-			...walked,
+			...ran,
 			files,
-			pictures
+			picture: await readFile(join(folder, "end.png")).catch(() => void 0)
 		};
 	} finally {
 		await rm(folder, {
@@ -2469,4 +2500,4 @@ async function playwright(run) {
 		});
 	});
 }
-export { repo as A, changes as C, personIn as D, make as E, thisCommand as M, pausedAt as N, setupIn as O, stopApp as S, giveBackLeft as T, compareWithEarlier as _, failedAt as a, keepRunning as b, isFlow as c, runFlows as d, waitsFor as f, writtenNow as g, trySetup as h, called as i, stillAt as j, copies as k, makeFlowsFolder as l, whereItStopped as m, REACHES_OUTSIDE as n, flowsOf as o, walkFork as p, WALKED as r, howToWriteFlows as s, ALONGSIDE as t, recorder as u, placeIn as v, firstOf$1 as w, serves as x, shownAt as y };
+export { setupIn as A, serves as C, giveBackLeft as D, firstOf$1 as E, pausedAt as F, repo as M, stillAt as N, make as O, thisCommand as P, keepRunning as S, changes as T, compareWithEarlier as _, failedAt as a, sameWords as b, isFlow as c, runFlows as d, runFork as f, writtenNow as g, trySetup as h, called as i, copies as j, personIn as k, makeFlowsFolder as l, whereItStopped as m, FORK_RAN as n, flowsOf as o, waitsFor as p, REACHES_OUTSIDE as r, howToWriteFlows as s, ALONGSIDE as t, recorder as u, firstShown as v, stopApp as w, shownAt as x, placeIn as y };