demowright 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# demowright
+
+Playwright HUD plugin — renders a visible **mouse cursor**, **keystroke display**, **auto-slowdown**, **TTS narration**, and **subtitles** into test video recordings, making them readable by humans and AI (e.g. Gemini video analysis).
+
+## Demos
+
+> 6 runnable examples in `examples/` — see [Examples guide](./docs/examples.md)
+
+| # | Demo | What it shows |
+|---|------|---------------|
+| 01 | [Dashboard](examples/01-cursor-demo.spec.ts) | Cursor, clicks, Ctrl+K search, modal form typing |
+| 02 | [Monaco Editor](examples/02-keyboard-demo.spec.ts) | Real VS Code editor — typing, Ctrl+S/Z/A, tab switching |
+| 03 | [E-commerce Checkout](examples/03-form-interaction.spec.ts) | Browse, add to cart, fill payment form with `annotate()` |
+| 04 | [Narrated Tour](examples/04-narrated-tour.spec.ts) | SaaS landing page tour — heavy TTS + subtitles |
+| 05 | [Kanban Board](examples/05-kanban-board.spec.ts) | Move cards between columns, add tasks |
+| 06 | [Native API](examples/06-native-api.spec.ts) | **Zero helpers** — `page.click()`, `page.fill()` only |
+
+```bash
+npx playwright test --config examples/playwright.config.ts  # run all 6
+```
+
+## Problem
+
+Playwright's video recording doesn't capture the browser cursor or keyboard input. Tests run too fast for meaningful video review.
+
+## Solution
+
+`demowright` injects a lightweight overlay into every page during test execution:
+
+- 🖱️ **Visible cursor** — SVG pointer follows mouse with click ripple effects
+- ⌨️ **Keystroke display** — keys shown as HUD badges; modifier keys (Shift/Ctrl/Alt) as persistent blue badges
+- 🐢 **Auto-slowdown** — configurable delays after actions for human-readable recordings
+- 🗣️ **TTS narration** — spoken annotations via pluggable providers (OpenAI, ElevenLabs, espeak, URL template)
+- 💬 **Subtitles** — visual text overlays that fade in/out during recordings
+- 🎵 **Audio capture** — record browser audio to WAV via Web Audio API tap
+- 🔌 **Non-invasive** — 4 integration methods, from zero-change config to full programmatic control
+
+## Quick Start
+
+```bash
+npm install demowright
+```
+
+### Zero-change setup (recommended) ⭐
+
+Add one line to your `playwright.config.ts` — no test files need to change:
+
+```ts
+// playwright.config.ts
+import { defineConfig } from "@playwright/test";
+import { withDemowright } from "demowright/config";
+
+export default withDemowright(
+  defineConfig({
+    use: { video: "on" },
+  }),
+);
+```
+
+Your existing tests keep using `import { test } from '@playwright/test'` — the HUD is injected automatically.
+
+### Alternative: CLI flag (zero code changes at all)
+
+```bash
+NODE_OPTIONS="--require demowright/register" npx playwright test
+```
+
+### Alternative: Import replacement
+
+```ts
+// Change this:
+import { test, expect } from "@playwright/test";
+// To this:
+import { test, expect } from "demowright";
+```
+
+### Alternative: Programmatic (full control)
+
+```ts
+import { test as base } from "@playwright/test";
+import { applyHud } from "demowright";
+
+const test = base.extend({
+  context: async ({ context }, use) => {
+    await applyHud(context, { cursor: true, keyboard: true, actionDelay: 150 });
+    await use(context);
+  },
+});
+```
+
+## Configuration
+
+```ts
+// Via withDemowright (recommended)
+export default withDemowright(defineConfig({ ... }), {
+  actionDelay: 200,
+  cursorStyle: 'dot',
+});
+
+// Via test.use (import replacement approach)
+test.use({
+  qaHud: {
+    cursor: true,            // show cursor overlay (default: true)
+    keyboard: true,          // show keystroke display (default: true)
+    cursorStyle: 'default',  // 'default' | 'dot' | 'crosshair'
+    keyFadeMs: 1500,         // key label fade time in ms
+    actionDelay: 120,        // delay after each action for readability (ms)
+    audio: false,            // path to save WAV, or false to disable
+    tts: false,              // TTS provider: URL template, function, or false
+  },
+});
+
+// Via env vars (CLI approach)
+QA_HUD_CURSOR=0 QA_HUD_DELAY=200 NODE_OPTIONS="--require demowright/register" npx playwright test
+```
+
+| Env Var                   | Description               | Default   |
+| ------------------------- | ------------------------- | --------- |
+| `QA_HUD=0`                | Disable HUD entirely      | enabled   |
+| `QA_HUD_CURSOR=0`         | Disable cursor overlay    | enabled   |
+| `QA_HUD_KEYBOARD=0`       | Disable keyboard display  | enabled   |
+| `QA_HUD_DELAY=200`        | Action delay in ms        | `120`     |
+| `QA_HUD_CURSOR_STYLE=dot` | Cursor style              | `default` |
+| `QA_HUD_KEY_FADE=2000`    | Key label fade time in ms | `1500`    |
+| `QA_HUD_TTS=url`          | TTS URL template (`%s`)   | disabled  |
+
+## Helpers — Recording-Only Convenience Functions
+
+```ts
+import { clickEl, typeKeys, narrate, annotate, hudWait } from "demowright/helpers";
+
+await annotate(page, "Welcome to the product tour"); // subtitle + TTS
+await clickEl(page, "#get-started");                  // animated cursor + ripple + click
+await typeKeys(page, "hello@example.com", 60, "#email"); // char-by-char with key badges
+await hudWait(page, 500);                              // waits only during recording
+await narrate(page, "Now let's submit the form");      // TTS narration
+```
+
+All helpers are **no-ops when HUD is inactive** — safe to leave in production tests.
+
+## TTS Narration
+
+Configure a TTS provider for spoken narration in recordings:
+
+```ts
+export default withDemowright(defineConfig({ ... }), {
+  tts: "http://localhost:5000/tts?text=%s", // URL template
+  audio: "test-audio.wav",                   // capture audio to WAV
+});
+```
+
+Or use a function for APIs requiring auth (OpenAI, ElevenLabs, etc.):
+
+```ts
+await applyHud(context, {
+  tts: async (text) => {
+    const res = await fetch("https://api.openai.com/v1/audio/speech", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ model: "tts-1", voice: "alloy", input: text }),
+    });
+    return Buffer.from(await res.arrayBuffer());
+  },
+});
+```
+
+## How It Works
+
+1. **Event listeners** are injected via `context.addInitScript()` — captures mouse/keyboard events before DOM exists, survives navigations
+2. **DOM overlay** is injected via `page.evaluate()` after each navigation (`goto`, `reload`, `setContent`, etc.)
+3. The overlay uses `pointer-events: none` and max z-index — never interferes with test interactions
+4. Page actions (`click`, `fill`, `type`, etc.) are wrapped with configurable delays for video readability
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](./docs/getting-started.md) | Installation, 4 integration methods, configuration |
+| [Helpers API](./docs/helpers.md) | `clickEl`, `typeKeys`, `moveTo`, `hudWait` reference |
+| [Narration & Subtitles](./docs/narration.md) | `narrate()`, `subtitle()`, `annotate()` |
+| [TTS Setup](./docs/tts.md) | Configuring text-to-speech providers |
+| [Cursor & Keyboard](./docs/cursor-keyboard.md) | Cursor styles, key badges, click ripples, auto-slowdown |
+| [Audio Capture](./docs/audio.md) | Recording browser audio to WAV |
+| [Examples](./docs/examples.md) | 6 runnable demo scenarios |
+| [Wrapper Strategies](./docs/wrapper.md) | Making native Playwright calls show the HUD |
+
+## License
+
+MIT

package/dist/auto-annotate.d.mts

@@ -0,0 +1,6 @@
+import { test } from "@playwright/test";
+
+//#region src/auto-annotate.d.ts
+declare function installAutoAnnotate(test: typeof test): void;
+//#endregion
+export { installAutoAnnotate };

package/dist/auto-annotate.mjs

@@ -0,0 +1,9 @@
+//#region src/auto-annotate.ts
+function installAutoAnnotate(test) {
+	test.beforeEach(async ({ page }, testInfo) => {
+		const { annotate } = await import("./helpers.mjs");
+		await annotate(page, testInfo.titlePath.length > 1 ? testInfo.titlePath.join(" › ") : testInfo.title);
+	});
+}
+//#endregion
+export { installAutoAnnotate };

package/dist/chunk-C0p4GxOx.mjs

@@ -0,0 +1,29 @@
+import "node:module";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toCommonJS = (mod) => __hasOwnProp.call(mod, "module.exports") ? mod["module.exports"] : __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+//#endregion
+export { __exportAll as n, __toCommonJS as r, __esmMin as t };

package/dist/config.d.mts

@@ -0,0 +1,7 @@
+import { t as QaHudOptions } from "./setup-D-Ut4FYK.mjs";
+import { PlaywrightTestConfig } from "@playwright/test";
+
+//#region src/config.d.ts
+declare function withDemowright(config: PlaywrightTestConfig, options?: Partial<QaHudOptions>): PlaywrightTestConfig;
+//#endregion
+export { type QaHudOptions, withDemowright };

package/dist/config.mjs

@@ -0,0 +1,36 @@
+import { n as defaultOptions } from "./setup-CfPylVYx.mjs";
+import { createRequire } from "node:module";
+//#region src/config.ts
+/**
+* Approach 3: Config helper (one line in playwright.config.ts).
+*
+*   import { defineConfig } from '@playwright/test';
+*   import { withDemowright } from 'demowright/config';
+*
+*   export default withDemowright(defineConfig({ ... }));
+*
+* Sets NODE_OPTIONS to --require demowright/register so the HUD is injected
+* into every BrowserContext automatically. No test file changes needed.
+*/
+function withDemowright(config, options) {
+	const opts = {
+		...defaultOptions,
+		...options
+	};
+	const registerPath = createRequire(import.meta.url).resolve("../register.cjs");
+	if (!opts.cursor) process.env.QA_HUD_CURSOR = "0";
+	if (!opts.keyboard) process.env.QA_HUD_KEYBOARD = "0";
+	if (opts.actionDelay !== defaultOptions.actionDelay) process.env.QA_HUD_DELAY = String(opts.actionDelay);
+	if (opts.cursorStyle !== defaultOptions.cursorStyle) process.env.QA_HUD_CURSOR_STYLE = opts.cursorStyle;
+	if (opts.keyFadeMs !== defaultOptions.keyFadeMs) process.env.QA_HUD_KEY_FADE = String(opts.keyFadeMs);
+	if (typeof opts.tts === "string") process.env.QA_HUD_TTS = opts.tts;
+	if (opts.audio) process.env.QA_HUD_AUDIO = typeof opts.audio === "string" ? opts.audio : "1";
+	if (opts.autoAnnotate) process.env.QA_HUD_AUTO_ANNOTATE = "1";
+	if (opts.outputDir !== defaultOptions.outputDir) process.env.QA_HUD_OUTPUT_DIR = opts.outputDir;
+	const flag = `--require ${registerPath}`;
+	const existing = process.env.NODE_OPTIONS || "";
+	if (!existing.includes(flag)) process.env.NODE_OPTIONS = existing ? `${existing} ${flag}` : flag;
+	return config;
+}
+//#endregion
+export { withDemowright };

package/dist/helpers.d.mts

@@ -0,0 +1,95 @@
+import { Page } from "@playwright/test";
+
+//#region src/helpers.d.ts
+/**
+ * Wait for `ms` milliseconds, but only when demowright is active.
+ * Use this instead of `page.waitForTimeout()` for recording-only pauses.
+ */
+declare function hudWait(page: Page, ms: number): Promise<void>;
+/**
+ * Smoothly move the HUD cursor to (x, y) over `steps` frames.
+ * No-op when HUD is inactive.
+ */
+declare function moveTo(page: Page, x: number, y: number, steps?: number): Promise<void>;
+/**
+ * Smoothly move the HUD cursor to the center of `selector`.
+ * Returns the element center coordinates.
+ * When HUD is inactive, resolves coordinates but skips the animation.
+ */
+declare function moveToEl(page: Page, selector: string): Promise<{
+  x: number;
+  y: number;
+}>;
+/**
+ * Animated click on `selector` — moves cursor, fires mousedown/mouseup
+ * ripple, then performs the actual DOM click.
+ * When HUD is inactive, performs only the DOM click (no animation/delays).
+ */
+declare function clickEl(page: Page, selector: string): Promise<void>;
+/**
+ * Type `text` character-by-character with visible key badges.
+ * When HUD is inactive, sets the input value directly.
+ *
+ * @param inputSelector — optional selector for the input element to update.
+ *   If omitted, uses `document.activeElement`.
+ */
+declare function typeKeys(page: Page, text: string, delay?: number, inputSelector?: string): Promise<void>;
+/**
+ * Speak `text` via the configured TTS provider, or fall back to
+ * the browser's speechSynthesis API.
+ *
+ * When called with a callback, pre-fetches the TTS audio, then runs
+ * the callback actions in parallel with audio playback — waiting for
+ * whichever takes longer. This keeps narration and actions in sync.
+ *
+ * ```ts
+ * // TTS only
+ * await narrate(page, "Processing complete");
+ *
+ * // TTS + actions timed together
+ * await narrate(page, "Now let's fill the form", async () => {
+ *   await clickEl(page, "#name");
+ *   await typeKeys(page, "Alice");
+ * });
+ * ```
+ *
+ * When HUD is inactive, only the callback runs (instantly, no TTS).
+ */
+declare function narrate(page: Page, text: string, callbackOrOptions?: (() => Promise<void>) | {
+  rate?: number;
+  pitch?: number;
+  volume?: number;
+  voice?: string;
+}, callback?: () => Promise<void>): Promise<void>;
+/**
+ * Show a caption text overlay on the page for `durationMs` milliseconds.
+ * Useful as a visual annotation in recordings. No-op when HUD is inactive.
+ */
+declare function caption(page: Page, text: string, durationMs?: number): Promise<void>;
+/** @deprecated Use `caption()` instead. */
+declare const subtitle: typeof caption;
+/**
+ * Show a caption + speak it via TTS simultaneously.
+ * When called with a callback, runs the actions in parallel with
+ * the narration — waiting for whichever takes longer.
+ *
+ * ```ts
+ * // Caption + TTS
+ * await annotate(page, "Welcome to the tour");
+ *
+ * // Caption + TTS + actions
+ * await annotate(page, "Let's fill the form", async () => {
+ *   await clickEl(page, "#name");
+ *   await typeKeys(page, "Alice");
+ * });
+ * ```
+ *
+ * No-op when HUD is inactive (callback still runs).
+ */
+declare function annotate(page: Page, text: string, callbackOrOptions?: (() => Promise<void>) | {
+  durationMs?: number;
+  rate?: number;
+  voice?: string;
+}, callback?: () => Promise<void>): Promise<void>;
+//#endregion
+export { annotate, caption, clickEl, hudWait, moveTo, moveToEl, narrate, subtitle, typeKeys };