π¬ 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
refactor(core): move the description queue, its settle and on-demand guide descriptions into core
Luis Ortiz50e5ca2db8ab
diff --git a/src/entrypoints/background/__tests__/description-queue.test.ts b/packages/core/src/capture/ai/__tests__/description-queue.test.tssimilarity index 100%rename from src/entrypoints/background/__tests__/description-queue.test.tsrename to packages/core/src/capture/ai/__tests__/description-queue.test.tsdiff --git a/src/entrypoints/background/description-queue.ts b/packages/core/src/capture/ai/description-queue.tssimilarity index 96%rename from src/entrypoints/background/description-queue.tsrename to packages/core/src/capture/ai/description-queue.tsindex 5d2947c..3cab9bf 100644--- a/src/entrypoints/background/description-queue.ts+++ b/packages/core/src/capture/ai/description-queue.ts@@ -1,5 +1,5 @@-import { logger } from '@mimik/core/logger';import PQueue from 'p-queue';+import { logger } from '@/core/logger';const DRAIN_TIMEOUT_MS = 20000;const TASK_TIMEOUT_MS = 45000;diff --git a/packages/core/src/capture/ai/guide-description.ts b/packages/core/src/capture/ai/guide-description.tsnew file mode 100644index 0000000..b2d714b--- /dev/null+++ b/packages/core/src/capture/ai/guide-description.ts@@ -0,0 +1,49 @@+import { localStorage } from '@/core/env';+import { getStepsForGuide, updateGuideDescription } from '@/core/guides/service';+import { logger } from '@/core/logger';+import { AI_CREDENTIAL_SETTINGS, resolveAiCredentials } from './keys';+import { generateGuideMeta, guideMetaSteps } from './meta';++export type GuideDescriptionError = 'no-api-key' | 'no-steps' | 'generation-failed' | 'save-failed';++export interface GenerateGuideDescriptionResponse {+ description?: string;+ error?: GuideDescriptionError;+}++type GuideMetaInputs =+ | {+ ok: true;+ steps: { description: string; url: string }[];+ provider: string;+ model: string;+ apiKey: string;+ baseUrl?: string;+ }+ | { ok: false; reason: Extract<GuideDescriptionError, 'no-api-key' | 'no-steps'> };++export async function resolveGuideMetaInputs(guideId: string): Promise<GuideMetaInputs> {+ const keys = resolveAiCredentials(await localStorage.get([...AI_CREDENTIAL_SETTINGS]));+ if (!keys) return { ok: false, reason: 'no-api-key' };++ const steps = guideMetaSteps(await getStepsForGuide(guideId));+ if (steps.length === 0) return { ok: false, reason: 'no-steps' };++ return { ok: true, steps, ...keys };+}++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, inputs.baseUrl);+ 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/packages/core/src/capture/ai/settle-descriptions.ts b/packages/core/src/capture/ai/settle-descriptions.tsnew file mode 100644index 0000000..bf65d8f--- /dev/null+++ b/packages/core/src/capture/ai/settle-descriptions.ts@@ -0,0 +1,8 @@+import { clearStepAiPending, getStepsForGuide } from '@/core/guides/service';+import { drainDescriptions } from './description-queue';++export async function settleDescriptions(guideId: string): Promise<void> {+ await drainDescriptions(guideId);+ const pending = (await getStepsForGuide(guideId)).filter((step) => step.aiPending);+ await Promise.all(pending.map((step) => clearStepAiPending(step.id)));+}diff --git a/packages/ui/src/ai/lib/__tests__/guide-description-error.test.ts b/packages/ui/src/ai/lib/__tests__/guide-description-error.test.tsindex b086a86..8425703 100644--- a/packages/ui/src/ai/lib/__tests__/guide-description-error.test.ts+++ b/packages/ui/src/ai/lib/__tests__/guide-description-error.test.ts@@ -1,5 +1,5 @@+import type { GuideDescriptionError } from '@mimik/core/capture/ai/guide-description';import { describe, expect, it } from 'vitest';-import type { GuideDescriptionError } from '../../../env';import { guideDescriptionErrorMessage } from '../guide-description-error';const CASES: [GuideDescriptionError, string][] = [diff --git a/packages/ui/src/ai/lib/guide-description-error.ts b/packages/ui/src/ai/lib/guide-description-error.tsindex a21e92c..2241c6a 100644--- a/packages/ui/src/ai/lib/guide-description-error.ts+++ b/packages/ui/src/ai/lib/guide-description-error.ts@@ -1,5 +1,5 @@+import type { GuideDescriptionError } from '@mimik/core/capture/ai/guide-description';import { i18n } from '@mimik/core/env';-import type { GuideDescriptionError } from '../../env';const DESCRIPTION_ERROR_KEYS = {'no-api-key': 'editor.descriptionErrorNoApiKey',diff --git a/packages/ui/src/env.ts b/packages/ui/src/env.tsindex 557fa2b..984e524 100644--- a/packages/ui/src/env.ts+++ b/packages/ui/src/env.ts@@ -1,5 +1,3 @@-export type GuideDescriptionError = 'no-api-key' | 'no-steps' | 'generation-failed' | 'save-failed';-export interface RecordableTab {id: number;title: string;diff --git a/src/entrypoints/background/__tests__/guide-meta.test.ts b/src/entrypoints/background/__tests__/guide-meta.test.tsindex 4be8c9c..acb296d 100644--- a/src/entrypoints/background/__tests__/guide-meta.test.ts+++ b/src/entrypoints/background/__tests__/guide-meta.test.ts@@ -31,10 +31,14 @@ vi.mock('@/core/guides/service', () => ({updateGuideTitle: updateGuideTitleMock,}));-vi.mock('@/lib/browser-api/local-storage', () => ({ localStorage: { get: localStorageGetMock } }));+vi.mock('@/core/env', async (importOriginal) => ({+ ...(await importOriginal<typeof import('@/core/env')>()),+ localStorage: { get: localStorageGetMock },+}));+import { generateDescriptionOnDemand } from '@/core/capture/ai/guide-description';import { AI_PROVIDERS } from '@/core/capture/ai/models';-import { generateDescriptionOnDemand, generateGuideMetaOnStop } from '../guide-meta';+import { generateGuideMetaOnStop } from '../guide-meta';const GUIDE_ID = 'guide-1';diff --git a/src/entrypoints/background/describe-unnarrated.ts b/src/entrypoints/background/describe-unnarrated.tsindex 22bd2ed..c6b8808 100644--- a/src/entrypoints/background/describe-unnarrated.ts+++ b/src/entrypoints/background/describe-unnarrated.ts@@ -1,8 +1,8 @@import { logger } from '@mimik/core/logger';+import { queueDescription } from '@/core/capture/ai/description-queue';import { applyAiDescription, clearStepAiPending } from '@/core/guides/service';import { generateAiDescription } from './ai-description';import { takeDeferredDescription, takeDeferredDescriptions } from './deferred-descriptions';-import { queueDescription } from './description-queue';export function describeStepNow(guideId: string, stepId: string): void {const domContext = takeDeferredDescription(guideId, stepId);diff --git a/src/entrypoints/background/guide-meta.ts b/src/entrypoints/background/guide-meta.tsindex fa9e1fe..03a7aab 100644--- a/src/entrypoints/background/guide-meta.ts+++ b/src/entrypoints/background/guide-meta.ts@@ -1,42 +1,11 @@import { logger } from '@mimik/core/logger';import { i18n } from '#imports';-import { AI_CREDENTIAL_SETTINGS, resolveAiCredentials } from '@/core/capture/ai/keys';-import { generateGuideMeta, guideMetaSteps } from '@/core/capture/ai/meta';-import {- clearStepAiPending,- getGuideDomain,- getStepsForGuide,- updateGuideDescription,- updateGuideTitle,-} from '@/core/guides/service';-import { localStorage } from '@/lib/browser-api/local-storage';-import type { GenerateGuideDescriptionResponse, GuideDescriptionError } from '@/lib/messaging';-import { drainDescriptions } from './description-queue';+import { resolveGuideMetaInputs } from '@/core/capture/ai/guide-description';+import { generateGuideMeta } from '@/core/capture/ai/meta';+import { settleDescriptions } from '@/core/capture/ai/settle-descriptions';+import { getGuideDomain, updateGuideDescription, updateGuideTitle } from '@/core/guides/service';import { whenNarrationSettled } from './voice';-type ResolveFailure = Extract<GuideDescriptionError, 'no-api-key' | 'no-steps'>;--type GuideMetaInputs =- | {- ok: true;- steps: { description: string; url: string }[];- provider: string;- model: string;- apiKey: string;- baseUrl?: string;- }- | { ok: false; reason: ResolveFailure };--async function resolveGuideMetaInputs(guideId: string): Promise<GuideMetaInputs> {- const keys = resolveAiCredentials(await localStorage.get([...AI_CREDENTIAL_SETTINGS]));- if (!keys) return { ok: false, reason: 'no-api-key' };-- const steps = guideMetaSteps(await getStepsForGuide(guideId));- if (steps.length === 0) return { ok: false, reason: 'no-steps' };-- return { ok: true, steps, ...keys };-}-async function applyFallbackTitle(guideId: string) {const domain = await getGuideDomain(guideId);await updateGuideTitle(@@ -47,9 +16,7 @@ async function applyFallbackTitle(guideId: string) {export async function settlePendingDescriptions(guideId: string) {await whenNarrationSettled();- await drainDescriptions(guideId);- const pending = (await getStepsForGuide(guideId)).filter((s) => s.aiPending);- await Promise.all(pending.map((s) => clearStepAiPending(s.id)));+ await settleDescriptions(guideId);}export async function generateGuideMetaOnStop(guideId: string) {@@ -79,19 +46,3 @@ export async function generateGuideMetaOnStop(guideId: string) {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, inputs.baseUrl);- 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 cb146ce..6939eba 100644--- a/src/entrypoints/background/index.ts+++ b/src/entrypoints/background/index.ts@@ -2,6 +2,7 @@ import '@/lib/core-env';import '@/lib/ui-env';import { logger } from '@mimik/core/logger';import { browser, defineBackground } from '#imports';+import { generateDescriptionOnDemand } from '@/core/capture/ai/guide-description';import { rewriteSelection } from '@/core/capture/ai/rewrite';import { validateApiKey } from '@/core/capture/ai/validate';import { stepRequiresManual } from '@/core/guideme/manual';@@ -26,7 +27,7 @@ import { broadcastStateToPanel } from '@/lib/port/broadcast-state-to-panel';import { setupPortListener } from '@/lib/port/setup-port-listener';import { recordUpdate } from '@/lib/update-notice/record-update';import { getActor, getStateUpdate, initActor, initActorFallback, waitUntilReady } from './actor';-import { generateDescriptionOnDemand, generateGuideMetaOnStop, settlePendingDescriptions } from './guide-meta';+import { generateGuideMetaOnStop, settlePendingDescriptions } from './guide-meta';import { registerNavigationListeners } from './navigation';import { handleCaptureStep, handleFinalizeInputStep, handleUpdateInputStep } from './step-pipeline';import { broadcastStartCapture, broadcastStopCapture, showNotificationOnTab } from './tab-manager';diff --git a/src/entrypoints/background/step-pipeline.ts b/src/entrypoints/background/step-pipeline.tsindex 2a228ee..fc7804d 100644--- a/src/entrypoints/background/step-pipeline.ts+++ b/src/entrypoints/background/step-pipeline.ts@@ -1,4 +1,5 @@import { logger } from '@mimik/core/logger';+import { queueDescription } from '@/core/capture/ai/description-queue';import { AI_KEY_SETTINGS, resolveAiKey } from '@/core/capture/ai/keys';import type { DOMContext } from '@/core/capture/dom/context';import { CaptureState } from '@/core/capture/machine';@@ -21,7 +22,6 @@ import type { CaptureStepData, CaptureStepResponse } from '@/lib/messaging';import { getActor } from './actor';import { generateAiDescription } from './ai-description';import { deferDescription, shouldQueueAiDescription } from './deferred-descriptions';-import { queueDescription } from './description-queue';import { flushNarrationForStep, getVoiceUpdate } from './voice';async function takeScreenshot(stepId: string, meta: ElementMeta): Promise<string | undefined> {diff --git a/src/lib/messaging.ts b/src/lib/messaging.tsindex 6a4c2ac..285c72f 100644--- a/src/lib/messaging.ts+++ b/src/lib/messaging.ts@@ -1,4 +1,5 @@import { defineExtensionMessaging } from '@webext-core/messaging';+import type { GenerateGuideDescriptionResponse } from '@/core/capture/ai/guide-description';import type { RewriteError, RewriteSelectionResponse } from '@/core/capture/ai/rewrite';import type { CaptureStateValue } from '@/core/capture/machine';import type {@@ -62,17 +63,10 @@ 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 RewriteSelectionData {text: string;instruction: string;