agent-screenplay 0.1.2 → 0.1.4

package/README.md

@@ -1,5 +1,7 @@
 # Screenplay
 
+https://github.com/user-attachments/assets/dd9898da-4900-4a91-8620-57a860c46093
+
 **Screen Studio-quality screen recordings, made by your AI agent.**
 
 Ask Claude Code, Codex, Cursor or any agent: *"Make a video that shows how human handoff works"*. The agent explores your app and writes a short **scenario**; Screenplay plays it in a browser (or a desktop app), films it, and edits the video like Screen Studio would: smooth cursor, automatic zooms that follow the action, click effects, callouts, spotlight, captions, title cards, and an optional voice-over.
@@ -62,7 +64,7 @@ Requirements: Node 20+. ffmpeg and the drawing library ship with the package.
 - **Targets** name elements the way people see them: `text=…`, `role=button[name='…']`, `label=…`, `placeholder=…`, `testid=…`, `css=…` (web only), `at=x,y` (desktop apps without accessible elements only).
 - **Actions**: `goto`, `click`, `type`, `press`, `hover`, `scroll`, `select`, `wait`, `pause`.
 - **Direction**: `title` and `end` cards, `callout` (a bubble pointing at an element), `highlight` (spotlight), `zoomTo`, and on any step `say` (caption and voice), `zoom`, `hold`.
-- **Style**: background preset (soft light gradients: `dawn`, `iris`, `citrus`, `apricot`, `coral`, `blaze`, `cloud`, `glacier`, `tide`, `meadow`), your own gradient, a color or an image; padding, corner radius, shadow, cursor style, maximum zoom, browser frame, accent color. See [Style](#style).
+- **Style**: background preset (soft light gradients: `dawn`, `iris`, `citrus`, `apricot`, `coral`, `blaze`, `cloud`, `glacier`, `tide`, `meadow`), your own gradient, a color or an image; padding, corner radius, shadow, the cursor (`arrow` by default, a rounded arrow in the accent color; `macos`, `dot`) and its click effect (`ripple` by default; `rays`, `confetti`, `sparkle`), maximum zoom, browser frame, accent color. See [Style](#style).
 - **Output**: 1920×1080 at 30 fps by default; any size up to 4K, 24 to 60 fps, optional GIF.
 
 The full format is the JSON schema in [`schema/scenario.schema.json`](schema/scenario.schema.json) (`npx agent-screenplay schema`), and the agent guide in [`skills/screenplay/SKILL.md`](skills/screenplay/SKILL.md). Examples are in [`examples/`](examples).
@@ -126,6 +128,8 @@ Use `"app": "<name>"` instead of `"url"`. The steps are played through the opera
 
 Desktop recordings need a real screen: they cannot run in a headless container. Websites can.
 
+While Screenplay drives the computer, a pill at the top of the screen says so ("Screenplay is recording", or "rehearsing" during a check), with a **Stop** button that ends the run at once. The pill is left out of the capture, so it is never in the video. macOS and Windows; `SCREENPLAY_INDICATOR=0` turns it off.
+
 ### The whole screen
 
 `"screen": true` films the whole main screen instead of one window, for videos that go from one app to another or use the menu bar. `{ "open": "<app>" }` launches an app or brings it to the front, a step's `"app"` acts in another app, and `"surface": "menubar"` (or `menu`, `sheet`, `popover`, `alert`) finds elements outside the app's window. Everything on screen is filmed, desktop icons and notifications included: tidy the screen first; on macOS `"hideOthers": true` hides the other apps.
@@ -155,6 +159,20 @@ npm test                 # unit tests
 npm run test:e2e         # records a real scenario in headless Chromium and talks to the MCP server
 ```
 
+### Releasing
+
+```bash
+npm version patch --no-git-tag-version   # or minor / major; also updates src/version.ts
+```
+
+Merge that change, then tag the commit on main:
+
+```bash
+git tag v0.1.4 origin/main && git push origin v0.1.4
+```
+
+The tag starts `.github/workflows/release.yml`. It checks that the tag matches the version and is on main, runs the tests, publishes to npm (with provenance) and creates the GitHub release with notes from the merged pull requests. A version like `0.2.0-beta.1` goes to npm's `next` tag. Creating a release in GitHub's UI with a new tag works too.
+
 `examples/demo-app` is a small web app for trying scenarios; `examples/desktop-app/notes.py` is a GTK app for desktop recording on Linux.
 
 ## License

package/assets/editor/index.html

@@ -248,6 +248,14 @@ kbd { font: 11px ui-monospace, Menlo, monospace; color: var(--faint); }
         <div class="row"><span>Shadow</span><button class="switch" id="shadow" role="switch" aria-label="Shadow"></button></div>
         <div class="row" style="margin-top:16px"><span>Intro &amp; outro cards</span><button class="switch" id="cards" role="switch" aria-label="Intro and outro cards"></button></div>
       </div>
+
+      <div class="section">
+        <p class="label">Cursor</p>
+        <div class="seg" id="cursorKind"><span class="pill"></span><button data-k="arrow">Arrow</button><button data-k="macos">macOS</button><button data-k="dot">Dot</button></div>
+        <p class="label" style="margin-top:16px">Click</p>
+        <div class="seg" id="clickKind"><span class="pill"></span><button data-k="ripple">Ripple</button><button data-k="rays">Rays</button><button data-k="confetti">Confetti</button><button data-k="sparkle">Sparkle</button></div>
+        <p class="note on" style="display:block">Shown in the video: Render to see them.</p>
+      </div>
     </div>
 
     <div class="foot">
@@ -284,7 +292,7 @@ async function load() {
   S = await (await api("/api/state")).json();
   $("name").textContent = S.name;
   const eff = { ...S.defaults, ...S.projectStyle, ...S.scenarioStyle };
-  style = { background: eff.background, padding: eff.padding, radius: eff.radius, shadow: eff.shadow, cards: eff.cards };
+  style = { background: eff.background, padding: eff.padding, radius: eff.radius, shadow: eff.shadow, cards: eff.cards, cursor: eff.cursor, click: eff.click };
   if (kindOf(style.background) === "image") imageRef = { path: style.background, from: S.scenarioStyle.background !== undefined ? "scenario" : "project" };
   saved = JSON.stringify(style);
   // A video that already has its own look keeps it; otherwise the look is for the whole project.
@@ -462,6 +470,8 @@ $("rad").oninput = (e) => { live(); style.radius = +e.target.value; change(); };
 $("shadow").onclick = () => { style.shadow = !style.shadow; change(); };
 // Cards are not in the frame preview: the rendered video shows them.
 $("cards").onclick = () => { style.cards = !style.cards; change(); };
+$("cursorKind").querySelectorAll("button").forEach((b) => (b.onclick = () => { style.cursor = b.dataset.k; change(); }));
+$("clickKind").querySelectorAll("button").forEach((b) => (b.onclick = () => { style.click = b.dataset.k; change(); }));
 $("reset").onclick = () => {
   style = { ...S.defaults };
   setKind(kindOf(style.background), true);
@@ -534,6 +544,8 @@ function sync() {
   }
   $("shadow").setAttribute("aria-checked", String(style.shadow));
   $("cards").setAttribute("aria-checked", String(style.cards));
+  setSeg($("cursorKind"), style.cursor);
+  setSeg($("clickKind"), style.click);
   $("reset").disabled = JSON.stringify(style) === JSON.stringify({ ...S.defaults });
   // The recording keeps its shape: when it is not the video's, the background shows on two sides even with no padding.
   const cap = S.capture || { width: 1440, height: 900 }, r = cap.width / cap.height, R = S.output.width / S.output.height;

package/assets/indicator/macos.js

@@ -0,0 +1,100 @@
+// The pill that tells the person at the Mac that Screenplay is driving it (and filming).
+// Run with `osascript -l JavaScript macos.js <label> <parent pid> [selftest]`.
+// It is left out of screen captures (NSWindowSharingNone), stays on top on every Space,
+// never takes focus, and survives "Hide others". Stop exits with code 3; the pill also
+// quits by itself when the Screenplay process that started it is gone.
+ObjC.import("Cocoa");
+ObjC.import("stdlib");
+ObjC.import("signal");
+
+function run(argv) {
+  const text = argv[0] || "Screenplay is recording";
+  const parent = Number(argv[1] || 0);
+  const selftest = argv[2] === "selftest";
+
+  const app = $.NSApplication.sharedApplication;
+  app.setActivationPolicy($.NSApplicationActivationPolicyAccessory);
+  app.finishLaunching;
+
+  ObjC.registerSubclass({
+    name: "SPStopTarget",
+    methods: { "stop:": { types: ["void", ["id"]], implementation: () => $.exit(3) } },
+  });
+  const target = $.SPStopTarget.alloc.init;
+
+  const rgba = (r, g, b, a) => $.NSColor.colorWithSRGBRedGreenBlueAlpha(r / 255, g / 255, b / 255, a);
+  const H = 36;
+
+  const label = $.NSTextField.labelWithString(text);
+  label.font = $.NSFont.systemFontOfSizeWeight(13, 0.23);
+  label.textColor = rgba(255, 255, 255, 0.95);
+  label.sizeToFit;
+  const lw = Math.ceil(label.frame.size.width);
+
+  const stop = $.NSButton.buttonWithTitleTargetAction("Stop", target, "stop:");
+  stop.bezelStyle = $.NSBezelStyleRounded;
+  stop.controlSize = $.NSControlSizeSmall;
+  stop.font = $.NSFont.systemFontOfSizeWeight(11, 0.3);
+  stop.sizeToFit;
+  const bw = Math.ceil(stop.frame.size.width);
+  const bh = Math.ceil(stop.frame.size.height);
+
+  const W = 14 + 8 + 9 + lw + 10 + bw + 8;
+  const vf = $.NSScreen.mainScreen.visibleFrame;
+  const rect = $.NSMakeRect(vf.origin.x + Math.round((vf.size.width - W) / 2), vf.origin.y + vf.size.height - H - 10, W, H);
+
+  const panel = $.NSPanel.alloc.initWithContentRectStyleMaskBackingDefer(rect, $.NSWindowStyleMaskBorderless | $.NSWindowStyleMaskNonactivatingPanel, $.NSBackingStoreBuffered, false);
+  panel.appearance = $.NSAppearance.appearanceNamed($.NSAppearanceNameDarkAqua);
+  panel.opaque = false;
+  panel.backgroundColor = $.NSColor.clearColor;
+  panel.hasShadow = true;
+  panel.level = $.NSStatusWindowLevel;
+  panel.sharingType = $.NSWindowSharingNone;
+  panel.canHide = false;
+  panel.hidesOnDeactivate = false;
+  panel.movableByWindowBackground = true;
+  panel.collectionBehavior =
+    $.NSWindowCollectionBehaviorCanJoinAllSpaces | $.NSWindowCollectionBehaviorStationary | $.NSWindowCollectionBehaviorIgnoresCycle | $.NSWindowCollectionBehaviorFullScreenAuxiliary;
+
+  // NSBox draws rounded fills without Core Animation colors, which JXA cannot pass.
+  const box = (frame, fill, radius, border) => {
+    const b = $.NSBox.alloc.initWithFrame(frame);
+    b.boxType = $.NSBoxCustom;
+    b.titlePosition = $.NSNoTitle;
+    b.contentViewMargins = $.NSMakeSize(0, 0);
+    b.fillColor = fill;
+    b.cornerRadius = radius;
+    b.borderWidth = border ? 1 : 0;
+    b.borderColor = border || $.NSColor.clearColor;
+    return b;
+  };
+  const pill = box($.NSMakeRect(0, 0, W, H), rgba(24, 24, 27, 0.92), H / 2, rgba(255, 255, 255, 0.14));
+  const dot = box($.NSMakeRect(14, (H - 8) / 2, 8, 8), rgba(255, 69, 58, 1), 4);
+
+  label.setFrameOrigin($.NSMakePoint(14 + 8 + 9, Math.round((H - label.frame.size.height) / 2)));
+  stop.setFrameOrigin($.NSMakePoint(W - bw - 8, Math.round((H - bh) / 2)));
+
+  const view = $.NSView.alloc.initWithFrame($.NSMakeRect(0, 0, W, H));
+  view.addSubview(pill);
+  view.addSubview(dot);
+  view.addSubview(label);
+  view.addSubview(stop);
+  panel.contentView = view;
+  panel.orderFrontRegardless;
+
+  if (selftest) stop.performClick(null);
+
+  // The dot blinks softly; the loop also handles clicks and watches the parent process.
+  let lit = true;
+  let next = Date.now();
+  for (;;) {
+    const ev = app.nextEventMatchingMaskUntilDateInModeDequeue($.NSEventMaskAny, $.NSDate.dateWithTimeIntervalSinceNow(0.25), $.NSDefaultRunLoopMode, true);
+    if (ev && !ev.isNil()) app.sendEvent(ev);
+    if (Date.now() >= next) {
+      lit = !lit;
+      dot.animator.alphaValue = lit ? 1 : 0.3;
+      next = Date.now() + 800;
+      if (parent && $.kill(parent, 0) !== 0) $.exit(0);
+    }
+  }
+}

package/assets/indicator/windows.ps1

@@ -0,0 +1,75 @@
+# The pill that tells the person at the PC that Screenplay is driving it (and filming).
+# Run with: powershell -NoProfile -ExecutionPolicy Bypass -File windows.ps1 <label> <parent pid> [selftest]
+# It is left out of screen captures (WDA_EXCLUDEFROMCAPTURE), stays on top, never takes focus.
+# Stop exits with code 3; the pill also quits when the Screenplay process that started it is gone.
+param([string]$Label = "Screenplay is recording", [int]$ParentPid = 0, [string]$Mode = "")
+
+Add-Type -ReferencedAssemblies System.Windows.Forms, System.Drawing -TypeDefinition @"
+using System;
+using System.Diagnostics;
+using System.Drawing;
+using System.Drawing.Drawing2D;
+using System.Runtime.InteropServices;
+using System.Windows.Forms;
+
+public class ScreenplayPill : Form {
+  [DllImport("user32.dll")] static extern bool SetWindowDisplayAffinity(IntPtr hWnd, uint affinity);
+  const int WS_EX_TOPMOST = 0x8, WS_EX_TOOLWINDOW = 0x80, WS_EX_NOACTIVATE = 0x8000000;
+  readonly int parent;
+  bool lit = true;
+  readonly Panel dot;
+  public readonly Button StopButton;
+
+  public ScreenplayPill(string text, int parentPid) {
+    parent = parentPid;
+    FormBorderStyle = FormBorderStyle.None;
+    ShowInTaskbar = false;
+    TopMost = true;
+    StartPosition = FormStartPosition.Manual;
+    BackColor = Color.FromArgb(24, 24, 27);
+    Font = new Font("Segoe UI Semibold", 9.75f);
+    int h = 36;
+
+    dot = new Panel { BackColor = Color.FromArgb(255, 69, 58), Size = new Size(8, 8), Location = new Point(14, (h - 8) / 2) };
+    var dp = new GraphicsPath(); dp.AddEllipse(0, 0, 8, 8); dot.Region = new Region(dp);
+
+    var label = new Label { Text = text, ForeColor = Color.White, AutoSize = true, BackColor = Color.Transparent };
+    label.Location = new Point(31, (h - label.PreferredHeight) / 2);
+
+    StopButton = new Button { Text = "Stop", FlatStyle = FlatStyle.Flat, ForeColor = Color.White, BackColor = Color.FromArgb(60, 60, 66), Size = new Size(52, 24), TabStop = false };
+    StopButton.FlatAppearance.BorderSize = 0;
+    StopButton.Click += (s, e) => Environment.Exit(3);
+
+    int w = 31 + label.PreferredWidth + 10 + 52 + 8;
+    Size = new Size(w, h);
+    StopButton.Location = new Point(w - 52 - 8, (h - 24) / 2);
+    var area = Screen.PrimaryScreen.WorkingArea;
+    Location = new Point(area.X + (area.Width - w) / 2, area.Y + 10);
+    var path = new GraphicsPath();
+    path.AddArc(0, 0, h, h, 90, 180); path.AddArc(w - h, 0, h, h, 270, 180); path.CloseFigure();
+    Region = new Region(path);
+    Controls.Add(dot); Controls.Add(label); Controls.Add(StopButton);
+
+    var timer = new Timer { Interval = 800 };
+    timer.Tick += (s, e) => {
+      lit = !lit;
+      dot.BackColor = lit ? Color.FromArgb(255, 69, 58) : Color.FromArgb(110, 40, 38);
+      if (parent > 0) { try { Process.GetProcessById(parent); } catch (ArgumentException) { Environment.Exit(0); } }
+    };
+    timer.Start();
+  }
+
+  protected override bool ShowWithoutActivation { get { return true; } }
+  protected override CreateParams CreateParams {
+    get { var cp = base.CreateParams; cp.ExStyle |= WS_EX_TOPMOST | WS_EX_TOOLWINDOW | WS_EX_NOACTIVATE; return cp; }
+  }
+  protected override void OnHandleCreated(EventArgs e) {
+    base.OnHandleCreated(e);
+    SetWindowDisplayAffinity(Handle, 0x11); // WDA_EXCLUDEFROMCAPTURE (Windows 10 2004+)
+  }
+}
+"@
+
+$pill = New-Object ScreenplayPill($Label, $ParentPid)
+if ($Mode -eq "selftest") { $pill.add_Shown({ $pill.StopButton.PerformClick() }) }
+[System.Windows.Forms.Application]::Run($pill)

package/dist/drivers/desktop.d.ts

@@ -21,14 +21,36 @@ interface Envelope<T = any> {
         details?: unknown;
     };
 }
+/** The error a run ends with when the person presses Stop on the pill. */
+export declare class StoppedError extends Error {
+    constructor();
+}
+/**
+ * Stop for one run: `pause` is a sleep that Stop ends at once (its timer cleared, so nothing keeps
+ * the process alive), `signal` rejects with StoppedError on Stop, `check` throws once stopped.
+ */
+export declare function createStopper(): {
+    readonly stopped: boolean;
+    signal: Promise<never>;
+    stop(): void;
+    check(): void;
+    pause(seconds: number): Promise<void>;
+};
 export declare class AgentDesktop {
     private bin;
     private session?;
+    private stopped;
+    private abort;
     constructor();
     static locate(): string;
+    /** After Stop, every call fails at once and calls in flight are killed; only ending the session still runs. */
+    stop(): void;
     call<T = any>(args: string[], opts?: {
         allowFail?: boolean;
     }): Promise<Envelope<T>>;
+    invoke<T = any>(args: string[], opts?: {
+        allowFail?: boolean;
+    }, signal?: AbortSignal): Promise<Envelope<T>>;
     startSession(): Promise<void>;
     endSession(): Promise<void>;
 }