feat: browser overlay debugger for stepping through Play acts

[rickcedwhat-ai]

Idea

A floating browser UI injected into the page during a test that lets you step through Play acts one at a time — Next Act, Skip, and Abort controls visible directly in the browser viewport.

Why

Playwright Inspector (used by page.pause()) gives DOM inspection and locator playground but no awareness of Play/Act structure. A Play-aware overlay would show the current act name, what's coming next, and let you skip an act or abort the play — all without leaving the browser.

How it would work

1. Before each act, inject a floating panel via page.evaluate() with Next / Skip / Abort buttons
2. Test blocks waiting for a signal using SharedArrayBuffer + Atomics.wait() (same mechanism Playwright's own pause uses)
3. Browser button clicks write to the shared buffer via Atomics.notify(), unblocking the test
4. Panel shows current act name, kind (act / detect / attempt / cleanup), and a queue of upcoming acts

API

await play.run(label, ctx, { debugOverlay: true });

Or a global toggle for an entire test:

const director = new Director({ debugOverlay: true });

Related

• Option 1 (quick): RunOptions.debug — calls page.pause() between acts, uses Playwright Inspector. Simpler, no custom UI. Already implemented.
• This issue is Option 2: the full custom overlay for a Play-aware step-through experience.

[coderabbitai]

🔗 Related PRs

#12 - feat: implement Play, Playbook, Director, SyncStrategy [merged]
#26 - feat(play)!: third-arg outcome and Play.run lastOutcome [merged]
#28 - feat(playbook): withCtx(name, ctx) log labels and bindPlaybooks { name } [merged]
#41 - feat: poc sync retry loop and timeout fixes [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[rickcedwhat-ai]

Blocked by #55 — this belongs in the future RBAC/playbook library, not in the core sugar primitives.