π¬ 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(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.tsindex 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.tsindex 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<stringreturn 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.tsxindex 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.tsxindex 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 () => {