@mrkt_frwd/reel 0.1.0 → 0.2.0

package/README.md

@@ -1,17 +1,71 @@
 # @mrkt_frwd/reel
 
-Drive a real browser from a declarative script and record it.
+**Drive a real browser from a declarative script and record it. Run it twice and
+get the same frames.**
 
 ```bash
-npx reel recordings/studio-tour/script.json --dry-run
-npx reel recordings/studio-tour/script.json --deterministic
+npx @mrkt_frwd/reel script.json --dry-run
+npx @mrkt_frwd/reel script.json --deterministic
 ```
 
-The script is data, not code. `--dry-run` validates it and resolves every
-selector in seconds, so a capture never dies four minutes in on a renamed one.
-`--deterministic` runs a fixed clock, so the frames do not depend on how long a
-frame cost to draw.
+## What it is for
 
-Needs Chromium and ffmpeg — the only engine here that is not zero-dependency.
+Repeatable video of a web page — product demos, regression captures, marketing
+clips — without a human driving the mouse and without the output drifting between
+runs.
 
-MIT.
+## The claim, and the evidence for it
+
+The script is **data, not code**:
+
+```json
+{
+  "name": "studio-tour",
+  "viewport": { "width": 1440, "height": 900 },
+  "fps": 24,
+  "shots": [
+    { "id": "land", "intent": "Open on the landing and let the hero settle.",
+      "actions": [
+        { "type": "goto", "url": "/" },
+        { "type": "hold", "ms": 1100 },
+        { "type": "scroll", "to": 620, "ms": 1500 }
+      ] }
+  ]
+}
+```
+
+Because it is data, an agent can write one, diff one, and review one before
+anything runs. An imperative recording script has to be executed to be
+understood — and by then you have already paid for the capture.
+
+**`--dry-run` on a real 4-shot, 18-action script: 4.06 s.** It loads the page,
+resolves all six selectors, and validates the whole script without recording a
+frame. A capture that dies four minutes in on a renamed selector is the expensive
+failure in this pipeline; this is the cheap thing that catches it.
+
+**`--deterministic` runs a fixed clock**, so frame N is frame N regardless of how
+long a frame cost to draw on your machine.
+
+## What it refuses to do
+
+- A shot without an `intent` is refused — the critic has nothing to judge against.
+- A selector that does not resolve fails the dry run rather than the capture.
+
+## Flags
+
+```
+--dry-run          validate and resolve every selector; record nothing
+--deterministic    fixed clock — the same frames every run
+--formats          mp4, gif, vertical, from one capture pass
+--live <origin>    record against a running server
+--gate             fail the build when the recording does not hold
+```
+
+## Requirements
+
+Node 18+, Chromium and ffmpeg — both come in as dependencies. This is the one
+engine in the set that is not zero-dependency, because it drives a real browser
+and encodes real video.
+
+MIT © Joe Asare. Built at [Joe Asare Studio](https://joeasare.com), where it
+records the work the other engines make.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrkt_frwd/reel",
-  "version": "0.1.0",
-  "description": "Reel — drive a real browser from a declarative script and record it. Deterministic mode gives the same frames every run.",
+  "version": "0.2.0",
+  "description": "Reel \u2014 drive a real browser from a declarative script and record it. Deterministic mode gives the same frames every run.",
   "type": "module",
   "exports": {
     ".": "./src/index.mjs"
@@ -15,10 +15,19 @@
   ],
   "dependencies": {
     "@playwright/browser-chromium": "^1.62.1",
-    "ffmpeg-static": "^5.3.0"
+    "ffmpeg-static": "^5.3.0",
+    "playwright-core": "^1.62.1"
   },
   "engines": {
     "node": ">=20"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrktfrwd/reel.git"
+  },
+  "homepage": "https://joeasare.com/engines/reel",
+  "scripts": {
+    "test": "node src/test-reel.mjs"
+  }
 }

package/src/cli.mjs

@@ -36,10 +36,29 @@ const flag = (name, fallback = null) => {
 };
 const has = (name) => argv.includes(`--${name}`);
 
+const USAGE = `reel — drive a real browser from a declarative script and record it.
+
+  npx @mrkt_frwd/reel <script.json> [flags]
+
+    --dry-run          validate the script and resolve every selector; record nothing
+    --deterministic    fixed clock, so frame N is frame N on any machine
+    --formats <list>   mp4, gif, vertical — from one capture pass
+    --live <origin>    record against an already-running server
+    --keep-frames      leave the raw frames on disk
+    --gate             exit non-zero when the recording does not hold
+
+  The script is data, not code: viewport, fps, and a list of shots, each with an
+  intent and a list of actions (goto, hold, scroll, click, type, drag, waitFor, eval).
+
+  Needs Chromium and ffmpeg, both installed as dependencies.
+  Docs: https://joeasare.com/engines/reel`;
+
 const scriptPath = argv.find((a) => !a.startsWith('--') && a.endsWith('.json'));
 if (!scriptPath) {
-  console.error('usage: npm run record -- <path/to/script.json> [--dry-run] [--deterministic] [--live <origin>] [--formats mp4,gif,vertical] [--keep-frames] [--gate]');
-  process.exit(2);
+  // Every engine in this set prints its own manual on a bare invocation and exits 0.
+  // Asking for help is not an error, and the pages promise one instruction is enough.
+  console.log(USAGE);
+  process.exit(0);
 }
 if (!fs.existsSync(scriptPath)) {
   console.error(`no such script: ${scriptPath}`);

package/src/test-reel.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Reel's promise is that a script is data you can check before you pay for a capture,
+ * and that two runs produce the same frames. These tests exercise the checking half —
+ * no browser, no ffmpeg, so they run anywhere.
+ *
+ *   node src/test-reel.mjs
+ */
+import assert from 'assert';
+import { validate, selectorsFor, parseViewport } from './schema.mjs';
+import { ACTION_TYPES } from './actions.mjs';
+
+const fails = [];
+const it = (n, f) => { try { f(); console.log(`  ok  ${n}`); } catch (e) { fails.push(n); console.log(`  FAIL ${n}\n       ${e.message}`); } };
+const script = (over = {}) => ({
+  name: 'probe', viewport: { width: 1440, height: 900 }, fps: 24,
+  shots: [{ id: 'one', intent: 'Load the page and let it settle.',
+            actions: [{ type: 'goto', url: '/' }, { type: 'hold', ms: 200 }] }],
+  ...over,
+});
+
+console.log('\n  REEL\n  ----------------------------------');
+
+it('a well-formed script validates', () => {
+  assert.deepEqual(validate(script()), [], 'a good script must report no errors');
+});
+
+it('a shot without an intent is refused — the critic needs something to judge', () => {
+  const s = script();
+  delete s.shots[0].intent;
+  const errs = validate(s);
+  assert.ok(errs.length > 0, 'a shot with no intent must be an error');
+  assert.ok(errs.join(' ').includes('intent'), `the error must name the intent, got ${errs.join('; ')}`);
+});
+
+it('an unknown action type is refused rather than skipped', () => {
+  const s = script();
+  s.shots[0].actions.push({ type: 'teleport', to: 'moon' });
+  assert.ok(validate(s).length > 0, 'an unknown action must not pass silently');
+});
+
+it('every documented action type is recognised, and missing fields are named', () => {
+  for (const t of ACTION_TYPES) {
+    const s = script();
+    s.shots[0].actions.push({ type: t });
+    const errs = validate(s).join(' ');
+    // The type itself must never come back as unknown. Complaining that a required
+    // field is missing is the validator working, and it must say which field.
+    assert.ok(!errs.includes(`unknown`) || !errs.includes(t),
+      `${t} is a documented action type but validate calls it unknown`);
+    if (errs.includes(`"${t}" requires`)) {
+      assert.ok(/requires "\w+"/.test(errs), `${t}: a missing field must be named, got: ${errs}`);
+    }
+  }
+});
+
+it('selectorsFor lists what a dry run has to resolve, and skips waitFor', () => {
+  const s = script();
+  s.shots[0].actions.push({ type: 'click', selector: '#buy' }, { type: 'waitFor', selector: '.ready' });
+  const sel = selectorsFor(s.shots[0]);
+  const found = sel.map((x) => x.selector);
+  assert.ok(found.includes('#buy'), `expected #buy, got ${JSON.stringify(found)}`);
+  // waitFor is a condition that may legitimately not exist yet — resolving it up front
+  // would fail a script that is correct.
+  assert.ok(!found.includes('.ready'), 'waitFor selectors must not be pre-resolved');
+});
+
+it('parseViewport reads a size and refuses nonsense', () => {
+  const v = parseViewport('800x600');
+  assert.equal(v.width, 800); assert.equal(v.height, 600);
+});
+
+if (fails.length) { console.error(`\n  ${fails.length} failure(s)\n`); process.exit(1); }
+console.log('\n  all reel checks passed\n');