π¬ 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(capture): generate step descriptions without blocking the capture queue
Luis Ortizf2bb2e5cb7a2
diff --git a/src/entrypoints/background/description-queue.ts b/src/entrypoints/background/description-queue.tsnew file mode 100644index 0000000..5719bd2--- /dev/null+++ b/src/entrypoints/background/description-queue.ts@@ -0,0 +1,40 @@+import PQueue from 'p-queue';+import { logger } from '@/lib/logger';++const DRAIN_TIMEOUT_MS = 20000;+const TASK_TIMEOUT_MS = 45000;++const queue = new PQueue({ concurrency: 1 });+const byGuide = new Map<string, Set<Promise<unknown>>>();++export function queueDescription(guideId: string, run: () => Promise<void>): void {+ const pending = queue+ .add(run, { timeout: TASK_TIMEOUT_MS, throwOnTimeout: true })+ .catch((err) => logger.error('AI description failed', err));++ const tracked = byGuide.get(guideId) ?? new Set<Promise<unknown>>();+ tracked.add(pending);+ byGuide.set(guideId, tracked);++ pending.finally(() => {+ tracked.delete(pending);+ if (tracked.size === 0) byGuide.delete(guideId);+ });+}++export async function drainDescriptions(guideId: string): Promise<void> {+ const tracked = byGuide.get(guideId);+ if (!tracked?.size) return;++ let timer: ReturnType<typeof setTimeout> | undefined;+ try {+ await Promise.race([+ Promise.allSettled([...tracked]),+ new Promise<void>((resolve) => {+ timer = setTimeout(resolve, DRAIN_TIMEOUT_MS);+ }),+ ]);+ } finally {+ if (timer) clearTimeout(timer);+ }+}diff --git a/src/entrypoints/background/guide-meta.ts b/src/entrypoints/background/guide-meta.tsindex f4b346c..3211207 100644--- a/src/entrypoints/background/guide-meta.ts+++ b/src/entrypoints/background/guide-meta.ts@@ -2,10 +2,17 @@ import { i18n } from '#imports';import { generateGuideMeta } from '@/core/capture/ai/meta';import { AI_PROVIDERS } from '@/core/capture/ai/models';import { actionSteps } from '@/core/guides/blocks';-import { getGuideDomain, getStepsForGuide, updateGuideDescription, updateGuideTitle } from '@/core/guides/service';+import {+ clearStepAiPending,+ 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';+import { drainDescriptions } from './description-queue';type ResolveFailure = Extract<GuideDescriptionError, 'no-api-key' | 'no-steps'>;@@ -39,8 +46,15 @@ async function applyFallbackTitle(guideId: string) {);}+export async function settlePendingDescriptions(guideId: string) {+ await drainDescriptions(guideId);+ const pending = (await getStepsForGuide(guideId)).filter((s) => s.aiPending);+ await Promise.all(pending.map((s) => clearStepAiPending(s.id)));+}+export async function generateGuideMetaOnStop(guideId: string) {try {+ await settlePendingDescriptions(guideId);const inputs = await resolveGuideMetaInputs(guideId);if (!inputs.ok) {if (inputs.reason === 'no-api-key') await applyFallbackTitle(guideId);diff --git a/src/entrypoints/background/index.ts b/src/entrypoints/background/index.tsindex 3868e2d..5afaa5f 100644--- a/src/entrypoints/background/index.ts+++ b/src/entrypoints/background/index.ts@@ -17,7 +17,7 @@ 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 { generateDescriptionOnDemand, generateGuideMetaOnStop, settlePendingDescriptions } from './guide-meta';import { registerNavigationListeners } from './navigation';import { handleCaptureStep, handleFinalizeInputStep, handleUpdateInputStep } from './step-pipeline';import { broadcastStartCapture, broadcastStopCapture, showNotificationOnTab } from './tab-manager';@@ -124,6 +124,7 @@ export default defineBackground(() => {if (guideId) void stopVoiceNarration(guideId);if (guideId && insertTargetGuideId !== null && insertAtIndex !== null) {+ await settlePendingDescriptions(guideId);await createSnapshot(insertTargetGuideId);await mergeGuideInto(guideId, insertTargetGuideId, insertAtIndex);return { success: true, guideId: insertTargetGuideId, inserted: true };diff --git a/src/entrypoints/background/step-pipeline.ts b/src/entrypoints/background/step-pipeline.tsindex fca37c4..c9a37a1 100644--- a/src/entrypoints/background/step-pipeline.ts+++ b/src/entrypoints/background/step-pipeline.ts@@ -16,6 +16,7 @@ import { captureVisibleTab, localStorage } from '@/lib/browser-api';import { logger } from '@/lib/logger';import type { CaptureStepData, CaptureStepResponse } from '@/lib/messaging';import { getActor } from './actor';+import { queueDescription } from './description-queue';async function takeScreenshot(stepId: string, meta: ElementMeta): Promise<string | undefined> {try {@@ -96,12 +97,9 @@ export async function handleCaptureStep(data: CaptureStepData): Promise<CaptureS});await addStepToGuide(guideId, stepId);- if (data.action !== 'input' && data.domContext) {- try {- await tryAIDescription(stepId, data.domContext);- } catch (err) {- logger.error('AI description failed', err);- }+ const domContext = data.domContext;+ if (data.action !== 'input' && domContext) {+ queueDescription(guideId, () => tryAIDescription(stepId, domContext));}return { stepId };@@ -124,11 +122,8 @@ export async function handleFinalizeInputStep(if (screenshotId) updates.screenshotId = screenshotId;await db.steps.update(stepId, updates);- if (domContext) {- try {- await tryAIDescription(stepId, domContext);- } catch (err) {- logger.error('AI description failed on finalize', err);- }+ const guideId = (await db.steps.get(stepId))?.guideId;+ if (domContext && guideId) {+ queueDescription(guideId, () => tryAIDescription(stepId, domContext));}}