demowright 0.1.0

package/dist/helpers.mjs

@@ -0,0 +1,299 @@
+import { a as getTtsProvider, o as init_hud_registry, s as isHudActive, u as storeAudioSegment } from "./hud-registry-CptkyV32.mjs";
+//#region src/helpers.ts
+init_hud_registry();
+/**
+* Wait for `ms` milliseconds, but only when demowright is active.
+* Use this instead of `page.waitForTimeout()` for recording-only pauses.
+*/
+async function hudWait(page, ms) {
+	if (!await isHudActive(page)) return;
+	await page.waitForTimeout(ms);
+}
+/**
+* Smoothly move the HUD cursor to (x, y) over `steps` frames.
+* No-op when HUD is inactive.
+*/
+async function moveTo(page, x, y, steps = 10) {
+	if (!await isHudActive(page)) return;
+	const start = await page.evaluate(() => ({
+		x: window.__qaHud?.cx ?? 0,
+		y: window.__qaHud?.cy ?? 0
+	}));
+	for (let i = 1; i <= steps; i++) {
+		const t = i / steps;
+		await page.evaluate(([mx, my]) => document.dispatchEvent(new MouseEvent("mousemove", {
+			clientX: mx,
+			clientY: my,
+			bubbles: true
+		})), [start.x + (x - start.x) * t, start.y + (y - start.y) * t]);
+		await page.waitForTimeout(20);
+	}
+}
+/**
+* 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.
+*/
+async function moveToEl(page, selector) {
+	const center = await page.evaluate((s) => {
+		const r = document.querySelector(s).getBoundingClientRect();
+		return {
+			x: r.x + r.width / 2,
+			y: r.y + r.height / 2
+		};
+	}, selector);
+	if (await isHudActive(page)) await moveTo(page, center.x, center.y);
+	return center;
+}
+/**
+* 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).
+*/
+async function clickEl(page, selector) {
+	const active = await isHudActive(page);
+	if (active) {
+		const c = await moveToEl(page, selector);
+		await page.waitForTimeout(150);
+		await page.evaluate(([x, y]) => {
+			document.dispatchEvent(new MouseEvent("mousedown", {
+				clientX: x,
+				clientY: y,
+				bubbles: true
+			}));
+			setTimeout(() => document.dispatchEvent(new MouseEvent("mouseup", {
+				clientX: x,
+				clientY: y,
+				bubbles: true
+			})), 60);
+		}, [c.x, c.y]);
+	}
+	await page.evaluate((s) => document.querySelector(s)?.click(), selector);
+	if (active) await page.waitForTimeout(100);
+}
+/**
+* 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`.
+*/
+async function typeKeys(page, text, delay = 65, inputSelector) {
+	if (!await isHudActive(page)) {
+		await page.evaluate(([t, sel]) => {
+			const el = sel ? document.querySelector(sel) : document.activeElement;
+			if (el && "value" in el) {
+				el.value = t;
+				el.dispatchEvent(new Event("input", { bubbles: true }));
+				el.dispatchEvent(new Event("change", { bubbles: true }));
+			}
+		}, [text, inputSelector]);
+		return;
+	}
+	for (let i = 0; i < text.length; i++) {
+		await page.evaluate(([k, sel, partial]) => {
+			document.dispatchEvent(new KeyboardEvent("keydown", {
+				key: k,
+				bubbles: true
+			}));
+			const el = sel ? document.querySelector(sel) : document.activeElement;
+			if (el && "value" in el) el.value = partial;
+		}, [
+			text[i],
+			inputSelector,
+			text.slice(0, i + 1)
+		]);
+		await page.waitForTimeout(delay);
+	}
+}
+/** Fetch audio from a TTS provider. Returns a WAV Buffer. */
+async function fetchTtsAudio(text, provider) {
+	if (typeof provider === "string") {
+		const url = provider.replace(/%s/g, encodeURIComponent(text));
+		const res = await fetch(url);
+		if (!res.ok) throw new Error(`TTS fetch ${res.status}`);
+		return Buffer.from(await res.arrayBuffer());
+	}
+	const result = await provider(text);
+	return Buffer.isBuffer(result) ? result : Buffer.from(result);
+}
+/** Parse WAV and return { float32, sampleRate, channels, durationMs }. */
+function parseWav(wavBuf) {
+	const dataOffset = wavBuf.indexOf("data") + 8;
+	if (dataOffset < 8) throw new Error("Invalid WAV");
+	const sampleRate = wavBuf.readUInt32LE(24);
+	const channels = wavBuf.readUInt16LE(22);
+	const pcmData = wavBuf.subarray(dataOffset);
+	const sampleCount = pcmData.length / 2;
+	const float32 = new Float32Array(sampleCount);
+	for (let i = 0; i < sampleCount; i++) float32[i] = pcmData.readInt16LE(i * 2) / 32768;
+	return {
+		float32,
+		sampleRate,
+		channels,
+		sampleCount,
+		durationMs: sampleCount / channels / sampleRate * 1e3
+	};
+}
+/**
+* Store TTS audio segment with its timestamp for deferred track building.
+* The complete audio track is assembled at context close using actual
+* wall-clock timestamps, eliminating drift from page.evaluate overhead.
+*/
+async function playTtsAudio(page, wavBuf) {
+	const { durationMs } = parseWav(wavBuf);
+	storeAudioSegment(page, {
+		timestampMs: Date.now(),
+		wavBuf
+	});
+	await page.waitForTimeout(durationMs);
+}
+/**
+* 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).
+*/
+async function narrate(page, text, callbackOrOptions, callback) {
+	const cb = typeof callbackOrOptions === "function" ? callbackOrOptions : callback;
+	const options = typeof callbackOrOptions === "object" ? callbackOrOptions : void 0;
+	if (!await isHudActive(page)) {
+		await cb?.();
+		return;
+	}
+	const provider = getTtsProvider(page);
+	if (provider) try {
+		const wavBuf = await fetchTtsAudio(text, provider);
+		if (cb) await Promise.all([playTtsAudio(page, wavBuf), cb()]);
+		else await playTtsAudio(page, wavBuf);
+		return;
+	} catch {}
+	const opts = {
+		rate: options?.rate ?? 1,
+		pitch: options?.pitch ?? 1,
+		volume: options?.volume ?? 1,
+		voice: options?.voice
+	};
+	const speechPromise = page.evaluate(([t, o]) => {
+		return new Promise((resolve) => {
+			const synth = window.speechSynthesis;
+			if (!synth) {
+				resolve();
+				return;
+			}
+			try {
+				const utter = new SpeechSynthesisUtterance(t);
+				utter.rate = o.rate;
+				utter.pitch = o.pitch;
+				utter.volume = o.volume;
+				if (o.voice) {
+					const match = synth.getVoices().find((v) => v.name === o.voice || v.lang === o.voice);
+					if (match) utter.voice = match;
+				}
+				utter.onend = () => resolve();
+				utter.onerror = () => resolve();
+				const timeout = Math.min(5e3, Math.max(1e3, t.length * 80));
+				setTimeout(resolve, timeout);
+				synth.speak(utter);
+			} catch {
+				resolve();
+			}
+		});
+	}, [text, opts]);
+	if (cb) await Promise.all([speechPromise, cb()]);
+	else await speechPromise;
+}
+/**
+* Show a caption text overlay on the page for `durationMs` milliseconds.
+* Useful as a visual annotation in recordings. No-op when HUD is inactive.
+*/
+async function caption(page, text, durationMs = 3e3) {
+	if (!await isHudActive(page)) return;
+	await page.evaluate(([t, d]) => {
+		const el = document.createElement("div");
+		el.textContent = t;
+		el.style.cssText = [
+			"position:fixed",
+			"bottom:60px",
+			"left:50%",
+			"transform:translateX(-50%)",
+			"background:rgba(0,0,0,0.8)",
+			"color:#fff",
+			"font-family:system-ui,sans-serif",
+			"font-size:18px",
+			"padding:10px 24px",
+			"border-radius:8px",
+			"z-index:2147483647",
+			"pointer-events:none",
+			"white-space:nowrap",
+			"max-width:90vw",
+			"text-align:center",
+			`animation:qa-sub-fade ${d}ms ease-out forwards`
+		].join(";");
+		if (!document.querySelector("#qa-sub-style")) {
+			const style = document.createElement("style");
+			style.id = "qa-sub-style";
+			style.textContent = `
+          @keyframes qa-sub-fade {
+            0%   { opacity: 0; transform: translateX(-50%) translateY(10px); }
+            8%   { opacity: 1; transform: translateX(-50%) translateY(0); }
+            85%  { opacity: 1; transform: translateX(-50%) translateY(0); }
+            100% { opacity: 0; transform: translateX(-50%) translateY(-10px); }
+          }
+        `;
+			document.head.appendChild(style);
+		}
+		document.body.appendChild(el);
+		setTimeout(() => el.remove(), d);
+	}, [text, durationMs]);
+}
+/** @deprecated Use `caption()` instead. */
+const subtitle = 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).
+*/
+async function annotate(page, text, callbackOrOptions, callback) {
+	const cb = typeof callbackOrOptions === "function" ? callbackOrOptions : callback;
+	const options = typeof callbackOrOptions === "object" ? callbackOrOptions : void 0;
+	if (!await isHudActive(page)) {
+		await cb?.();
+		return;
+	}
+	const durationMs = options?.durationMs ?? 4e3;
+	await Promise.all([caption(page, text, durationMs), narrate(page, text, {
+		rate: options?.rate,
+		voice: options?.voice
+	}, cb)]);
+}
+//#endregion
+export { annotate, caption, clickEl, hudWait, moveTo, moveToEl, narrate, subtitle, typeKeys };

package/dist/hud-registry-CptkyV32.mjs

@@ -0,0 +1,90 @@
+import { t as __esmMin } from "./chunk-C0p4GxOx.mjs";
+//#region src/hud-registry.ts
+function registerHudPage(page, config) {
+	hudPages.set(page, config ?? { tts: false });
+	if (config?.tts) g.__qaHudGlobal.tts = config.tts;
+}
+/**
+* Check if demowright is active on this page.
+* Checks the Node-side registry first (fast), falls back to querying
+* the browser for window.__qaHud (covers the config/register approach).
+*/
+async function isHudActive(page) {
+	if (hudPages.has(page)) return true;
+	try {
+		const active = await page.evaluate(() => !!window.__qaHud);
+		if (active) hudPages.set(page, { tts: g.__qaHudGlobal.tts || false });
+		return active;
+	} catch {
+		return false;
+	}
+}
+/**
+* Get TTS provider configured for this page (if any).
+*/
+function getTtsProvider(page) {
+	return hudPages.get(page)?.tts || g.__qaHudGlobal.tts || false;
+}
+/**
+* Get the global TTS provider (set by register.cjs or applyHud).
+* Useful for pre-generating audio before a page/context exists.
+*/
+function getGlobalTtsProvider() {
+	return g.__qaHudGlobal.tts || false;
+}
+function setGlobalOutputDir(dir) {
+	g.__qaHudGlobal.outputDir = dir;
+}
+function getGlobalOutputDir() {
+	return g.__qaHudGlobal.outputDir || ".demowright";
+}
+/**
+* Store a TTS audio segment with its wall-clock timestamp.
+* Used for deferred audio track building at context close.
+*/
+function storeAudioSegment(page, segment) {
+	let segs = audioSegments.get(page);
+	if (!segs) {
+		segs = [];
+		audioSegments.set(page, segs);
+	}
+	segs.push(segment);
+	const pageId = page._guid || String(Date.now());
+	if (!g.__qaHudGlobal.audioSegments.has(pageId)) g.__qaHudGlobal.audioSegments.set(pageId, segs);
+}
+/**
+* Get all stored audio segments for a page.
+*/
+function getAudioSegments(page) {
+	const local = audioSegments.get(page);
+	if (local && local.length > 0) return local;
+	const pageId = page._guid;
+	if (pageId) return g.__qaHudGlobal.audioSegments.get(pageId) ?? [];
+	return [];
+}
+function storeRenderJob(page, job) {
+	renderJobs.set(page, job);
+	const pageId = page._guid || String(Date.now());
+	if (!g.__qaHudGlobal.renderJobs) g.__qaHudGlobal.renderJobs = /* @__PURE__ */ new Map();
+	g.__qaHudGlobal.renderJobs.set(pageId, job);
+}
+function getRenderJob(page) {
+	const local = renderJobs.get(page);
+	if (local) return local;
+	const pageId = page._guid;
+	if (pageId) return g.__qaHudGlobal.renderJobs?.get(pageId);
+}
+var hudPages, audioSegments, g, renderJobs;
+var init_hud_registry = __esmMin((() => {
+	hudPages = /* @__PURE__ */ new WeakMap();
+	audioSegments = /* @__PURE__ */ new WeakMap();
+	g = globalThis;
+	if (!g.__qaHudGlobal) g.__qaHudGlobal = {
+		tts: false,
+		audioSegments: /* @__PURE__ */ new Map(),
+		outputDir: ".demowright"
+	};
+	renderJobs = /* @__PURE__ */ new WeakMap();
+}));
+//#endregion
+export { getTtsProvider as a, registerHudPage as c, storeRenderJob as d, getRenderJob as i, setGlobalOutputDir as l, getGlobalOutputDir as n, init_hud_registry as o, getGlobalTtsProvider as r, isHudActive as s, getAudioSegments as t, storeAudioSegment as u };