Skip to content

armgit / mimik

Public Imported from GitHub
0

🎬 A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots πŸ“–

fix(recording): bring the microphone back after a pause

davbio6dccb89a5086
diff --git a/src/core/capture/machine.ts b/src/core/capture/machine.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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<boo
await 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);
}