screencast-axi 0.1.0

package/dist/src/overlay.js

@@ -0,0 +1,302 @@
+/**
+ * Page overlay injected into every document of a recording session.
+ *
+ * Playwright videos do not contain the mouse pointer, which makes any clip of a
+ * drag or a click unreadable. This draws a synthetic pointer that follows the
+ * real one (Playwright's `mouse.move` dispatches genuine `mousemove` events, so
+ * the overlay stays in sync for free), plus a click ripple, a drag ghost and a
+ * caption bar.
+ *
+ * Everything lives in a shadow root so no page CSS can reach it, and the host
+ * is `pointer-events: none` so it never intercepts a click.
+ */
+export const DEFAULT_OVERLAY_THEME = {
+    accent: "#4f46e5",
+    hideNativeCursor: true,
+    hideSelectors: [],
+    pointer: { size: 26, fill: "#111116", stroke: "#ffffff", strokeWidth: 1.6 },
+    ripple: { enabled: true, scale: 2.6, durationMs: 500 },
+    dragGhost: { enabled: true, width: 46, height: 30, radius: 6 },
+    caption: {
+        position: "bottom",
+        offset: 40,
+        maxWidth: "min(760px, 78vw)",
+        background: "rgba(17, 17, 22, .88)",
+        color: "#ffffff",
+        fontSize: 17,
+        fontFamily: 'ui-sans-serif, -apple-system, "Segoe UI", system-ui, sans-serif',
+        fontWeight: 500,
+        radius: 12,
+        padding: "12px 20px",
+        fadeMs: 220,
+        shadow: "0 12px 40px rgba(0,0,0,.34)",
+    },
+};
+function rgba(color, alpha) {
+    const hex = color.trim().replace(/^#/, "");
+    const full = hex.length === 3
+        ? hex
+            .split("")
+            .map((c) => c + c)
+            .join("")
+        : hex;
+    if (!/^[0-9a-fA-F]{6}$/.test(full)) {
+        // Not a hex colour - use it as given and let the browser decide. A named
+        // colour or an rgb() string still renders; it just cannot be made
+        // translucent here.
+        return color;
+    }
+    const r = parseInt(full.slice(0, 2), 16);
+    const g = parseInt(full.slice(2, 4), 16);
+    const b = parseInt(full.slice(4, 6), 16);
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+export function resolveOverlayTheme(overrides) {
+    const t = mergeTheme(DEFAULT_OVERLAY_THEME, overrides);
+    return {
+        ...t,
+        accentSoft: rgba(t.accent, 0.16),
+        accentEdge: rgba(t.accent, 0.55),
+        accentRipple: rgba(t.accent, 0.28),
+        accentRippleEdge: rgba(t.accent, 0.6),
+    };
+}
+export function mergeThemes(base, over) {
+    if (!base)
+        return over ?? {};
+    if (!over)
+        return base;
+    return {
+        ...base,
+        ...over,
+        pointer: { ...base.pointer, ...over.pointer },
+        ripple: { ...base.ripple, ...over.ripple },
+        dragGhost: { ...base.dragGhost, ...over.dragGhost },
+        caption: { ...base.caption, ...over.caption },
+    };
+}
+function mergeTheme(base, overrides) {
+    if (!overrides)
+        return base;
+    return {
+        ...base,
+        ...overrides,
+        pointer: { ...base.pointer, ...overrides.pointer },
+        ripple: { ...base.ripple, ...overrides.ripple },
+        dragGhost: { ...base.dragGhost, ...overrides.dragGhost },
+        caption: { ...base.caption, ...overrides.caption },
+    };
+}
+/**
+ * Serialised form of {@link installOverlay}, ready for `addInitScript`.
+ *
+ * The function is stringified rather than passed directly because this file is
+ * compiled by esbuild under `keepNames` in some toolchains, which rewrites
+ * every inner function as `__name(fn, "fn")`. That helper only exists in the
+ * Node module scope, so the function throws `__name is not defined` the moment
+ * Playwright evaluates it in the page - silently, unless a `pageerror`
+ * listener is attached. Re-declaring `__name` as identity in the wrapper is
+ * enough, and costs nothing if a future toolchain stops emitting it.
+ *
+ * The theme travels as JSON in the same wrapper, so theming does not
+ * reintroduce a function reference that would have to survive the same trip.
+ */
+export function overlayInitScript(theme) {
+    return `(() => { const __name = (fn) => fn; (${installOverlay.toString()})(${JSON.stringify(theme)}); })();`;
+}
+/** Runs inside the page via `addInitScript`. Must be fully self-contained. */
+export function installOverlay(theme) {
+    const HOST_ID = "__screencast_overlay";
+    const STYLE_ID = "__screencast_hide";
+    // Already installed in this realm. An init script runs once per document
+    // creation, so this only fires if something injected it twice.
+    if (window.__screencast)
+        return;
+    let refs = null;
+    /** Last caption text, so a re-mount can restore what was on screen. */
+    let captionText = null;
+    const cap = theme.caption;
+    const edge = cap.position === "top" ? `top: ${cap.offset}px` : `bottom: ${cap.offset}px`;
+    const rise = cap.position === "top" ? -8 : 8;
+    const build = () => {
+        if (!document.body || !document.documentElement)
+            return null;
+        const host = document.createElement("div");
+        host.id = HOST_ID;
+        host.style.cssText = "position:fixed;inset:0;z-index:2147483647;pointer-events:none;";
+        const root = host.attachShadow({ mode: "open" });
+        root.innerHTML = `
+      <style>
+        :host { all: initial; }
+        .pointer {
+          position: fixed; top: 0; left: 0;
+          width: ${theme.pointer.size}px; height: ${theme.pointer.size}px;
+          transform: translate3d(-100px, -100px, 0);
+          will-change: transform; opacity: 0; transition: opacity 120ms linear;
+        }
+        .pointer.on { opacity: 1; }
+        .carry {
+          position: fixed; top: 0; left: 0;
+          transform: translate3d(-100px, -100px, 0);
+          opacity: 0; transition: opacity 140ms linear;
+        }
+        .carry.on { opacity: 1; }
+        .carry > i {
+          display: block;
+          width: ${theme.dragGhost.width}px; height: ${theme.dragGhost.height}px;
+          margin: 10px 0 0 10px;
+          border-radius: ${theme.dragGhost.radius}px;
+          background: ${theme.accentSoft};
+          border: 1px solid ${theme.accentEdge};
+          box-shadow: 0 6px 18px rgba(17, 17, 22, .18);
+        }
+        .ripple { position: fixed; top: 0; left: 0; transform: translate3d(-100px, -100px, 0); }
+        .ripple > i {
+          display: block; width: 18px; height: 18px; margin: -9px 0 0 -9px;
+          border-radius: 50%; background: ${theme.accentRipple};
+          box-shadow: 0 0 0 2px ${theme.accentRippleEdge};
+          transform: scale(.3); opacity: 0;
+        }
+        .ripple.go > i {
+          animation: pop ${theme.ripple.durationMs}ms cubic-bezier(.2,.8,.3,1) forwards;
+        }
+        @keyframes pop {
+          0%   { transform: scale(.3);  opacity: .95; }
+          100% { transform: scale(${theme.ripple.scale}); opacity: 0; }
+        }
+        .caption {
+          position: fixed; left: 50%; ${edge};
+          transform: translateX(-50%) translateY(${rise}px);
+          max-width: ${cap.maxWidth}; padding: ${cap.padding};
+          border-radius: ${cap.radius}px;
+          background: ${cap.background}; color: ${cap.color};
+          font: ${cap.fontWeight} ${cap.fontSize}px/1.45 ${cap.fontFamily};
+          letter-spacing: .01em; text-align: center;
+          box-shadow: ${cap.shadow};
+          opacity: 0;
+          transition: opacity ${cap.fadeMs}ms ease, transform ${cap.fadeMs}ms ease;
+        }
+        .caption.on { opacity: 1; transform: translateX(-50%) translateY(0); }
+      </style>
+      <div class="ripple"><i></i></div>
+      <div class="carry"><i></i></div>
+      <svg class="pointer" viewBox="0 0 26 26" aria-hidden="true">
+        <path d="M5 2.5 L5 20.5 L9.6 16.2 L12.6 22.6 L16 21 L13 14.8 L19.4 14.4 Z"
+              fill="${theme.pointer.fill}" stroke="${theme.pointer.stroke}"
+              stroke-width="${theme.pointer.strokeWidth}" stroke-linejoin="round"/>
+      </svg>
+      <div class="caption"></div>
+    `;
+        document.documentElement.appendChild(host);
+        // A single fixed arrow reads better than the browser swapping between
+        // arrow / text / grab cursors mid-clip, so hide the real one. Anything in
+        // `hideSelectors` is page chrome the recording should not show.
+        if (document.head && !document.getElementById(STYLE_ID)) {
+            const rules = [];
+            if (theme.hideNativeCursor)
+                rules.push("*, *::before, *::after { cursor: none !important; }");
+            for (const selector of theme.hideSelectors) {
+                rules.push(`${selector} { display: none !important; }`);
+            }
+            if (rules.length > 0) {
+                const hide = document.createElement("style");
+                hide.id = STYLE_ID;
+                hide.textContent = rules.join(" ");
+                document.head.appendChild(hide);
+            }
+        }
+        const next = {
+            host,
+            pointer: root.querySelector(".pointer"),
+            ripple: root.querySelector(".ripple"),
+            carry: root.querySelector(".carry"),
+            caption: root.querySelector(".caption"),
+        };
+        // A re-mount must not lose the line that was on screen: a page that
+        // rewrites its document mid-take would otherwise drop the caption and the
+        // clip would keep recording as if nothing were wrong.
+        if (captionText !== null) {
+            next.caption.textContent = captionText;
+            next.caption.classList.add("on");
+        }
+        return next;
+    };
+    /**
+     * The overlay, rebuilt if the page threw it away.
+     *
+     * A document replacement - `document.write`, Playwright's `setContent`, some
+     * SPA bootstraps - detaches the host while this realm, and therefore
+     * `window.__screencast`, survives. Without this the API would keep answering
+     * on a detached node: captions would stop appearing and the recording would
+     * carry on silently, which is the worst way for this to fail.
+     */
+    const ensure = () => {
+        if (refs && refs.host.isConnected)
+            return refs;
+        refs = build();
+        return refs;
+    };
+    const move = (x, y) => {
+        const r = ensure();
+        if (!r)
+            return;
+        r.pointer.style.transform = `translate3d(${x}px, ${y}px, 0)`;
+        r.carry.style.transform = `translate3d(${x}px, ${y}px, 0)`;
+        r.pointer.classList.add("on");
+    };
+    addEventListener("mousemove", (e) => move(e.clientX, e.clientY), {
+        capture: true,
+        passive: true,
+    });
+    if (theme.ripple.enabled) {
+        addEventListener("mousedown", (e) => {
+            const r = ensure();
+            if (!r)
+                return;
+            r.ripple.style.transform = `translate3d(${e.clientX}px, ${e.clientY}px, 0)`;
+            r.ripple.classList.remove("go");
+            void r.ripple.offsetWidth; // restart the animation
+            r.ripple.classList.add("go");
+        }, { capture: true, passive: true });
+    }
+    window.__screencast = {
+        caption(text) {
+            captionText = text;
+            const r = ensure();
+            if (!r)
+                return;
+            if (text) {
+                r.caption.textContent = text;
+                r.caption.classList.add("on");
+            }
+            else {
+                r.caption.classList.remove("on");
+            }
+        },
+        setPointerVisible(visible) {
+            ensure()?.pointer.classList.toggle("on", visible);
+        },
+        // An HTML5 drag never presses the mouse button (see Director.dragHtml5),
+        // so there is no ripple and nothing else on screen says "this pointer is
+        // carrying something". This ghost chip does.
+        setDragging(dragging) {
+            if (!theme.dragGhost.enabled)
+                return;
+            ensure()?.carry.classList.toggle("on", dragging);
+        },
+    };
+    // Listeners go on `window`, not `document`: `document.open()` - which is how
+    // a page replaces itself - drops every listener registered on the document,
+    // while window-level ones survive.
+    //
+    // These cover the ordinary path, where the document is still parsing when
+    // the init script runs. They do *not* cover a document replacement: measured
+    // in Chromium, a replaced document fires neither DOMContentLoaded nor load
+    // on window, even though the listeners are still attached. That case is
+    // handled lazily by `ensure()`, which every API call and every pointer move
+    // goes through - so the overlay is back before the next thing a take does.
+    addEventListener("DOMContentLoaded", () => ensure());
+    addEventListener("load", () => ensure());
+    ensure();
+}
+//# sourceMappingURL=overlay.js.map

package/dist/src/overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.js","sourceRoot":"","sources":["../../src/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA6DH,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,MAAM,EAAE,SAAS;IACjB,gBAAgB,EAAE,IAAI;IACtB,aAAa,EAAE,EAAE;IACjB,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,EAAE;IAC3E,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE;IACtD,SAAS,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE;IAC9D,OAAO,EAAE;QACP,QAAQ,EAAE,QAAQ;QAClB,MAAM,EAAE,EAAE;QACV,QAAQ,EAAE,kBAAkB;QAC5B,UAAU,EAAE,uBAAuB;QACnC,KAAK,EAAE,SAAS;QAChB,QAAQ,EAAE,EAAE;QACZ,UAAU,EAAE,iEAAiE;QAC7E,UAAU,EAAE,GAAG;QACf,MAAM,EAAE,EAAE;QACV,OAAO,EAAE,WAAW;QACpB,MAAM,EAAE,GAAG;QACX,MAAM,EAAE,6BAA6B;KACtC;CACF,CAAC;AAiBF,SAAS,IAAI,CAAC,KAAa,EAAE,KAAa;IACxC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC3C,MAAM,IAAI,GACR,GAAG,CAAC,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,GAAG;aACA,KAAK,CAAC,EAAE,CAAC;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;aACjB,IAAI,CAAC,EAAE,CAAC;QACb,CAAC,CAAC,GAAG,CAAC;IACV,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,yEAAyE;QACzE,kEAAkE;QAClE,oBAAoB;QACpB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzC,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzC,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzC,OAAO,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,KAAK,GAAG,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,SAAqC;IACvE,MAAM,CAAC,GAAG,UAAU,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC;IACvD,OAAO;QACL,GAAG,CAAC;QACJ,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC;QAChC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC;QAChC,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC;QAClC,gBAAgB,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC;KACtC,CAAC;AACJ,CAAC;AAUD,MAAM,UAAU,WAAW,CACzB,IAA2C,EAC3C,IAA2C;IAE3C,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO;QACL,GAAG,IAAI;QACP,GAAG,IAAI;QACP,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE;QAC7C,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE;QAC1C,SAAS,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE;QACnD,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE;KAC9C,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAkB,EAAE,SAAqC;IAC3E,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO;QACL,GAAG,IAAI;QACP,GAAG,SAAS;QACZ,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE;QAClD,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE;QAC/C,SAAS,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,SAAS,EAAE;QACxD,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE;KACnC,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA2B;IAC3D,OAAO,wCAAwC,cAAc,CAAC,QAAQ,EAAE,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC;AAC/G,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,cAAc,CAAC,KAA2B;IACxD,MAAM,OAAO,GAAG,sBAAsB,CAAC;IACvC,MAAM,QAAQ,GAAG,mBAAmB,CAAC;IAErC,yEAAyE;IACzE,+DAA+D;IAC/D,IAAI,MAAM,CAAC,YAAY;QAAE,OAAO;IAUhC,IAAI,IAAI,GAAgB,IAAI,CAAC;IAC7B,uEAAuE;IACvE,IAAI,WAAW,GAAkB,IAAI,CAAC;IAEtC,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC;IAC1B,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,MAAM,IAAI,CAAC;IACzF,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7C,MAAM,KAAK,GAAG,GAAgB,EAAE;QAC9B,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,eAAe;YAAE,OAAO,IAAI,CAAC;QAE7D,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC;QAClB,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,gEAAgE,CAAC;QACtF,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAEjD,IAAI,CAAC,SAAS,GAAG;;;;;mBAKF,KAAK,CAAC,OAAO,CAAC,IAAI,eAAe,KAAK,CAAC,OAAO,CAAC,IAAI;;;;;;;;;;;;;mBAanD,KAAK,CAAC,SAAS,CAAC,KAAK,eAAe,KAAK,CAAC,SAAS,CAAC,MAAM;;2BAElD,KAAK,CAAC,SAAS,CAAC,MAAM;wBACzB,KAAK,CAAC,UAAU;8BACV,KAAK,CAAC,UAAU;;;;;;4CAMF,KAAK,CAAC,YAAY;kCAC5B,KAAK,CAAC,gBAAgB;;;;2BAI7B,KAAK,CAAC,MAAM,CAAC,UAAU;;;;oCAId,KAAK,CAAC,MAAM,CAAC,KAAK;;;wCAGd,IAAI;mDACO,IAAI;uBAChC,GAAG,CAAC,QAAQ,cAAc,GAAG,CAAC,OAAO;2BACjC,GAAG,CAAC,MAAM;wBACb,GAAG,CAAC,UAAU,YAAY,GAAG,CAAC,KAAK;kBACzC,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,QAAQ,WAAW,GAAG,CAAC,UAAU;;wBAEjD,GAAG,CAAC,MAAM;;gCAEF,GAAG,CAAC,MAAM,sBAAsB,GAAG,CAAC,MAAM;;;;;;;;sBAQpD,KAAK,CAAC,OAAO,CAAC,IAAI,aAAa,KAAK,CAAC,OAAO,CAAC,MAAM;8BAC3C,KAAK,CAAC,OAAO,CAAC,WAAW;;;KAGlD,CAAC;QAEF,QAAQ,CAAC,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAE3C,sEAAsE;QACtE,0EAA0E;QAC1E,gEAAgE;QAChE,IAAI,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxD,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,gBAAgB;gBAAE,KAAK,CAAC,IAAI,CAAC,qDAAqD,CAAC,CAAC;YAC9F,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;gBAC3C,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,gCAAgC,CAAC,CAAC;YAC1D,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrB,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;gBAC7C,IAAI,CAAC,EAAE,GAAG,QAAQ,CAAC;gBACnB,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACnC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QAED,MAAM,IAAI,GAAS;YACjB,IAAI;YACJ,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,UAAU,CAAe;YACrD,MAAM,EAAE,IAAI,CAAC,aAAa,CAAC,SAAS,CAAgB;YACpD,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAgB;YAClD,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,UAAU,CAAgB;SACvD,CAAC;QAEF,oEAAoE;QACpE,0EAA0E;QAC1E,sDAAsD;QACtD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,IAAI,CAAC,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;YACvC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF;;;;;;;;OAQG;IACH,MAAM,MAAM,GAAG,GAAgB,EAAE;QAC/B,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QAC/C,IAAI,GAAG,KAAK,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE;QACpC,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC;QACnB,IAAI,CAAC,CAAC;YAAE,OAAO;QACf,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC7D,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC3D,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC,CAAC;IAEF,gBAAgB,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE;QAC/D,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,IAAI;KACd,CAAC,CAAC;IAEH,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACzB,gBAAgB,CACd,WAAW,EACX,CAAC,CAAC,EAAE,EAAE;YACJ,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC;YACnB,IAAI,CAAC,CAAC;gBAAE,OAAO;YACf,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,GAAG,eAAe,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,OAAO,QAAQ,CAAC;YAC5E,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAChC,KAAK,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,wBAAwB;YACnD,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC,EACD,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CACjC,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,YAAY,GAAG;QACpB,OAAO,CAAC,IAAmB;YACzB,WAAW,GAAG,IAAI,CAAC;YACnB,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC;YACnB,IAAI,CAAC,CAAC;gBAAE,OAAO;YACf,IAAI,IAAI,EAAE,CAAC;gBACT,CAAC,CAAC,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;gBAC7B,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC;iBAAM,CAAC;gBACN,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QACD,iBAAiB,CAAC,OAAgB;YAChC,MAAM,EAAE,EAAE,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACpD,CAAC;QACD,yEAAyE;QACzE,yEAAyE;QACzE,6CAA6C;QAC7C,WAAW,CAAC,QAAiB;YAC3B,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO;gBAAE,OAAO;YACrC,MAAM,EAAE,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACnD,CAAC;KACF,CAAC;IAEF,6EAA6E;IAC7E,4EAA4E;IAC5E,mCAAmC;IACnC,EAAE;IACF,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,wEAAwE;IACxE,4EAA4E;IAC5E,2EAA2E;IAC3E,gBAAgB,CAAC,kBAAkB,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;IACrD,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,MAAM,EAAE,CAAC;AACX,CAAC"}

package/dist/src/reference.d.ts

@@ -0,0 +1 @@
+export declare function COMMAND_REFERENCE(): string;

package/dist/src/reference.js

@@ -0,0 +1,108 @@
+import { AUTH_FLAGS } from "./commands/auth.js";
+import { CHECK_FLAGS } from "./commands/check.js";
+import { DOCTOR_FLAGS } from "./commands/doctor.js";
+import { GUIDE_FLAGS } from "./commands/guide.js";
+import { LIST_FLAGS, SHOW_FLAGS } from "./commands/list.js";
+import { RECORD_FLAGS, REHEARSE_FLAGS } from "./commands/record.js";
+import { SCAFFOLD_FLAGS } from "./commands/scaffold.js";
+import { INIT_FLAGS, SETUP_FLAGS } from "./commands/setup.js";
+const COMMANDS = [
+    {
+        command: "init",
+        summary: "Write a config, a scenarios directory and a gitignore entry",
+        usage: "screencast-axi init",
+        flags: INIT_FLAGS,
+    },
+    {
+        command: "scaffold",
+        summary: "Write a scenario skeleton so the boilerplate is never what goes wrong",
+        usage: "screencast-axi scaffold <id>",
+        flags: SCAFFOLD_FLAGS,
+    },
+    {
+        command: "rehearse",
+        summary: "Run a scenario without recording, and print every action it took",
+        usage: "screencast-axi rehearse <id|path...>",
+        flags: REHEARSE_FLAGS,
+    },
+    {
+        command: "record",
+        summary: "Run a scenario for real and encode the clip",
+        usage: "screencast-axi record <id|path...>",
+        flags: RECORD_FLAGS,
+    },
+    {
+        command: "list",
+        summary: "Every scenario, with what needs re-shooting",
+        usage: "screencast-axi list",
+        flags: LIST_FLAGS,
+    },
+    {
+        command: "show",
+        summary: "One clip in full: files, sizes, narration, when it was shot",
+        usage: "screencast-axi show <id>",
+        flags: SHOW_FLAGS,
+    },
+    {
+        command: "check",
+        summary: "Cross-reference the manifest, the scenarios and the files on disk",
+        usage: "screencast-axi check",
+        flags: CHECK_FLAGS,
+    },
+    {
+        command: "doctor",
+        summary: "Check everything a recording needs, in one pass",
+        usage: "screencast-axi doctor",
+        flags: DOCTOR_FLAGS,
+    },
+    {
+        command: "setup",
+        summary: "Install the browser; name anything you must install yourself",
+        usage: "screencast-axi setup",
+        flags: SETUP_FLAGS,
+    },
+    {
+        command: "auth",
+        summary: "Sign in by hand once, or check the saved session still works",
+        usage: "screencast-axi auth login|check [name]",
+        flags: AUTH_FLAGS,
+    },
+    {
+        command: "guide",
+        summary: "Topic-sized guidance, pulled one topic at a time",
+        usage: "screencast-axi guide [topic]",
+        flags: GUIDE_FLAGS,
+    },
+];
+function renderFlags(flags) {
+    const entries = Object.entries(flags);
+    if (entries.length === 0)
+        return "_No flags._\n";
+    const rows = entries.map(([name, spec]) => {
+        const left = spec.kind === "boolean" ? `--${name}` : `--${name} <${spec.placeholder ?? "value"}>`;
+        const repeat = spec.repeat ? " Repeatable." : "";
+        return `| \`${left}\` | ${spec.description}.${repeat} |`;
+    });
+    return ["| Flag | What it does |", "| --- | --- |", ...rows].join("\n") + "\n";
+}
+export function COMMAND_REFERENCE() {
+    const parts = [
+        "Every command takes `--help`. Flags always come after the command:",
+        "`screencast-axi <command> [args] [flags]`. An unknown flag is a usage error rather than",
+        "something quietly ignored.",
+        "",
+    ];
+    for (const entry of COMMANDS) {
+        parts.push(`#### \`${entry.command}\``);
+        parts.push("");
+        parts.push(`${entry.summary}.`);
+        parts.push("");
+        parts.push("```sh");
+        parts.push(entry.usage);
+        parts.push("```");
+        parts.push("");
+        parts.push(renderFlags(entry.flags));
+    }
+    return parts.join("\n").trimEnd();
+}
+//# sourceMappingURL=reference.js.map

package/dist/src/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../src/reference.ts"],"names":[],"mappings":"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"}

package/dist/src/run.d.ts

@@ -0,0 +1,82 @@
+import { type ResolvedViewport } from "./browser.js";
+import { type ResolvedConfig } from "./config.js";
+import type { AuthIdentity } from "./auth/types.js";
+import { type DirectorAction } from "./director.js";
+import { type EncodeResult, type EncodeSettings } from "./encode.js";
+import { ScreencastError } from "./errors.js";
+import { type Forensics } from "./forensics.js";
+import { type ManifestEntry } from "./manifest.js";
+import { type Toolchain } from "./toolchain.js";
+import type { DefinedScenario, Viewport } from "./types.js";
+export type RunMode = "record" | "rehearse";
+export interface RunOptions {
+    readonly scenario: DefinedScenario;
+    readonly config: ResolvedConfig;
+    readonly mode: RunMode;
+    /** Source of the scenario module, hashed so staleness is answerable later. */
+    readonly sourceText?: string;
+    readonly baseUrl?: string;
+    readonly outDir?: string;
+    readonly pace?: number;
+    readonly headed?: boolean;
+    readonly device?: string;
+    readonly viewport?: Viewport;
+    readonly orientation?: "portrait" | "landscape";
+    readonly keepRaw?: boolean;
+    /** Per-run overrides on the encode settings, e.g. the looping formats. */
+    readonly deliverables?: Partial<EncodeSettings>;
+    /** Named strategy, or false to record signed out. */
+    readonly auth?: string | false;
+    readonly toolchain?: Toolchain;
+    /** Progress, to stderr. stdout stays reserved for the final payload. */
+    log?(message: string): void;
+}
+export interface RunResult {
+    readonly id: string;
+    readonly mode: RunMode;
+    readonly durationMs: number;
+    /** Of that, how much was pace-scaled pause rather than the app's own waits. */
+    readonly scaledPauseMs: number;
+    readonly pace: number;
+    readonly viewport: ResolvedViewport;
+    readonly steps: readonly string[];
+    /** Everything the scenario did, in order. */
+    readonly performed: readonly DirectorAction[];
+    /** Hosts the take actually visited - the safety-relevant summary. */
+    readonly hosts: readonly string[];
+    readonly identity?: AuthIdentity;
+    /** Present only for a recording. */
+    readonly encoded?: EncodeResult;
+    readonly manifestPath?: string;
+    readonly entry?: ManifestEntry;
+}
+/**
+ * A take failed. Carries what was on screen when it did.
+ *
+ * The forensics are the point: without them a stale selector is a bare
+ * timeout, and fixing it means another forty-second run to see anything.
+ */
+export declare class ScenarioFailure extends ScreencastError {
+    readonly scenarioId: string;
+    readonly phase: "setup" | "run" | "encode";
+    readonly forensics: Forensics;
+    readonly lastStep: number | null;
+    constructor(init: {
+        scenarioId: string;
+        phase: "setup" | "run" | "encode";
+        message: string;
+        forensics: Forensics;
+        lastStep: number | null;
+        suggestions: string[];
+    });
+}
+/**
+ * Every declared narration line must appear once, in order.
+ *
+ * This is what stops the written workflow drifting from the recorded one: the
+ * same array becomes the burnt-in caption, the manifest's step list and the
+ * text a site renders beside the clip, so a line that never went on screen
+ * would be a caption promising something the video does not show.
+ */
+export declare function assertScriptComplete(steps: readonly string[] | undefined, shown: readonly number[]): void;
+export declare function runScenario(options: RunOptions): Promise<RunResult>;