Merge pull request #18 from HeyRenan/fix/actionability-gate

rec: actionability gate — refuse recording against a drifted app state (v1.6.1)

Author: HeyRenan

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Personal marketplace hosting the Showreel plugin",
-    "version": "1.6.0"
+    "version": "1.6.1"
   },
   "plugins": [
     {
       "name": "showreel",
       "source": "./showreel",
       "description": "Your UI, on its showreel \u2014 annotated screenshots, feature demos, flow walkthrough recordings (gif/mp4), terminal captures and before/after composites in one command each. Self-contained Chromium motor, deterministic placement, self-validated output; no MCP, cheap on tokens.",
-      "version": "1.6.0"
+      "version": "1.6.1"
     }
   ]
 }

CHANGELOG.md

@@ -9,6 +9,12 @@ Showreel turns "show me" into a finished visual — annotated screenshots, isola
 demos, flow GIFs, terminal recordings and before/after composites — driven entirely
 by CSS selectors and JSON steps.
 
+## [1.6.1] — 2026-07-08
+
+### Fixed
+- **Recording against a drifted app state is now refused, not silently mis-recorded.** Re-running a roster after the app moved on — a submitted form's button now `disabled`, a spent one-time action, a control now sitting under an overlay — used to slip the live safeguard: it drove the target with a DOM `el.click()`, which punches through a disabled/covered element without erroring, so the real coordinate-click then hit nothing or the overlay (reading as random clicks). The safeguard now asserts the target is actionable the way the real take clicks it and **refuses** (`[not-actionable]`, exit 2) on a `disabled` / `aria-disabled` / `pointer-events:none` / covered target, routing you to reset the app to a fresh state (occlusion is viewport-guarded, so a below-fold target is not false-flagged).
+- **Audit driving now matches real typing.** The safeguard's `fill` sets the value through the native input setter and dispatches `input` + `change` + `blur`, so a submit gated on `change`/blur/controlled-state enables during the audit too — a valid fill→enable-submit flow (the `form-flow` preset) is no longer false-refused.
+
 ## [1.6.0] — 2026-07-07
 
 ### Added

showreel/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "showreel",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Your UI, on its showreel \u2014 annotated screenshots, feature demos, flow walkthrough recordings (gif/mp4), terminal captures and before/after composites in one command each. Self-contained Chromium motor, deterministic placement, self-validated output; no MCP, cheap on tokens.",
   "author": {
     "name": "Renan"

showreel/scripts/__tests__/rec-steps.test.mjs

@@ -688,6 +688,74 @@ test('auditRosterLive gates a MISSING scrollTo target (silent-wrong-scene)', asy
   assert.equal((await auditRosterLive([{ zoom: 'out' }], bridge)).errors.length, 0); // "out" is not a selector
 });
 
+test('auditRosterLive refuses a not-actionable interaction target (app-state drift)', async () => {
+  // The audit drives clicks with el.click(), which punches through a disabled or
+  // covered element without throwing; the real take clicks by coordinate and hits
+  // nothing (disabled) or the overlay (random click). The actionability gate
+  // catches the re-record-against-drifted-state failure BEFORE any video.
+  const acts = {
+    '#submit': { ok: false, reason: 'disabled' },
+    '#cta': { ok: false, reason: 'covered', by: 'div.cookie-banner' },
+    '#email': { ok: false, reason: 'disabled' },
+    '#go': { ok: true },
+  };
+  const bridge = {
+    measure: async () => ({ visible: true, w: 120, h: 36, cx: 200, cy: 300 }),
+    click: async () => {}, fill: async () => {}, select: async () => {}, settle: async () => {},
+    actionable: async (sel) => acts[sel] || { ok: true },
+  };
+  // disabled click -> not-actionable, message routes the operator to reset state
+  const dis = (await auditRosterLive([{ click: '#submit' }], bridge)).errors;
+  assert.equal(dis.length, 1);
+  assert.equal(dis[0].kind, 'not-actionable');
+  assert.match(dis[0].message, /reset/i);
+  // covered click -> not-actionable, message names the overlay on top
+  const cov = (await auditRosterLive([{ click: '#cta' }], bridge)).errors;
+  assert.equal(cov.length, 1);
+  assert.equal(cov[0].kind, 'not-actionable');
+  assert.match(cov[0].message, /cookie-banner/);
+  // a fill target is gated too (the audit fills with el.value=, same punch-through)
+  const fil = (await auditRosterLive([{ fill: '#email', text: 'a@b.com' }], bridge)).errors;
+  assert.equal(fil.length, 1);
+  assert.equal(fil[0].kind, 'not-actionable');
+  // an actionable target renders clean — the happy path is untouched
+  assert.equal((await auditRosterLive([{ click: '#go' }], bridge)).errors.length, 0);
+});
+
+test('auditRosterLive: a target enabled by an EARLIER step is not falsely refused', async () => {
+  // form-flow: #submit starts disabled and an earlier fill enables it. The gate
+  // checks actionability AFTER driving prior steps, so #submit must read
+  // actionable at its click. Guards the regression where a valid fill->submit
+  // flow would be refused. (The real bridge's fill fires input+change via the
+  // native setter so the DOM actually flips; here the fake bridge models that.)
+  const makeFormBridge = () => {
+    let filled = false;
+    return {
+      measure: async () => ({ visible: true, w: 120, h: 36, cx: 200, cy: 300 }),
+      click: async () => {}, settle: async () => {}, select: async () => {},
+      fill: async () => { filled = true; },
+      actionable: async (sel) => (sel === '#submit' && !filled ? { ok: false, reason: 'disabled' } : { ok: true }),
+    };
+  };
+  const roster = [{ fill: '#email', text: 'a@b.com' }, { click: '#submit', note: 'Enviar' }];
+  const errs = (await auditRosterLive(roster, makeFormBridge())).errors;
+  assert.equal(errs.length, 0, 'a fill that enables the submit must not trip not-actionable');
+  // control: the SAME submit with no preceding fill IS refused (disabled on load)
+  const bare = (await auditRosterLive([{ click: '#submit', note: 'Enviar' }], makeFormBridge())).errors;
+  assert.equal(bare.length, 1);
+  assert.equal(bare[0].kind, 'not-actionable');
+});
+
+test('auditRosterLive: a bridge without actionable() adds no errors (back-compat)', async () => {
+  // fake bridges (and any external caller) predating the actionability gate must
+  // keep passing — the check is guarded on the method existing.
+  const bridge = {
+    measure: async () => ({ visible: true, w: 120, h: 36, cx: 200, cy: 300 }),
+    click: async () => {}, fill: async () => {}, select: async () => {}, settle: async () => {},
+  };
+  assert.equal((await auditRosterLive([{ click: '#submit' }], bridge)).errors.length, 0);
+});
+
 test('auditRosterLive warns on zoom-churn: re-framing a nested element of the same card across an "out"', async () => {
   // #rollback-countdown lives INSIDE #deploy-panel — framing the panel, pulling
   // out, then framing a child (or back to the panel) re-zooms the same card. The

showreel/scripts/rec-steps.mjs

@@ -759,8 +759,27 @@ export function makeAuditBridge(page, vw, vh) {
       return { w: r.width, h: r.height, cx: r.left + r.width / 2, cy: r.top + r.height / 2, visible };
     }, sel),
     click: (sel) => page.evaluate((q) => { const el = document.querySelector(q); if (el) el.click(); }, sel),
-    fill: (sel, t) => page.evaluate(({ q, t }) => { const el = document.querySelector(q); if (el) { el.value = t; el.dispatchEvent(new Event('input', { bubbles: true })); } }, { q: sel, t }),
-    select: (sel, o) => page.evaluate(({ q, o }) => { const el = document.querySelector(q); if (el) { const x = [...el.options].find((p) => p.text.trim() === o || p.value === o); if (x) { el.value = x.value; el.dispatchEvent(new Event('change', { bubbles: true })); } } }, { q: sel, o }),
+    // Type/select the way the REAL take does (keyboard + coordinate change), so
+    // the audit's post-action DOM — and the actionability verdict riding it —
+    // matches what the recording produces. A raw `el.value=` fires no `change`
+    // and is invisible to a controlled (React) input (its value setter is
+    // overridden on the instance): use the prototype's native setter and
+    // dispatch input + change (+ blur) so a submit gated on change/blur/state
+    // actually enables here too. Without this the gate FALSE-REFUSES a valid
+    // fill->enable-submit flow (the shipped form-flow preset).
+    fill: (sel, t) => page.evaluate(({ q, t }) => {
+      const el = document.querySelector(q); if (!el) return;
+      // native value setter ONLY on a real input/textarea — calling the input
+      // prototype's setter on any other element throws "Illegal invocation".
+      const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype
+        : el instanceof HTMLInputElement ? HTMLInputElement.prototype : null;
+      const desc = proto && Object.getOwnPropertyDescriptor(proto, 'value');
+      if (desc && desc.set) desc.set.call(el, t); else el.value = t;
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+      el.dispatchEvent(new Event('blur', { bubbles: true }));
+    }, { q: sel, t }),
+    select: (sel, o) => page.evaluate(({ q, o }) => { const el = document.querySelector(q); if (el) { const x = [...el.options].find((p) => p.text.trim() === o || p.value === o); if (x) { el.value = x.value; el.dispatchEvent(new Event('input', { bubbles: true })); el.dispatchEvent(new Event('change', { bubbles: true })); } } }, { q: sel, o }),
     settle: (ms) => page.waitForTimeout(ms),
     contains: (host, sel) => page.evaluate(({ h, s }) => {
       const he = document.querySelector(h), se = document.querySelector(s);
@@ -773,9 +792,54 @@ export function makeAuditBridge(page, vw, vh) {
       const noCrop = cap.MARGIN * Math.min(vw / r.width, vh / r.height);
       return Math.max(1, Math.min(Math.min(cap.MAX, fit * cap.ZOOM), noCrop));
     }, { q: sel, vw, vh, cap: FRAME }),
+    // Is an INTERACTION target truly clickable, the way the real take clicks it?
+    // The audit drives with el.click()/el.value= (above), which PUNCH THROUGH a
+    // disabled or covered element — el.click() never throws on a disabled control
+    // and ignores pointer-events + occlusion. The recorded take clicks by
+    // coordinate (p.mouse.click), so it clicks nothing (disabled) or the overlay
+    // on top (reads as a random click). This asserts the target the way the take
+    // will hit it. Occlusion is viewport-guarded: elementFromPoint returns null
+    // for a point below the fold, which would false-flag every off-screen target
+    // as covered — the disabled/aria/pointer-events checks are position-free and
+    // always run. Returns { ok } or { ok:false, reason, by? }.
+    actionable: (sel) => page.evaluate(({ q, vw, vh }) => {
+      const el = document.querySelector(q);
+      if (!el) return { ok: false, reason: 'missing' };
+      if (el.disabled === true) return { ok: false, reason: 'disabled' };
+      if (el.getAttribute('aria-disabled') === 'true') return { ok: false, reason: 'aria-disabled' };
+      if (getComputedStyle(el).pointerEvents === 'none') return { ok: false, reason: 'pointer-events' };
+      const r = el.getBoundingClientRect();
+      const cx = r.left + r.width / 2, cy = r.top + r.height / 2;
+      const inViewport = cx >= 0 && cx <= vw && cy >= 0 && cy <= vh;
+      if (inViewport) {
+        const top = document.elementFromPoint(cx, cy);
+        if (top && top !== el && !el.contains(top) && !top.contains(el)) {
+          const tag = top.tagName.toLowerCase();
+          const cls = typeof top.className === 'string' && top.className.trim()
+            ? '.' + top.className.trim().split(/\s+/).join('.') : '';
+          return { ok: false, reason: 'covered', by: tag + cls };
+        }
+      }
+      return { ok: true };
+    }, { q: sel, vw, vh }),
   };
 }
 
+// Human message for a not-actionable interaction target. Routes the operator to
+// the REAL cause — the app drifted from the state the roster was authored for —
+// because the recorder cannot reset server-side state (a fresh browser context
+// won't un-submit a form). Pure; unit-tested through auditRosterLive.
+export function actionabilityMessage(sel, act) {
+  const reason = act && act.reason;
+  if (reason === 'covered')
+    return `"${sel}" is covered by ${(act && act.by) || 'another element'} at its click point — the real mouse click would hit that overlay, not the target (reads as a random click). Dismiss/hide the overlay first (an earlier click to close it, or {"hide":"<overlay>"}).`;
+  if (reason === 'pointer-events')
+    return `"${sel}" has pointer-events:none — the real mouse click can't actuate it. Reveal/enable it first, or target the actionable element.`;
+  if (reason === 'missing')
+    return `"${sel}" matches no element — the step fires on nothing.`;
+  return `"${sel}" is disabled — the app is in a state this roster wasn't authored for (a form already submitted, a one-time action already spent). The recorder can't reset server-side state; reset the demo/app to a fresh state before recording (or pass --no-safeguards to override).`;
+}
+
 // Live audit (needs a page): walks the roster against the REAL rendered DOM and
 // returns hard ERRORS for the two failures static analysis can't see:
 //  - off-screen: an action/primitive anchored to an element whose center is
@@ -873,13 +937,35 @@ export async function auditRosterLive(steps, bridge) {
       if (!(await measure(sel))) errors.push({ step: i + 1, kind: 'missing', message: `${what} "${sel}" matches no element — the scene never ${what === 'zoom target' ? 'frames it (renders wide, reads as a random pan)' : 'scrolls (silently shows the wrong position)'}.` });
     }
 
-    // drive real state so later anchors see the post-action DOM
+    // actionability gate: assert each interaction target is clickable the way the
+    // real take clicks it (by coordinate), not the way the audit drives it (DOM
+    // el.click(), which punches through disabled/covered). This is the app-state-
+    // drift failure the operator hits re-recording — a form already submitted, a
+    // spent one-time action, a CTA that changed and now covers/overlays.
+    const notActionable = new Set();
+    if (typeof bridge.actionable === 'function') {
+      const interactionSels = [];
+      if (typeof s.click === 'string') interactionSels.push(s.click);
+      const fSpec = fillSpec(s); if (fSpec && fSpec.sel) interactionSels.push(fSpec.sel);
+      const slSpec = selectSpec(s); if (slSpec && slSpec.sel) interactionSels.push(slSpec.sel);
+      for (const sel of interactionSels) {
+        const act = await bridge.actionable(sel);
+        if (act && !act.ok) {
+          errors.push({ step: i + 1, kind: 'not-actionable', message: actionabilityMessage(sel, act) });
+          notActionable.add(sel);
+        }
+      }
+    }
+
+    // drive real state so later anchors see the post-action DOM. A target flagged
+    // not-actionable is skipped — driving it would either no-op (disabled) or
+    // punch through to a covered element and mutate state off the wrong node.
     try {
       // a click can kick off an async flow (deploy progress reveals toast/new
       // row ~2s later); settle long enough for those reveals before later checks.
-      if (typeof s.click === 'string') { await bridge.click(s.click); await bridge.settle(2300); }
-      const fl = s.fill; if (typeof fl === 'string' && typeof s.text === 'string') { await bridge.fill(fl, s.text); }
-      if (typeof s.select === 'string' && typeof s.option === 'string') { await bridge.select(s.select, s.option); }
+      if (typeof s.click === 'string' && !notActionable.has(s.click)) { await bridge.click(s.click); await bridge.settle(2300); }
+      const fl = s.fill; if (typeof fl === 'string' && typeof s.text === 'string' && !notActionable.has(fl)) { await bridge.fill(fl, s.text); }
+      if (typeof s.select === 'string' && typeof s.option === 'string' && !notActionable.has(s.select)) { await bridge.select(s.select, s.option); }
     } catch { /* driving is best-effort; a failed click just leaves state as-is */ }
   }
   return { errors, warnings };

showreel/skills/showreel/SKILL.md

@@ -74,6 +74,8 @@ Whatever you pick: every label visibly connects to its target, and the final fra
 
 **Discipline:** `--dry` is MANDATORY before any recording — resolves every selector ([ok]/[MISS]), no recording. A [MISS] on a glide/camera/click/fill/select target is a frozen dead beat — fix to zero MISS, then record ONCE.
 
+**Fresh app state before every (re-)record.** A roster is authored for the app in state A; re-running it later hits state B, where the action already happened — a submitted form's button is now `disabled`, a one-time CTA is spent, a control changed and an overlay/next-page element sits where the target was. The recorder then clicks nothing (disabled) or the wrong thing (reads as random clicks). `--dry` will NOT catch this (a disabled button still resolves). The live safeguard now **refuses** (exit 2, `[not-actionable]`) when a click/fill/select target is `disabled` / `aria-disabled` / `pointer-events:none` / covered by another element. The recorder CANNOT reset server-side state (a fresh browser context won't un-submit a form) — so on a `not-actionable` refusal, **reset the demo/app to a fresh state and re-run**; never `--no-safeguards` past it (that records the broken flow).
+
 **Render mode (decides at the command line, not in the frames):** a MOVING reel — any `glide`/`follow`/`camera`/`fill`/`select` — records realtime `--fps 30`, NO `--offline` (15fps stills → slideshow), NO `--pace fast` (collapses easing), NO `speed` (a no-op in realtime). `--pace fast` and `--offline` are ONLY for quick static/dwell-only proofs.
 
 **Presets:** don't write step JSON from scratch. Copy a starting roster from `scripts/presets/` — `form-flow.json`, `nav-flow.json`, `dashboard.json` — and swap the selectors for the page under test.