π¬ A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots π
TypeScript browser-extensionchrome-extensiondocumentationfirefox-extensionguide-generatorlocal-firstmanifest-v3privacy-firstproductivityreactscreenshotstep-by-step-guidetutorialtypescriptworkflowwxt
fix(recording): bring the microphone back after a pause
davbio6dccb89a5086
diff --git a/src/core/capture/machine.ts b/src/core/capture/machine.tsindex 1dfafff..9d7a3bc 100644--- a/src/core/capture/machine.ts+++ b/src/core/capture/machine.ts@@ -13,7 +13,7 @@ export type PauseReason = 'blur' | 'manual';type CaptureEvent =| { type: 'START_RECORDING'; url?: string; insertTargetGuideId?: string; insertAtIndex?: number }| { type: 'STOP_RECORDING' }- | { type: 'PAUSE_CAPTURE'; reason: PauseReason }+ | { type: 'PAUSE_CAPTURE'; reason: PauseReason; narrationWasLive?: boolean }| { type: 'RESUME_CAPTURE' }| { type: 'USER_ACTION' }| { type: 'URL_CHANGED'; url: string };@@ -25,6 +25,7 @@ interface CaptureContext {insertTargetGuideId: string | null;insertAtIndex: number | null;pauseReason: PauseReason | null;+ narrationWasLive: boolean;}const IDLE_CONTEXT: CaptureContext = {@@ -34,6 +35,7 @@ const IDLE_CONTEXT: CaptureContext = {insertTargetGuideId: null,insertAtIndex: null,pauseReason: null,+ narrationWasLive: false,};export const captureMachine = createMachine({@@ -56,6 +58,7 @@ export const captureMachine = createMachine({insertTargetGuideId: ({ event }) => event.insertTargetGuideId ?? null,insertAtIndex: ({ event }) => event.insertAtIndex ?? null,pauseReason: null,+ narrationWasLive: false,}),},},@@ -70,6 +73,7 @@ export const captureMachine = createMachine({target: CaptureState.PAUSED,actions: assign({pauseReason: ({ event }) => event.reason,+ narrationWasLive: ({ event }) => event.narrationWasLive === true,}),},USER_ACTION: {@@ -88,7 +92,7 @@ export const captureMachine = createMachine({on: {RESUME_CAPTURE: {target: CaptureState.RECORDING,- actions: assign({ pauseReason: null }),+ actions: assign({ pauseReason: null, narrationWasLive: false }),},STOP_RECORDING: {target: CaptureState.IDLE,diff --git a/src/entrypoints/background/__tests__/pause-narration.test.ts b/src/entrypoints/background/__tests__/pause-narration.test.tsnew file mode 100644index 0000000..435d64c--- /dev/null+++ b/src/entrypoints/background/__tests__/pause-narration.test.ts@@ -0,0 +1,180 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';+import { createActor } from 'xstate';+import { captureMachine } from '@/core/capture/machine';++let actor: ReturnType<typeof createActor<typeof captureMachine>>;++const stopVoiceNarration = vi.fn();+const whenNarrationSettled = vi.fn();+const reportNarrationLost = vi.fn();+let voicePhase = 'idle';+let hostIsRecording = false;++vi.mock('../actor', () => ({ getActor: () => actor, waitUntilReady: () => Promise.resolve() }));+vi.mock('@/lib/browser-api', () => ({ getActiveTab: () => Promise.resolve({ id: 1, url: 'https://app.test' }) }));+vi.mock('@/lib/logger', () => ({ logger: { info: vi.fn(), debug: vi.fn(), warn: vi.fn(), error: vi.fn() } }));+vi.mock('../tab-manager', () => ({+ broadcastDismissBlur: vi.fn().mockResolvedValue(undefined),+ broadcastStartCapture: vi.fn().mockResolvedValue(undefined),+ broadcastStopCaptureAndFlush: vi.fn().mockResolvedValue(undefined),+ injectContentScript: vi.fn().mockResolvedValue(undefined),+ isInjectableTab: () => true,+}));+vi.mock('../voice', () => ({+ getVoiceUpdate: () => ({ type: 'VOICE_UPDATE', phase: voicePhase }),+ isNarrationLive: () => Promise.resolve(voicePhase === 'recording' || hostIsRecording),+ isNarrationSettling: () => voicePhase === 'transcribing',+ reportNarrationLost: (...args: unknown[]) => reportNarrationLost(...args),+ stopVoiceNarration: (...args: unknown[]) => stopVoiceNarration(...args),+ whenNarrationSettled: (...args: unknown[]) => whenNarrationSettled(...args),+}));++import { pauseCapture, restartNarrationOnceTranscriptionSettles, resumeCapture } from '../pause';++const flush = () => new Promise((resolve) => setTimeout(resolve, 0));++beforeEach(() => {+ vi.clearAllMocks();+ voicePhase = 'idle';+ hostIsRecording = false;+ whenNarrationSettled.mockResolvedValue(undefined);+ stopVoiceNarration.mockResolvedValue(undefined);+ actor = createActor(captureMachine);+ actor.start();+ actor.send({ type: 'START_RECORDING', url: 'https://app.test/a' });+});++describe('remembering that narration was on', () => {+ it('records it in the machine context, which survives a worker restart', async () => {+ voicePhase = 'recording';++ await pauseCapture('manual');++ expect(actor.getSnapshot().context.narrationWasLive).toBe(true);+ expect(stopVoiceNarration).toHaveBeenCalledWith(actor.getSnapshot().context.currentGuideId);+ });++ it('asks the microphone host when the in-memory phase was lost to an eviction', async () => {+ voicePhase = 'idle';+ hostIsRecording = true;++ await pauseCapture('manual');++ expect(actor.getSnapshot().context.narrationWasLive).toBe(true);+ expect(stopVoiceNarration).toHaveBeenCalled();+ });++ it('counts a still-transcribing flush from an earlier pause as live', async () => {+ voicePhase = 'transcribing';++ await pauseCapture('manual');++ expect(actor.getSnapshot().context.narrationWasLive).toBe(true);+ });++ it('leaves the flag off when nothing was being narrated', async () => {+ await pauseCapture('manual');++ expect(actor.getSnapshot().context.narrationWasLive).toBe(false);+ expect(stopVoiceNarration).not.toHaveBeenCalled();+ });++ it('clears the flag on resume so a later pause starts clean', async () => {+ voicePhase = 'recording';+ await pauseCapture('manual');+ await resumeCapture(vi.fn().mockResolvedValue(true));++ expect(actor.getSnapshot().context.narrationWasLive).toBe(false);+ });+});++describe('restarting narration after the pause', () => {+ it('answers the panel without waiting for the transcription round-trip', async () => {+ voicePhase = 'recording';+ await pauseCapture('manual');+ voicePhase = 'transcribing';++ let settle = () => {};+ whenNarrationSettled.mockReturnValue(+ new Promise<void>((resolve) => {+ settle = resolve;+ }),+ );++ await expect(resumeCapture(vi.fn().mockResolvedValue(false))).resolves.toBe(true);+ expect(actor.getSnapshot().value).toBe('RECORDING');++ settle();+ });++ it('does not wait on the transcription when the first attempt works', async () => {+ voicePhase = 'recording';+ await pauseCapture('manual');++ const start = vi.fn().mockResolvedValue(true);+ await resumeCapture(start);+ await flush();++ expect(start).toHaveBeenCalledTimes(1);+ expect(whenNarrationSettled).not.toHaveBeenCalled();+ });++ it('does not restart narration that was not running before the pause', async () => {+ await pauseCapture('manual');++ const start = vi.fn().mockResolvedValue(true);+ await resumeCapture(start);+ await flush();++ expect(start).not.toHaveBeenCalled();+ });+});++describe('the retry that waits for the transcription', () => {+ it('tries again once the pending transcription settles', async () => {+ voicePhase = 'transcribing';+ const start = vi.fn().mockImplementation(() => {+ if (start.mock.calls.length > 1) return true;+ return false;+ });+ whenNarrationSettled.mockImplementation(() => {+ voicePhase = 'idle';+ return Promise.resolve();+ });++ await expect(restartNarrationOnceTranscriptionSettles(start)).resolves.toBe(true);++ expect(start).toHaveBeenCalledTimes(2);+ expect(reportNarrationLost).not.toHaveBeenCalled();+ });++ it('keeps waiting while the transcription outlives one settle timeout', async () => {+ voicePhase = 'transcribing';+ const start = vi.fn().mockImplementation(() => start.mock.calls.length > 3);++ await expect(restartNarrationOnceTranscriptionSettles(start)).resolves.toBe(true);++ expect(start).toHaveBeenCalledTimes(4);+ expect(whenNarrationSettled).toHaveBeenCalledTimes(3);+ });++ it('gives up without a second start when the start itself failed', async () => {+ voicePhase = 'idle';+ const start = vi.fn().mockResolvedValue(false);++ await expect(restartNarrationOnceTranscriptionSettles(start)).resolves.toBe(false);++ expect(start).toHaveBeenCalledTimes(1);+ expect(whenNarrationSettled).not.toHaveBeenCalled();+ expect(reportNarrationLost).toHaveBeenCalled();+ });++ it('tells the panel narration is gone when the budget runs out', async () => {+ voicePhase = 'transcribing';+ const start = vi.fn().mockResolvedValue(false);++ await expect(restartNarrationOnceTranscriptionSettles(start)).resolves.toBe(false);++ expect(reportNarrationLost).toHaveBeenCalled();+ });+});diff --git a/src/entrypoints/background/__tests__/pause.test.ts b/src/entrypoints/background/__tests__/pause.test.tsindex 757f2ad..396afe5 100644--- a/src/entrypoints/background/__tests__/pause.test.ts+++ b/src/entrypoints/background/__tests__/pause.test.ts@@ -30,7 +30,11 @@ vi.mock('../tab-manager', () => ({vi.mock('../voice', () => ({getVoiceUpdate: () => ({ type: 'VOICE_UPDATE', phase: voicePhase }),+ isNarrationLive: () => Promise.resolve(voicePhase === 'recording'),+ isNarrationSettling: () => voicePhase === 'transcribing',+ reportNarrationLost: vi.fn(),stopVoiceNarration: record('stopNarration'),+ whenNarrationSettled: () => Promise.resolve(),}));vi.mock('@/lib/browser-api', () => ({ getActiveTab: () => Promise.resolve(activeTab) }));@@ -139,18 +143,20 @@ describe('resumeCapture', () => {it('restarts narration only when the pause stopped it', async () => {voicePhase = 'recording';await pauseCapture('manual');- const onResume = vi.fn();+ const onResume = vi.fn().mockResolvedValue(true);await resumeCapture(onResume);+ await new Promise((resolve) => setTimeout(resolve, 0));expect(onResume).toHaveBeenCalledOnce();});it('does not restart narration the user never had on', async () => {await pauseCapture('manual');- const onResume = vi.fn();+ const onResume = vi.fn().mockResolvedValue(true);await resumeCapture(onResume);+ await new Promise((resolve) => setTimeout(resolve, 0));expect(onResume).not.toHaveBeenCalled();});@@ -158,14 +164,16 @@ describe('resumeCapture', () => {it('does not restart narration twice across two pause cycles', async () => {voicePhase = 'recording';await pauseCapture('manual');- const first = vi.fn();+ const first = vi.fn().mockResolvedValue(true);await resumeCapture(first);+ await new Promise((resolve) => setTimeout(resolve, 0));expect(first).toHaveBeenCalledOnce();voicePhase = 'idle';await pauseCapture('manual');- const second = vi.fn();+ const second = vi.fn().mockResolvedValue(true);await resumeCapture(second);+ await new Promise((resolve) => setTimeout(resolve, 0));expect(second).not.toHaveBeenCalled();});diff --git a/src/entrypoints/background/index.ts b/src/entrypoints/background/index.tsindex aacc95d..f9444de 100644--- a/src/entrypoints/background/index.ts+++ b/src/entrypoints/background/index.ts@@ -119,7 +119,7 @@ export default defineBackground(() => {getActor().subscribe(() => broadcastStateToPanel(getStateUpdate()));});- const resume = () => resumeFromPause(() => void startNarrationIfPossible());+ const resume = () => resumeFromPause(startNarrationIfPossible);onMessage('getState', async () => {await waitUntilReady();diff --git a/src/entrypoints/background/pause.ts b/src/entrypoints/background/pause.tsindex 0188103..0ceed7f 100644--- a/src/entrypoints/background/pause.ts+++ b/src/entrypoints/background/pause.ts@@ -1,5 +1,6 @@import { CaptureState, type PauseReason } from '@/core/capture/machine';import { getActiveTab } from '@/lib/browser-api';+import { logger } from '@/lib/logger';import { getActor } from './actor';import {broadcastDismissBlur,@@ -8,25 +9,36 @@ import {injectContentScript,isInjectableTab,} from './tab-manager';-import { getVoiceUpdate, stopVoiceNarration } from './voice';+import {+ isNarrationLive,+ isNarrationSettling,+ reportNarrationLost,+ stopVoiceNarration,+ whenNarrationSettled,+} from './voice';++const NARRATION_RESTART_ATTEMPTS = 6;-let narrationWasLive = false;+export type NarrationStarter = () => Promise<boolean> | boolean;export async function pauseCapture(reason: PauseReason): Promise<boolean> {const actor = getActor();if (actor.getSnapshot().value !== CaptureState.RECORDING) return false;- actor.send({ type: 'PAUSE_CAPTURE', reason });++ const narrationWasLive = (await isNarrationLive()) || isNarrationSettling();+ actor.send({ type: 'PAUSE_CAPTURE', reason, narrationWasLive });const guideId = actor.getSnapshot().context.currentGuideId;- narrationWasLive = getVoiceUpdate().phase === 'recording';await broadcastStopCaptureAndFlush();if (narrationWasLive && guideId) await stopVoiceNarration(guideId);return true;}-export async function resumeCapture(onNarrationResume?: () => void): Promise<boolean> {+export async function resumeCapture(tryStartNarration?: NarrationStarter): Promise<boolean> {const actor = getActor();if (actor.getSnapshot().value !== CaptureState.PAUSED) return false;++ const narrationWasLive = actor.getSnapshot().context.narrationWasLive === true;actor.send({ type: 'RESUME_CAPTURE' });const guideId = actor.getSnapshot().context.currentGuideId;@@ -36,14 +48,28 @@ export async function resumeCapture(onNarrationResume?: () => void): Promise<booawait broadcastStartCapture(guideId);}- if (narrationWasLive) {- narrationWasLive = false;- onNarrationResume?.();+ if (narrationWasLive && tryStartNarration) {+ void restartNarrationOnceTranscriptionSettles(tryStartNarration).catch((error: unknown) =>+ logger.error('voice: narration could not be restarted after the pause', error),+ );}return true;}-export async function resumeFromPause(onNarrationResume?: () => void): Promise<boolean> {+export async function restartNarrationOnceTranscriptionSettles(tryStartNarration: NarrationStarter): Promise<boolean> {+ for (let attempt = 0; attempt < NARRATION_RESTART_ATTEMPTS; attempt++) {+ if (await tryStartNarration()) return true;+ if (!isNarrationSettling()) {+ reportNarrationLost();+ return false;+ }+ await whenNarrationSettled();+ }+ reportNarrationLost();+ return false;+}++export async function resumeFromPause(tryStartNarration?: NarrationStarter): Promise<boolean> {await broadcastDismissBlur();- return resumeCapture(onNarrationResume);+ return resumeCapture(tryStartNarration);}