π¬ 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
feat(messaging): add on-demand guide description generation
Luis Ortiz5b4639bfddb4
diff --git a/src/entrypoints/background/__tests__/guide-meta.test.ts b/src/entrypoints/background/__tests__/guide-meta.test.tsnew file mode 100644index 0000000..fa3d8f7--- /dev/null+++ b/src/entrypoints/background/__tests__/guide-meta.test.ts@@ -0,0 +1,230 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++const {+ generateGuideMetaMock,+ getGuideDomainMock,+ getStepsForGuideMock,+ localStorageGetMock,+ updateGuideDescriptionMock,+ updateGuideTitleMock,+} = vi.hoisted(() => ({+ generateGuideMetaMock: vi.fn(),+ getGuideDomainMock: vi.fn(),+ getStepsForGuideMock: vi.fn(),+ localStorageGetMock: vi.fn(),+ updateGuideDescriptionMock: vi.fn(),+ updateGuideTitleMock: vi.fn(),+}));++vi.mock('@/core/capture/ai/meta', () => ({ generateGuideMeta: generateGuideMetaMock }));++vi.mock('@/core/guides/service', () => ({+ getGuideDomain: getGuideDomainMock,+ getStepsForGuide: getStepsForGuideMock,+ updateGuideDescription: updateGuideDescriptionMock,+ updateGuideTitle: updateGuideTitleMock,+}));++vi.mock('@/lib/browser-api', () => ({ localStorage: { get: localStorageGetMock } }));++import { AI_PROVIDERS } from '@/core/capture/ai/models';+import { generateDescriptionOnDemand, generateGuideMetaOnStop } from '../guide-meta';++const GUIDE_ID = 'guide-1';++const entryPoints = [+ ['generateGuideMetaOnStop', generateGuideMetaOnStop],+ ['generateDescriptionOnDemand', generateDescriptionOnDemand],+] as const;++function makeSteps(count: number) {+ return Array.from({ length: count }, (_, i) => ({+ description: `step ${i}`,+ url: `https://example.com/${i}`,+ }));+}++describe('background guide-meta', () => {+ beforeEach(() => {+ vi.clearAllMocks();+ localStorageGetMock.mockResolvedValue({ aiApiKey: 'key', aiProvider: 'openai', aiModel: 'gpt-4o' });+ getStepsForGuideMock.mockResolvedValue(makeSteps(3));+ getGuideDomainMock.mockResolvedValue('example.com');+ updateGuideTitleMock.mockResolvedValue(undefined);+ updateGuideDescriptionMock.mockResolvedValue(undefined);+ generateGuideMetaMock.mockResolvedValue({ title: 'Generated Title', description: 'Generated description.' });+ });++ describe('input resolution shared by both entry points', () => {+ it.each(entryPoints)('%s sends the first ten and last five of more than fifteen steps', async (_name, run) => {+ getStepsForGuideMock.mockResolvedValue(makeSteps(20));++ await run(GUIDE_ID);++ const sent = generateGuideMetaMock.mock.calls[0][0];+ expect(sent).toHaveLength(15);+ expect(sent[0].description).toBe('step 0');+ expect(sent[9].description).toBe('step 9');+ expect(sent[10].description).toBe('step 15');+ expect(sent[14].description).toBe('step 19');+ });++ it.each(entryPoints)('%s sends every step when there are exactly fifteen', async (_name, run) => {+ getStepsForGuideMock.mockResolvedValue(makeSteps(15));++ await run(GUIDE_ID);++ expect(generateGuideMetaMock.mock.calls[0][0]).toHaveLength(15);+ });++ it.each(entryPoints)('%s drops steps that have no description', async (_name, run) => {+ getStepsForGuideMock.mockResolvedValue([+ { description: 'kept', url: 'https://example.com/a' },+ { description: '', url: 'https://example.com/b' },+ ]);++ await run(GUIDE_ID);++ expect(generateGuideMetaMock.mock.calls[0][0]).toEqual([{ description: 'kept', url: 'https://example.com/a' }]);+ });++ it.each(entryPoints)("%s defaults the model to the provider's own default", async (_name, run) => {+ localStorageGetMock.mockResolvedValue({ aiApiKey: 'key', aiProvider: 'anthropic' });++ await run(GUIDE_ID);++ expect(generateGuideMetaMock).toHaveBeenCalledWith(+ expect.anything(),+ 'anthropic',+ AI_PROVIDERS.anthropic.defaultModel,+ 'key',+ );+ });++ it.each(entryPoints)('%s defaults the provider to OpenAI when none is stored', async (_name, run) => {+ localStorageGetMock.mockResolvedValue({ aiApiKey: 'key' });++ await run(GUIDE_ID);++ expect(generateGuideMetaMock).toHaveBeenCalledWith(+ expect.anything(),+ 'openai',+ AI_PROVIDERS.openai.defaultModel,+ 'key',+ );+ });+ });++ describe('generateGuideMetaOnStop', () => {+ it('applies the domain fallback title without calling the model when no key is set', async () => {+ localStorageGetMock.mockResolvedValue({});++ await generateGuideMetaOnStop(GUIDE_ID);++ expect(generateGuideMetaMock).not.toHaveBeenCalled();+ expect(updateGuideTitleMock).toHaveBeenCalledWith(GUIDE_ID, 'background.guideOnDomain[example.com]');+ });++ it('falls back to the generic title when the guide has no domain', async () => {+ localStorageGetMock.mockResolvedValue({});+ getGuideDomainMock.mockResolvedValue('');++ await generateGuideMetaOnStop(GUIDE_ID);++ expect(updateGuideTitleMock).toHaveBeenCalledWith(GUIDE_ID, 'background.newGuide');+ });++ it('writes no title at all when no step has a description', async () => {+ getStepsForGuideMock.mockResolvedValue([{ description: '', url: 'https://example.com' }]);++ await generateGuideMetaOnStop(GUIDE_ID);++ expect(generateGuideMetaMock).not.toHaveBeenCalled();+ expect(updateGuideTitleMock).not.toHaveBeenCalled();+ expect(updateGuideDescriptionMock).not.toHaveBeenCalled();+ });++ it('applies the fallback title when the model yields nothing', async () => {+ generateGuideMetaMock.mockResolvedValue(null);++ await generateGuideMetaOnStop(GUIDE_ID);++ expect(updateGuideTitleMock).toHaveBeenCalledWith(GUIDE_ID, 'background.guideOnDomain[example.com]');+ });++ it('stores both the title and the description on success', async () => {+ await generateGuideMetaOnStop(GUIDE_ID);++ expect(updateGuideTitleMock).toHaveBeenCalledWith(GUIDE_ID, 'Generated Title');+ expect(updateGuideDescriptionMock).toHaveBeenCalledWith(GUIDE_ID, 'Generated description.');+ });++ it('keeps the generated title when the description write fails', async () => {+ updateGuideDescriptionMock.mockRejectedValue(new Error('QuotaExceededError'));++ await generateGuideMetaOnStop(GUIDE_ID);++ expect(updateGuideTitleMock).toHaveBeenCalledTimes(1);+ expect(updateGuideTitleMock).toHaveBeenCalledWith(GUIDE_ID, 'Generated Title');+ });++ it('applies the fallback title when the title write itself fails', async () => {+ updateGuideTitleMock.mockRejectedValueOnce(new Error('DatabaseClosedError'));++ await generateGuideMetaOnStop(GUIDE_ID);++ expect(updateGuideTitleMock).toHaveBeenNthCalledWith(2, GUIDE_ID, 'background.guideOnDomain[example.com]');+ });+ });++ describe('generateDescriptionOnDemand', () => {+ it('reports a missing key without touching the guide', async () => {+ localStorageGetMock.mockResolvedValue({});++ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'no-api-key' });+ expect(updateGuideTitleMock).not.toHaveBeenCalled();+ expect(updateGuideDescriptionMock).not.toHaveBeenCalled();+ });++ it('reports a guide with no described steps', async () => {+ getStepsForGuideMock.mockResolvedValue([]);++ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'no-steps' });+ expect(generateGuideMetaMock).not.toHaveBeenCalled();+ });++ it('reports a failed generation', async () => {+ generateGuideMetaMock.mockResolvedValue(null);++ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'generation-failed' });+ expect(updateGuideDescriptionMock).not.toHaveBeenCalled();+ });++ it('reports a failed generation when the model returns a title but no description', async () => {+ generateGuideMetaMock.mockResolvedValue({ title: 'Generated Title' });++ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'generation-failed' });+ expect(updateGuideDescriptionMock).not.toHaveBeenCalled();+ });++ it('resolves to save-failed rather than rejecting when the write throws', async () => {+ updateGuideDescriptionMock.mockRejectedValue(new Error('QuotaExceededError'));++ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'save-failed' });+ });++ it('resolves to save-failed rather than rejecting when reading the inputs throws', async () => {+ localStorageGetMock.mockRejectedValue(new Error('DatabaseClosedError'));++ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'save-failed' });+ });++ it('stores and returns the description, leaving the title untouched', async () => {+ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({+ description: 'Generated description.',+ });+ expect(updateGuideDescriptionMock).toHaveBeenCalledWith(GUIDE_ID, 'Generated description.');+ expect(updateGuideTitleMock).not.toHaveBeenCalled();+ });+ });+});diff --git a/src/entrypoints/background/guide-meta.ts b/src/entrypoints/background/guide-meta.tsnew file mode 100644index 0000000..0b28902--- /dev/null+++ b/src/entrypoints/background/guide-meta.ts@@ -0,0 +1,82 @@+import { i18n } from '#imports';+import { generateGuideMeta } from '@/core/capture/ai/meta';+import { AI_PROVIDERS } from '@/core/capture/ai/models';+import { getGuideDomain, getStepsForGuide, updateGuideDescription, updateGuideTitle } from '@/core/guides/service';+import { localStorage } from '@/lib/browser-api';+import { logger } from '@/lib/logger';+import type { GenerateGuideDescriptionResponse, GuideDescriptionError } from '@/lib/messaging';++type ResolveFailure = Extract<GuideDescriptionError, 'no-api-key' | 'no-steps'>;++type GuideMetaInputs =+ | { ok: true; steps: { description: string; url: string }[]; provider: string; model: string; apiKey: string }+ | { ok: false; reason: ResolveFailure };++async function resolveGuideMetaInputs(guideId: string): Promise<GuideMetaInputs> {+ const settings = await localStorage.get(['aiApiKey', 'aiProvider', 'aiModel']);+ if (!settings.aiApiKey) return { ok: false, reason: 'no-api-key' };++ const steps = await getStepsForGuide(guideId);+ const described = steps.filter((s) => s.description).map((s) => ({ description: s.description, url: s.url }));+ if (described.length === 0) return { ok: false, reason: 'no-steps' };++ const provider = (settings.aiProvider as string) || 'openai';+ return {+ ok: true,+ steps: described.length > 15 ? [...described.slice(0, 10), ...described.slice(-5)] : described,+ provider,+ model: (settings.aiModel as string) || AI_PROVIDERS[provider].defaultModel,+ apiKey: settings.aiApiKey as string,+ };+}++async function applyFallbackTitle(guideId: string) {+ const domain = await getGuideDomain(guideId);+ await updateGuideTitle(+ guideId,+ domain ? i18n.t('background.guideOnDomain', [domain]) : i18n.t('background.newGuide'),+ );+}++export async function generateGuideMetaOnStop(guideId: string) {+ try {+ const inputs = await resolveGuideMetaInputs(guideId);+ if (!inputs.ok) {+ if (inputs.reason === 'no-api-key') await applyFallbackTitle(guideId);+ return;+ }++ const meta = await generateGuideMeta(inputs.steps, inputs.provider, inputs.model, inputs.apiKey);+ if (!meta) {+ await applyFallbackTitle(guideId);+ return;+ }++ await updateGuideTitle(guideId, meta.title);+ logger.info('Generated guide meta:', meta.title);+ if (meta.description) {+ await updateGuideDescription(guideId, meta.description).catch((err) =>+ logger.error('Guide description write failed', err),+ );+ }+ } catch (err) {+ logger.error('Guide meta generation failed', err);+ await applyFallbackTitle(guideId);+ }+}++export async function generateDescriptionOnDemand(guideId: string): Promise<GenerateGuideDescriptionResponse> {+ try {+ const inputs = await resolveGuideMetaInputs(guideId);+ if (!inputs.ok) return { error: inputs.reason };++ const meta = await generateGuideMeta(inputs.steps, inputs.provider, inputs.model, inputs.apiKey);+ if (!meta?.description) return { error: 'generation-failed' };++ await updateGuideDescription(guideId, meta.description);+ return { description: meta.description };+ } catch (err) {+ logger.error('On-demand description generation failed', err);+ return { error: 'save-failed' };+ }+}diff --git a/src/entrypoints/background/index.ts b/src/entrypoints/background/index.tsindex 7f18fe7..8849ff2 100644--- a/src/entrypoints/background/index.ts+++ b/src/entrypoints/background/index.ts@@ -1,70 +1,25 @@-import { browser, defineBackground, i18n } from '#imports';-import { generateGuideMeta } from '@/core/capture/ai/meta';+import { browser, defineBackground } from '#imports';import { stepRequiresManual } from '@/core/guideme/manual';import { advanceSession, cancelSession, completeSession, getSession, startSession } from '@/core/guideme/session';-import {- createGuide,- getGuideDomain,- getScreenshotsForSteps,- getStepsForGuide,- updateGuideDescription,- updateGuideTitle,-} from '@/core/guides/service';+import { createGuide, getScreenshotsForSteps, getStepsForGuide } from '@/core/guides/service';import type { Step } from '@/core/guides/types';import { getActiveTab, localStorage, sendMessageToTab, setSidePanelBehavior, updateTab } from '@/lib/browser-api';import { logger } from '@/lib/logger';import { onMessage } from '@/lib/messaging';import { broadcastStateToPanel, setupPortListener } from '@/lib/port';import { getActor, getStateUpdate, initActor, initActorFallback, waitUntilReady } from './actor';+import { generateDescriptionOnDemand, generateGuideMetaOnStop } from './guide-meta';import { registerNavigationListeners } from './navigation';import { handleCaptureStep, handleFinalizeInputStep, handleUpdateInputStep } from './step-pipeline';import { broadcastStartCapture, broadcastStopCapture, showNotificationOnTab } from './tab-manager';-async function applyFallbackTitle(guideId: string) {- const domain = await getGuideDomain(guideId);- await updateGuideTitle(- guideId,- domain ? i18n.t('background.guideOnDomain', [domain]) : i18n.t('background.newGuide'),- );-}--async function generateGuideMetaInBackground(guideId: string) {- try {- const settings = await localStorage.get(['aiApiKey', 'aiProvider', 'aiModel']);- if (!settings.aiApiKey) {- await applyFallbackTitle(guideId);- return;- }-- const steps = await getStepsForGuide(guideId);- const allSteps = steps.filter((s) => s.description).map((s) => ({ description: s.description, url: s.url }));- if (allSteps.length === 0) return;- const stepsWithUrl = allSteps.length > 15 ? [...allSteps.slice(0, 10), ...allSteps.slice(-5)] : allSteps;-- const provider = (settings.aiProvider as string) || 'openai';- const model = (settings.aiModel as string) || 'gpt-4o-mini';- const meta = await generateGuideMeta(stepsWithUrl, provider, model, settings.aiApiKey as string);-- if (!meta) {- await applyFallbackTitle(guideId);- return;- }-- await updateGuideTitle(guideId, meta.title);- if (meta.description) await updateGuideDescription(guideId, meta.description);- logger.info('Generated guide meta:', meta.title);- } catch (err) {- logger.error('Guide meta generation failed', err);- await applyFallbackTitle(guideId);- }-}-async function resolveManual(step: Step): Promise<boolean> {if (!step.screenshotId) return stepRequiresManual(step, null);const screenshots = await getScreenshotsForSteps([step.screenshotId]);return stepRequiresManual(step, screenshots.get(step.id));}+export default defineBackground(() => {logger.info('Background service worker started');@@ -148,7 +103,7 @@ export default defineBackground(() => {await broadcastStopCapture();actor.send({ type: 'STOP_RECORDING' });- if (guideId) generateGuideMetaInBackground(guideId);+ if (guideId) generateGuideMetaOnStop(guideId).catch(() => {});return { success: true, guideId: guideId ?? undefined };});@@ -174,6 +129,8 @@ export default defineBackground(() => {return { exited: true };});+ onMessage('generateGuideDescription', ({ data }) => generateDescriptionOnDemand(data.guideId));+onMessage('captureStep', async ({ data }) => {await waitUntilReady();return handleCaptureStep(data);diff --git a/src/lib/messaging.ts b/src/lib/messaging.tsindex b2b3924..e0ca9c1 100644--- a/src/lib/messaging.ts+++ b/src/lib/messaging.ts@@ -81,6 +81,17 @@ export interface GuideMe_GoToResponse {moved: boolean;}+export type GuideDescriptionError = 'no-api-key' | 'no-steps' | 'generation-failed' | 'save-failed';++export interface GenerateGuideDescriptionData {+ guideId: string;+}++export interface GenerateGuideDescriptionResponse {+ description?: string;+ error?: GuideDescriptionError;+}+export interface EnterBlurModeResponse {entered: boolean;}@@ -102,6 +113,7 @@ interface MimikProtocol {guideMeGoTo(data: GuideMe_GoToData): GuideMe_GoToResponse;enterBlurMode(): EnterBlurModeResponse;exitBlurMode(): ExitBlurModeResponse;+ generateGuideDescription(data: GenerateGuideDescriptionData): GenerateGuideDescriptionResponse;}export const { sendMessage, onMessage } = defineExtensionMessaging<MimikProtocol>();