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(guides): close the three transcript gaps found in review

davbiod887d6c61840
diff --git a/src/core/guides/__tests__/spoken-original.test.ts b/src/core/guides/__tests__/spoken-original.test.ts
index ec17c1e..8475a12 100644
--- a/src/core/guides/__tests__/spoken-original.test.ts
+++ b/src/core/guides/__tests__/spoken-original.test.ts
@@ -18,9 +18,8 @@ vi.hoisted(() => {
import { db } from '../db';
import {
- appendToStepDescription,
+ addTranscriptLineToStep,
applyNarrationToSteps,
- attachTranscriptLine,
createSnapshot,
deleteTranscripts,
getTranscripts,
@@ -32,7 +31,23 @@ import {
saveTranscript,
updateStepDescription,
} from '../service';
-import type { Step } from '../types';
+import type { ElementMeta, Step } from '../types';
+
+const BUTTON_META: ElementMeta = {
+ tag: 'button',
+ cssSelector: 'button.billing',
+ textContent: 'Billing',
+ ariaLabel: null,
+ placeholder: null,
+ altText: null,
+ name: null,
+ role: null,
+ href: null,
+ inputType: null,
+ dataTestId: null,
+ rect: { x: 0, y: 0, width: 80, height: 24 },
+ devicePixelRatio: 1,
+};
const SPOKEN = 'Open the billing tab on the left';
@@ -68,6 +83,7 @@ afterEach(async () => {
await db.transcripts.clear();
await db.screenshots.clear();
await db.snapshots.clear();
+ await db.guideMerges.clear();
});
describe('the spoken original', () => {
@@ -106,22 +122,49 @@ describe('the spoken original', () => {
});
});
-describe('appendToStepDescription', () => {
- it('adds a recovered line to what the step already says', async () => {
- expect(await appendToStepDescription('s1', 'then confirm the change')).toBe(
+describe('adding a transcript line to a step', () => {
+ const unused = {
+ epochMs: 1_700_000_000_000,
+ lines: [{ start: 4, end: 6, text: 'then confirm the change', stepId: null, rejectReason: null }],
+ };
+
+ async function seedRow(): Promise<string> {
+ await saveTranscript('g1', unused);
+ return (await getTranscripts('g1'))[0].id;
+ }
+
+ it('adds the line to what the step already says', async () => {
+ const rowId = await seedRow();
+ expect(await addTranscriptLineToStep(rowId, 0, 's1', 'then confirm the change')).toBe(
'Clicked Billing then confirm the change',
);
expect((await db.steps.get('s1'))?.descriptionSource).toBe('manual');
});
it('becomes the whole description when the step had none', async () => {
+ const rowId = await seedRow();
await db.steps.update('s1', { description: '' });
- expect(await appendToStepDescription('s1', 'open the billing tab')).toBe('open the billing tab');
+ expect(await addTranscriptLineToStep(rowId, 0, 's1', 'open the billing tab')).toBe('open the billing tab');
});
it('refuses blank text and a step that is gone', async () => {
- expect(await appendToStepDescription('s1', ' ')).toBeNull();
- expect(await appendToStepDescription('missing', 'anything')).toBeNull();
+ const rowId = await seedRow();
+ expect(await addTranscriptLineToStep(rowId, 0, 's1', ' ')).toBeNull();
+ expect(await addTranscriptLineToStep(rowId, 0, 'missing', 'anything')).toBeNull();
+ });
+
+ it('refuses a second click on a line that is already used', async () => {
+ const rowId = await seedRow();
+ await addTranscriptLineToStep(rowId, 0, 's1', 'then confirm the change');
+
+ expect(await addTranscriptLineToStep(rowId, 0, 's1', 'then confirm the change')).toBeNull();
+ expect((await db.steps.get('s1'))?.description).toBe('Clicked Billing then confirm the change');
+ });
+
+ it('refuses a line index that is not in the row', async () => {
+ const rowId = await seedRow();
+ expect(await addTranscriptLineToStep(rowId, 7, 's1', 'anything')).toBeNull();
+ expect((await db.steps.get('s1'))?.description).toBe('Clicked Billing');
});
});
@@ -283,8 +326,7 @@ describe('a line pushed onto a step by hand', () => {
await saveTranscript('g1', transcript);
const row = (await getTranscripts('g1'))[0];
- await appendToStepDescription('s1', 'and then confirm it');
- await attachTranscriptLine(row.id, 1, 's1');
+ await addTranscriptLineToStep(row.id, 1, 's1', 'and then confirm it');
expect((await getTranscripts('g1'))[0].lines[1]).toMatchObject({ stepId: 's1', addedByHand: true });
await restoreNarratedDescription('s1');
@@ -335,3 +377,171 @@ describe('restoring an older version', () => {
expect((await db.steps.get('s1'))?.narratedDescription).toBe(SPOKEN);
});
});
+
+describe('deleting a transcript and the description narration wrote', () => {
+ const transcript = {
+ epochMs: 1_700_000_000_000,
+ lines: [{ start: 1, end: 3, text: SPOKEN, stepId: 's1', rejectReason: null }],
+ };
+
+ it('does not leave the spoken words sitting in the description', async () => {
+ await db.steps.update('s1', { elementMeta: BUTTON_META });
+ await applyNarrationToSteps([{ stepId: 's1', description: SPOKEN }]);
+ await saveTranscript('g1', transcript);
+
+ await deleteTranscripts('g1');
+
+ const step = await db.steps.get('s1');
+ expect(step?.description).toBe('steps.click[Billing]');
+ expect(step?.descriptionSource).toBe('heuristic');
+ });
+
+ it('falls back to the navigate wording for a step with no element', async () => {
+ await db.steps.update('s1', { action: 'navigate', elementMeta: undefined });
+ await applyNarrationToSteps([{ stepId: 's1', description: SPOKEN }]);
+ await saveTranscript('g1', transcript);
+
+ await deleteTranscripts('g1');
+
+ expect((await db.steps.get('s1'))?.description).toBe('steps.navigate');
+ });
+
+ it('strips a line the user added to a step by hand', async () => {
+ const secret = 'my password is hunter2';
+ await saveTranscript('g1', {
+ epochMs: 1_700_000_000_000,
+ lines: [{ start: 4, end: 6, text: secret, stepId: null, rejectReason: null }],
+ });
+ const row = (await getTranscripts('g1'))[0];
+ await addTranscriptLineToStep(row.id, 0, 's1', secret);
+ expect((await db.steps.get('s1'))?.description).toContain('hunter2');
+
+ await deleteTranscripts('g1');
+
+ const step = await db.steps.get('s1');
+ expect(step?.description).not.toContain('hunter2');
+ expect(step?.description).toBe('Clicked Billing');
+ });
+
+ it('leaves a description the user wrote alone', async () => {
+ await applyNarrationToSteps([{ stepId: 's1', description: SPOKEN }]);
+ await saveTranscript('g1', transcript);
+ await updateStepDescription('s1', 'Click the Billing tab', 'manual');
+
+ await deleteTranscripts('g1');
+
+ const step = await db.steps.get('s1');
+ expect(step?.description).toBe('Click the Billing tab');
+ expect(step?.descriptionSource).toBe('manual');
+ });
+
+ it('takes the spoken words out of the snapshots as well', async () => {
+ await db.steps.update('s1', { elementMeta: BUTTON_META });
+ await applyNarrationToSteps([{ stepId: 's1', description: SPOKEN }]);
+ await createSnapshot('g1');
+ await saveTranscript('g1', transcript);
+
+ await deleteTranscripts('g1');
+
+ const snapshots = await db.snapshots.where('guideId').equals('g1').toArray();
+ expect(snapshots.flatMap((s) => s.steps).some((s) => s.description === SPOKEN)).toBe(false);
+ });
+});
+
+describe('a transcript that lands after its guide was merged away', () => {
+ const unattributed = {
+ epochMs: 1_700_000_000_000,
+ lines: [{ start: 1, end: 3, text: 'a stray thought', stepId: null, rejectReason: null }],
+ };
+
+ async function addTarget(id: string): Promise<void> {
+ await db.guides.add({
+ id,
+ title: id,
+ createdAt: Date.now(),
+ updatedAt: Date.now(),
+ stepIds: [],
+ starred: false,
+ deletedAt: null,
+ });
+ }
+
+ it('is filed against the target even when no line resolves through a step', async () => {
+ await addTarget('target');
+ await mergeGuideInto('g1', 'target', 0);
+ await db.steps.clear();
+
+ await saveTranscript('g1', unattributed);
+
+ expect(await hasTranscript('target')).toBe(true);
+ });
+
+ it('records the redirect in the database, not in memory', async () => {
+ await addTarget('target');
+ await mergeGuideInto('g1', 'target', 0);
+
+ expect(await db.guideMerges.get('g1')).toMatchObject({ targetGuideId: 'target' });
+ });
+
+ it('drops the redirect when the target guide is permanently deleted', async () => {
+ await addTarget('target');
+ await mergeGuideInto('g1', 'target', 0);
+
+ await permanentlyDeleteGuide('target');
+
+ expect(await db.guideMerges.get('g1')).toBeUndefined();
+ });
+
+ it('follows a guide that was merged away more than once', async () => {
+ await addTarget('target');
+ await addTarget('final');
+ await mergeGuideInto('g1', 'target', 0);
+ await mergeGuideInto('target', 'final', 0);
+ await db.steps.clear();
+
+ await saveTranscript('g1', unattributed);
+
+ expect(await hasTranscript('final')).toBe(true);
+ });
+
+ it('is dropped when the target is gone too', async () => {
+ await addTarget('target');
+ await mergeGuideInto('g1', 'target', 0);
+ await db.steps.clear();
+ await db.guides.delete('target');
+
+ await saveTranscript('g1', unattributed);
+
+ expect(await db.transcripts.count()).toBe(0);
+ });
+});
+
+describe('pushing a line onto a step', () => {
+ const transcript = {
+ epochMs: 1_700_000_000_000,
+ lines: [
+ { start: 1, end: 3, text: SPOKEN, stepId: 's1', rejectReason: null },
+ { start: 4, end: 6, text: 'and then confirm it', stepId: null, rejectReason: null },
+ ],
+ };
+
+ it('writes the description and marks the line in one go', async () => {
+ await saveTranscript('g1', transcript);
+ const row = (await getTranscripts('g1'))[0];
+
+ const written = await addTranscriptLineToStep(row.id, 1, 's1', 'and then confirm it');
+
+ expect(written).toBe('Clicked Billing and then confirm it');
+ expect((await getTranscripts('g1'))[0].lines[1]).toMatchObject({ stepId: 's1', addedByHand: true });
+ });
+
+ it('cannot append the words while leaving the line reading unused', async () => {
+ await saveTranscript('g1', transcript);
+ const row = (await getTranscripts('g1'))[0];
+
+ expect(await addTranscriptLineToStep(row.id, 1, 'missing', 'and then confirm it')).toBeNull();
+
+ expect((await db.steps.get('s1'))?.description).toBe('Clicked Billing');
+ expect((await getTranscripts('g1'))[0].lines[1].stepId).toBeNull();
+ });
+});
diff --git a/src/core/guides/service.ts b/src/core/guides/service.ts
index 56da9f2..d9364d2 100644
--- a/src/core/guides/service.ts
+++ b/src/core/guides/service.ts
@@ -1,4 +1,5 @@
import { i18n } from '#imports';
+import { buildFallbackDescription } from '@/core/capture/step-description';
import type { NarrationUpdate } from '@/core/capture/voice/narration-updates';
import type { NarrationTranscript } from '@/core/capture/voice/types';
import type { ScreenshotEdits } from '@/core/screenshot/types';
@@ -136,6 +137,8 @@ export async function permanentlyDeleteGuide(id: string): Promise<void> {
await db.snapshots.where('guideId').equals(id).delete();
await db.transcripts.where('guideId').equals(id).delete();
await db.steps.where('guideId').equals(id).delete();
+ await db.guideMerges.delete(id);
+ await db.guideMerges.where('targetGuideId').equals(id).delete();
await db.guides.delete(id);
notifyGuidesChanged({ type: 'mutated' });
}
@@ -209,7 +212,7 @@ export async function createStep(step: Step): Promise<void> {
}
export async function mergeGuideInto(sourceGuideId: string, targetGuideId: string, atIndex: number): Promise<number> {
- const moved = await db.transaction('rw', db.steps, db.guides, db.transcripts, async () => {
+ const moved = await db.transaction('rw', db.steps, db.guides, db.transcripts, db.guideMerges, async () => {
const incoming = await db.steps.where('guideId').equals(sourceGuideId).sortBy('index');
const target = await db.steps.where('guideId').equals(targetGuideId).sortBy('index');
if (incoming.length > 0) {
@@ -225,7 +228,7 @@ export async function mergeGuideInto(sourceGuideId: string, targetGuideId: strin
});
}
await db.transcripts.where('guideId').equals(sourceGuideId).modify({ guideId: targetGuideId });
- mergedInto.set(sourceGuideId, targetGuideId);
+ await db.guideMerges.put({ id: sourceGuideId, targetGuideId, mergedAt: Date.now() });
await db.guides.delete(sourceGuideId);
return incoming.length;
});
@@ -287,13 +290,23 @@ export async function applyNarrationToSteps(updates: readonly NarrationUpdate[])
notifyGuidesChanged({ type: 'mutated' });
}
-const mergedInto = new Map<string, string>();
+const MERGE_CHAIN_LIMIT = 10;
+
+async function followMergeChain(guideId: string): Promise<string | null> {
+ let current = guideId;
+ for (let hop = 0; hop < MERGE_CHAIN_LIMIT; hop++) {
+ const merge = await db.guideMerges.get(current);
+ if (!merge) return current === guideId ? null : current;
+ current = merge.targetGuideId;
+ }
+ return current;
+}
async function resolveTranscriptOwner(guideId: string, transcript: NarrationTranscript): Promise<string | null> {
if (await db.guides.get(guideId)) return guideId;
const spokenFor = transcript.lines.map((line) => line.stepId).filter((id): id is string => id !== null);
const steps = await db.steps.bulkGet(spokenFor);
- const owner = steps.find((step) => step !== undefined)?.guideId ?? mergedInto.get(guideId);
+ const owner = steps.find((step) => step !== undefined)?.guideId ?? (await followMergeChain(guideId));
return owner && (await db.guides.get(owner)) ? owner : null;
}
@@ -319,20 +332,68 @@ export async function hasTranscript(guideId: string): Promise<boolean> {
return (await db.transcripts.where('guideId').equals(guideId).count()) > 0;
}
+function rebuiltHeuristicDescription(step: Step): string {
+ if (step.elementMeta) return buildFallbackDescription(step.action, step.elementMeta);
+ return step.action === 'navigate' ? i18n.t('steps.navigate') : '';
+}
+
+function withoutAppendedSentences(description: string, additions: readonly string[]): string {
+ let kept = description.trim();
+ let stripped = true;
+ while (stripped) {
+ stripped = false;
+ for (const addition of additions) {
+ const sentence = addition.trim();
+ if (!sentence) continue;
+ if (kept === sentence) return '';
+ if (!kept.endsWith(` ${sentence}`)) continue;
+ kept = kept.slice(0, -(sentence.length + 1)).trim();
+ stripped = true;
+ }
+ }
+ return kept;
+}
+
+function forgetSpokenWords(step: Step, handAdded: ReadonlyMap<string, string[]>): void {
+ delete step.narratedDescription;
+ if (step.descriptionSource === 'narration') {
+ step.description = rebuiltHeuristicDescription(step);
+ step.descriptionSource = 'heuristic';
+ return;
+ }
+ const additions = handAdded.get(step.id);
+ if (!additions) return;
+ const kept = withoutAppendedSentences(step.description, additions);
+ step.description = kept || rebuiltHeuristicDescription(step);
+}
+
+function handAddedSentences(rows: readonly GuideTranscript[]): Map<string, string[]> {
+ const byStep = new Map<string, string[]>();
+ for (const row of rows) {
+ for (const line of row.lines) {
+ if (!line.stepId || !line.addedByHand) continue;
+ const existing = byStep.get(line.stepId);
+ if (existing) existing.push(line.text);
+ else byStep.set(line.stepId, [line.text]);
+ }
+ }
+ return byStep;
+}
+
export async function deleteTranscripts(guideId: string): Promise<void> {
await db.transaction('rw', db.transcripts, db.steps, db.snapshots, async () => {
+ const rows = await db.transcripts.where('guideId').equals(guideId).toArray();
+ const handAdded = handAddedSentences(rows);
await db.transcripts.where('guideId').equals(guideId).delete();
await db.steps
.where('guideId')
.equals(guideId)
- .modify((step) => {
- delete step.narratedDescription;
- });
+ .modify((step) => forgetSpokenWords(step, handAdded));
await db.snapshots
.where('guideId')
.equals(guideId)
.modify((snapshot) => {
- for (const step of snapshot.steps) delete step.narratedDescription;
+ for (const step of snapshot.steps) forgetSpokenWords(step, handAdded);
snapshot.contentHash = hashPayload({
title: snapshot.title,
stepIds: snapshot.stepIds,
@@ -367,7 +428,7 @@ export async function restoreNarratedDescription(stepId: string): Promise<string
return spoken;
}
-export async function attachTranscriptLine(rowId: string, lineIndex: number, stepId: string): Promise<void> {
+async function markLineAttached(rowId: string, lineIndex: number, stepId: string): Promise<void> {
await db.transcripts
.where('id')
.equals(rowId)
@@ -379,14 +440,36 @@ export async function attachTranscriptLine(rowId: string, lineIndex: number, ste
});
}
-export async function appendToStepDescription(stepId: string, text: string): Promise<string | null> {
- const addition = text.trim();
- if (!addition) return null;
+async function writeAppendedDescription(stepId: string, addition: string): Promise<string | null> {
const step = await db.steps.get(stepId);
if (!step) return null;
const description = step.description.trim() ? `${step.description.trim()} ${addition}` : addition;
await db.steps.update(stepId, { description, descriptionSource: 'manual', aiPending: false });
- notifyGuidesChanged({ type: 'mutated' });
+ return description;
+}
+
+async function isLineStillUnused(rowId: string, lineIndex: number): Promise<boolean> {
+ const row = await db.transcripts.get(rowId);
+ const line = row?.lines[lineIndex];
+ return line !== undefined && !line.stepId;
+}
+
+export async function addTranscriptLineToStep(
+ rowId: string,
+ lineIndex: number,
+ stepId: string,
+ text: string,
+): Promise<string | null> {
+ const addition = text.trim();
+ if (!addition) return null;
+ const description = await db.transaction('rw', db.steps, db.transcripts, async () => {
+ if (!(await isLineStillUnused(rowId, lineIndex))) return null;
+ const written = await writeAppendedDescription(stepId, addition);
+ if (written === null) return null;
+ await markLineAttached(rowId, lineIndex, stepId);
+ return written;
+ });
+ if (description !== null) notifyGuidesChanged({ type: 'mutated' });
return description;
}
diff --git a/src/ui/fullview/components/TranscriptPanel.tsx b/src/ui/fullview/components/TranscriptPanel.tsx
index 51160e4..554f53d 100644
--- a/src/ui/fullview/components/TranscriptPanel.tsx
+++ b/src/ui/fullview/components/TranscriptPanel.tsx
@@ -3,12 +3,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { i18n } from '#imports';
import { downloadText, safeFilename } from '@/core/export/download';
import { stepNumbers } from '@/core/guides/blocks';
-import {
- appendToStepDescription,
- attachTranscriptLine,
- deleteTranscripts,
- getTranscripts,
-} from '@/core/guides/service';
+import { addTranscriptLineToStep, deleteTranscripts, getTranscripts } from '@/core/guides/service';
import {
countUnused,
formatOffset,
@@ -115,8 +110,7 @@ export default function TranscriptPanel({
const handleAddToStep = async (line: TimelineLine, index: number) => {
const targetId = targetFor(line, index);
if (!targetId) return;
- if (!(await appendToStepDescription(targetId, line.text))) return;
- await attachTranscriptLine(line.rowId, line.lineIndex, targetId);
+ if (!(await addTranscriptLineToStep(line.rowId, line.lineIndex, targetId, line.text))) return;
await load();
onChanged?.();
};
diff --git a/src/ui/fullview/components/__tests__/transcript-panel.test.tsx b/src/ui/fullview/components/__tests__/transcript-panel.test.tsx
index 33e6a7e..1deaabd 100644
--- a/src/ui/fullview/components/__tests__/transcript-panel.test.tsx
+++ b/src/ui/fullview/components/__tests__/transcript-panel.test.tsx
@@ -5,14 +5,12 @@ import type { GuideTranscript, Step } from '@/core/guides/types';
import { TooltipProvider } from '@/ui/components/ui/tooltip';
const getTranscripts = vi.fn();
-const appendToStepDescription = vi.fn();
-const attachTranscriptLine = vi.fn();
+const addTranscriptLineToStep = vi.fn();
const deleteTranscripts = vi.fn();
vi.mock('@/core/guides/service', () => ({
getTranscripts: (...args: unknown[]) => getTranscripts(...args),
- appendToStepDescription: (...args: unknown[]) => appendToStepDescription(...args),
- attachTranscriptLine: (...args: unknown[]) => attachTranscriptLine(...args),
+ addTranscriptLineToStep: (...args: unknown[]) => addTranscriptLineToStep(...args),
deleteTranscripts: (...args: unknown[]) => deleteTranscripts(...args),
}));
@@ -66,8 +64,7 @@ function renderPanel(rows: GuideTranscript[], steps: Step[], readOnly = false) {
beforeEach(() => {
getTranscripts.mockReset();
- appendToStepDescription.mockReset();
- attachTranscriptLine.mockReset().mockResolvedValue(undefined);
+ addTranscriptLineToStep.mockReset();
deleteTranscripts.mockReset();
});
@@ -90,7 +87,7 @@ describe('TranscriptPanel', () => {
});
it('appends an unused line to the step that follows it', async () => {
- appendToStepDescription.mockResolvedValue('Clicked something and then some');
+ addTranscriptLineToStep.mockResolvedValue('Clicked something and then some');
renderPanel(
[
transcript([
@@ -104,11 +101,13 @@ describe('TranscriptPanel', () => {
fireEvent.click(await screen.findByRole('button', { name: 'transcript.addToStep[2]' }));
- await waitFor(() => expect(appendToStepDescription).toHaveBeenCalledWith('s3', 'stray thought'));
+ await waitFor(() =>
+ expect(addTranscriptLineToStep).toHaveBeenCalledWith(expect.any(String), 1, 's3', 'stray thought'),
+ );
});
it('records the attribution, so reopening cannot append the same line twice', async () => {
- appendToStepDescription.mockResolvedValue('Clicked something and then some');
+ addTranscriptLineToStep.mockResolvedValue('Clicked something and then some');
const seeded = transcript([
[1, 'click save', 's1', null],
[3, 'stray thought', null, null],
@@ -134,9 +133,9 @@ describe('TranscriptPanel', () => {
fireEvent.click(await screen.findByRole('button', { name: 'transcript.addToStep[2]' }));
- await waitFor(() => expect(attachTranscriptLine).toHaveBeenCalledWith(seeded.id, 1, 's3'));
+ await waitFor(() => expect(addTranscriptLineToStep).toHaveBeenCalledWith(seeded.id, 1, 's3', 'stray thought'));
await waitFor(() => expect(screen.queryByRole('button', { name: /transcript.addToStep/ })).toBeNull());
- expect(appendToStepDescription).toHaveBeenCalledTimes(1);
+ expect(addTranscriptLineToStep).toHaveBeenCalledTimes(1);
});
it('keeps a filtered line visible with its own tag', async () => {