🎬 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: choose whether ai writes step descriptions and guide titles
Luis Ortiz97d2bf68b1d7
diff --git a/packages/core/src/capture/__tests__/write-step.test.ts b/packages/core/src/capture/__tests__/write-step.test.tsindex 178dd24..d456c37 100644--- a/packages/core/src/capture/__tests__/write-step.test.ts+++ b/packages/core/src/capture/__tests__/write-step.test.ts@@ -3,6 +3,7 @@ import type { ElementMeta } from '@/core/guides/types';const created: Array<Record<string, unknown>> = [];let hasKey = true;+let aiForSteps = true;vi.mock('@/core/guides/service', () => ({createStep: vi.fn(async (step: Record<string, unknown>) => {@@ -15,6 +16,7 @@ vi.mock('../ai/read-ai-credentials', () => ({readAiCredentials: vi.fn(async () => (hasKey ? { provider: 'openai', model: 'm', apiKey: 'k' } : null)),}));vi.mock('../ai/description-queue', () => ({ queueDescription: vi.fn() }));+vi.mock('../ai/read-ai-use', () => ({ readAiUse: vi.fn(async () => ({ steps: aiForSteps, guide: true })) }));import { queueDescription } from '../ai/description-queue';import { buildFallbackDescription } from '../step-description';@@ -39,6 +41,7 @@ function step(overrides: Partial<StepWrite> = {}): StepWrite {beforeEach(() => {created.length = 0;hasKey = true;+ aiForSteps = true;vi.mocked(queueDescription).mockClear();});@@ -52,6 +55,14 @@ describe('writeStep', () => {expect(queueDescription).toHaveBeenCalledTimes(2);});+ it('leaves the step settled and asks nothing when AI is off for steps, even with a key', async () => {+ aiForSteps = false;+ const written = await writeStep(step());++ expect(written.pending).toBe(false);+ expect(queueDescription).not.toHaveBeenCalled();+ });+it('leaves the step settled and asks nothing without a key', async () => {hasKey = false;const written = await writeStep(step());diff --git a/packages/core/src/capture/ai/finish-guide.ts b/packages/core/src/capture/ai/finish-guide.tsindex 95401e2..8ed764b 100644--- a/packages/core/src/capture/ai/finish-guide.ts+++ b/packages/core/src/capture/ai/finish-guide.ts@@ -3,6 +3,7 @@ import { logger } from '@/core/logger';import { resolveGuideMetaInputs } from './guide-description';import { generateGuideMeta } from './meta';import { readAiCredentials } from './read-ai-credentials';+import { readAiUse } from './read-ai-use';import { settleDescriptions } from './settle-descriptions';export interface FinishGuideOptions {@@ -17,7 +18,8 @@ export async function finishGuide(guideId: string, { fallbackTitle, settleNarratawait settleDescriptions(guideId);};- const keys = await readAiCredentials().catch(() => null);+ const use = await readAiUse().catch(() => ({ guide: true }));+ const keys = use.guide ? await readAiCredentials().catch(() => null) : null;if (!keys) {const titled = applyFallbackTitle().catch((err) => logger.error('Fallback title write failed', err));await settle().catch((err) => logger.error('Settling step descriptions failed', err));diff --git a/packages/core/src/capture/ai/read-ai-use.ts b/packages/core/src/capture/ai/read-ai-use.tsnew file mode 100644index 0000000..af39845--- /dev/null+++ b/packages/core/src/capture/ai/read-ai-use.ts@@ -0,0 +1,11 @@+import { localStorage } from '@/core/env';++export interface AiUse {+ steps: boolean;+ guide: boolean;+}++export async function readAiUse(): Promise<AiUse> {+ const stored = await localStorage.get(['aiForSteps', 'aiForGuide']);+ return { steps: stored.aiForSteps !== false, guide: stored.aiForGuide !== false };+}diff --git a/packages/core/src/capture/write-step.ts b/packages/core/src/capture/write-step.tsindex 622c18a..cfbe35d 100644--- a/packages/core/src/capture/write-step.ts+++ b/packages/core/src/capture/write-step.ts@@ -2,6 +2,7 @@ import { addStepToGuide, createStep, getStepsForGuide } from '@/core/guides/servimport type { ElementMeta, Step } from '@/core/guides/types';import { queueDescription } from './ai/description-queue';import { readAiCredentials } from './ai/read-ai-credentials';+import { readAiUse } from './ai/read-ai-use';import type { StepAction } from './step-action';import { buildFallbackDescription } from './step-description';@@ -39,7 +40,8 @@ function inOrder(write: () => Promise<void>): Promise<void> {}export async function writeStep(step: StepWrite): Promise<WrittenStep> {- const hasKey = (await readAiCredentials()) !== null;+ const [credentials, use] = await Promise.all([readAiCredentials(), readAiUse()]);+ const hasKey = credentials !== null && use.steps;const narrating = step.narration !== null;const willDescribe = step.describable && hasKey;const pending = narrating || willDescribe;diff --git a/packages/core/src/guides/types.ts b/packages/core/src/guides/types.tsindex 812e8f4..431dfcb 100644--- a/packages/core/src/guides/types.ts+++ b/packages/core/src/guides/types.ts@@ -81,6 +81,8 @@ export interface Settings {aiServerUrl: string;aiServerProtocol: AIProtocol;aiLanguage: string;+ aiForSteps: boolean;+ aiForGuide: boolean;voiceEnabled: boolean;voiceProvider: VoiceProvider;voiceApiKey: string;diff --git a/packages/ui/src/ai/components/AiSettings.tsx b/packages/ui/src/ai/components/AiSettings.tsxindex c7072e0..9c84ac4 100644--- a/packages/ui/src/ai/components/AiSettings.tsx+++ b/packages/ui/src/ai/components/AiSettings.tsx@@ -3,6 +3,7 @@ import { CUSTOM_MODEL_VALUE } from '@mimik/core/capture/ai/models';import { AI_LANGUAGES, type AILanguageCode } from '@mimik/core/capture/ai/prompts';import { i18n } from '@mimik/core/env';import { Sparkles } from 'lucide-react';+import { Checkbox } from '../../common/components/Checkbox';import { SettingsCard } from '../../common/components/SettingsCard';import { Input } from '../../components/ui/input';import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../../components/ui/select';@@ -19,8 +20,22 @@ interface AiSettingsProps {}export function AiSettings({ keys, onOpenKeys, onChange }: AiSettingsProps) {- const { provider, model, language, usingCustomModel, models, defaultModel, setProvider, setModel, setLanguage } =- useAiSettings({ onDirty: onChange });+ const {+ provider,+ model,+ language,+ forSteps,+ forGuide,+ usingCustomModel,+ models,+ defaultModel,+ setProvider,+ setModel,+ setLanguage,+ setForSteps,+ setForGuide,+ } = useAiSettings({ onDirty: onChange });+ const unused = !forSteps && !forGuide;const missing =provider === SERVER@@ -34,60 +49,88 @@ export function AiSettings({ keys, onOpenKeys, onChange }: AiSettingsProps) {hint={i18n.t('settings.aiDescriptionsHint')}><div>- <label className="block text-[11px] font-semibold text-foreground mb-1">{i18n.t('settings.provider')}</label>- <ProviderSelect- value={provider}- onChange={setProvider}- onOpenKeys={onOpenKeys}- options={aiProviderOptions((choice) =>- choice === SERVER ? Boolean(keys.server.url.trim()) : Boolean(keys.keys[choice]),- )}- />- {missing && <MissingKeyNote text={missing} onOpenKeys={onOpenKeys} />}+ <span className="block text-[11px] font-semibold text-foreground mb-1.5">{i18n.t('settings.aiUseFor')}</span>+ <div className="space-y-2">+ <Checkbox+ checked={forSteps}+ label={i18n.t('settings.aiForSteps')}+ hint={i18n.t('settings.aiForStepsHint')}+ onChange={setForSteps}+ />+ <Checkbox+ checked={forGuide}+ label={i18n.t('settings.aiForGuide')}+ hint={i18n.t('settings.aiForGuideHint')}+ onChange={setForGuide}+ />+ </div></div>- <div>- <label className="block text-[11px] font-semibold text-foreground mb-1">{i18n.t('settings.model')}</label>- {models.length > 0 && (- <Select value={usingCustomModel ? CUSTOM_MODEL_VALUE : model} onValueChange={setModel}>+ <div className={`space-y-3 transition-opacity ${unused ? 'opacity-45' : ''}`}>+ <div>+ <label className="block text-[11px] font-semibold text-foreground mb-1">{i18n.t('settings.provider')}</label>+ <ProviderSelect+ value={provider}+ onChange={setProvider}+ onOpenKeys={onOpenKeys}+ options={aiProviderOptions((choice) =>+ choice === SERVER ? Boolean(keys.server.url.trim()) : Boolean(keys.keys[choice]),+ )}+ />+ {missing && <MissingKeyNote text={missing} onOpenKeys={onOpenKeys} />}+ </div>++ <div>+ <label className="block text-[11px] font-semibold text-foreground mb-1">{i18n.t('settings.model')}</label>+ {models.length > 0 && (+ <Select value={usingCustomModel ? CUSTOM_MODEL_VALUE : model} onValueChange={setModel}>+ <SelectTrigger className="h-8">+ <SelectValue />+ </SelectTrigger>+ <SelectContent>+ {models.map((m) => (+ <SelectItem key={m.id} value={m.id}>+ {m.label}+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ )}+ {usingCustomModel && (+ <Input+ value={model}+ onChange={(e) => setModel(e.target.value)}+ placeholder={defaultModel || 'llama3.2'}+ aria-label={i18n.t('settings.modelCustom')}+ className={`${models.length > 0 ? 'mt-1.5 ' : ''}h-8 text-[13px] rounded-lg border-border`}+ />+ )}+ </div>++ <div>+ <label className="block text-[11px] font-semibold text-foreground mb-1">+ {i18n.t('settings.aiLanguage')}+ </label>+ <Select value={language} onValueChange={(v) => setLanguage(v as AILanguageCode)}><SelectTrigger className="h-8"><SelectValue /></SelectTrigger><SelectContent>- {models.map((m) => (- <SelectItem key={m.id} value={m.id}>- {m.label}+ {AI_LANGUAGES.map((lang) => (+ <SelectItem key={lang.code} value={lang.code}>+ {lang.label}</SelectItem>))}</SelectContent></Select>- )}- {usingCustomModel && (- <Input- value={model}- onChange={(e) => setModel(e.target.value)}- placeholder={defaultModel || 'llama3.2'}- aria-label={i18n.t('settings.modelCustom')}- className={`${models.length > 0 ? 'mt-1.5 ' : ''}h-8 text-[13px] rounded-lg border-border`}- />- )}+ </div></div>- <div>- <label className="block text-[11px] font-semibold text-foreground mb-1">{i18n.t('settings.aiLanguage')}</label>- <Select value={language} onValueChange={(v) => setLanguage(v as AILanguageCode)}>- <SelectTrigger className="h-8">- <SelectValue />- </SelectTrigger>- <SelectContent>- {AI_LANGUAGES.map((lang) => (- <SelectItem key={lang.code} value={lang.code}>- {lang.label}- </SelectItem>- ))}- </SelectContent>- </Select>- </div>+ {unused && (+ <p className="rounded-lg bg-secondary px-2.5 py-2 text-[11px] leading-relaxed text-muted-foreground">+ {i18n.t('settings.aiUnusedNote')}+ </p>+ )}</SettingsCard>);}diff --git a/packages/ui/src/ai/hooks/use-ai-settings.ts b/packages/ui/src/ai/hooks/use-ai-settings.tsindex 7e58556..d133a16 100644--- a/packages/ui/src/ai/hooks/use-ai-settings.ts+++ b/packages/ui/src/ai/hooks/use-ai-settings.ts@@ -10,18 +10,30 @@ import type { AILanguageCode } from '@mimik/core/capture/ai/prompts';import { localStorage } from '@mimik/core/env';import { useCallback, useEffect, useState } from 'react';-const AI_KEYS = ['aiProvider', 'aiModel', 'aiBaseUrl', 'aiServerUrl', 'aiLanguage'] as const;+const AI_KEYS = [+ 'aiProvider',+ 'aiModel',+ 'aiBaseUrl',+ 'aiServerUrl',+ 'aiLanguage',+ 'aiForSteps',+ 'aiForGuide',+] as const;export interface AiSettingsState {provider: AiChoice;model: string;language: AILanguageCode;+ forSteps: boolean;+ forGuide: boolean;usingCustomModel: boolean;models: AIModelOption[];defaultModel: string;setProvider: (provider: AiChoice) => void;setModel: (model: string) => void;setLanguage: (language: AILanguageCode) => void;+ setForSteps: (on: boolean) => void;+ setForGuide: (on: boolean) => void;}interface Options {@@ -38,6 +50,8 @@ export function useAiSettings({ onDirty, reloadOnFocus = false }: Options = {}):const [model, setModelState] = useState(AI_PROVIDERS[DEFAULT_AI_PROVIDER].defaultModel);const [language, setLanguageState] = useState<AILanguageCode>('en');const [customModel, setCustomModel] = useState(false);+ const [forSteps, setForStepsState] = useState(true);+ const [forGuide, setForGuideState] = useState(true);useEffect(() => {const load = () =>@@ -46,6 +60,8 @@ export function useAiSettings({ onDirty, reloadOnFocus = false }: Options = {}):setProviderState(next);setModelState(typeof stored.aiModel === 'string' ? stored.aiModel : defaultModelFor(next));if (typeof stored.aiLanguage === 'string') setLanguageState(stored.aiLanguage as AILanguageCode);+ setForStepsState(stored.aiForSteps !== false);+ setForGuideState(stored.aiForGuide !== false);});void load();@@ -98,17 +114,37 @@ export function useAiSettings({ onDirty, reloadOnFocus = false }: Options = {}):[dirty],);+ const setForSteps = useCallback(+ (on: boolean) => {+ setForStepsState(on);+ dirty({ aiForSteps: on });+ },+ [dirty],+ );++ const setForGuide = useCallback(+ (on: boolean) => {+ setForGuideState(on);+ dirty({ aiForGuide: on });+ },+ [dirty],+ );+const config = provider === SERVER ? null : AI_PROVIDERS[provider];return {provider,model,language,+ forSteps,+ forGuide,usingCustomModel: config === null || customModel || isCustomModel(model, config),models: config?.models ?? [],defaultModel: config?.defaultModel ?? '',setProvider,setModel,setLanguage,+ setForSteps,+ setForGuide,};}diff --git a/packages/ui/src/common/components/Checkbox.tsx b/packages/ui/src/common/components/Checkbox.tsxnew file mode 100644index 0000000..91d6754--- /dev/null+++ b/packages/ui/src/common/components/Checkbox.tsx@@ -0,0 +1,33 @@+import { Check } from 'lucide-react';++interface CheckboxProps {+ checked: boolean;+ label: string;+ hint?: string;+ onChange: (next: boolean) => void;+}++export function Checkbox({ checked, label, hint, onChange }: CheckboxProps) {+ return (+ <label className="flex w-full cursor-pointer items-start gap-2.5">+ <input+ type="checkbox"+ className="peer sr-only"+ checked={checked}+ onChange={(event) => onChange(event.target.checked)}+ />+ <span+ aria-hidden="true"+ className={`mt-0.5 flex h-4 w-4 shrink-0 items-center justify-center rounded border-[1.5px] transition-colors peer-focus-visible:ring-2 peer-focus-visible:ring-ring peer-focus-visible:ring-offset-1 ${+ checked ? 'border-accent bg-accent text-primary-foreground' : 'border-border bg-card'+ }`}+ >+ {checked && <Check size={11} strokeWidth={3} />}+ </span>+ <span className="min-w-0">+ <span className="block text-xs font-semibold text-foreground">{label}</span>+ {hint && <span className="block text-[11px] text-muted-foreground">{hint}</span>}+ </span>+ </label>+ );+}diff --git a/src/entrypoints/background/__tests__/guide-meta.test.ts b/src/entrypoints/background/__tests__/guide-meta.test.tsindex 7c559af..85c26d1 100644--- a/src/entrypoints/background/__tests__/guide-meta.test.ts+++ b/src/entrypoints/background/__tests__/guide-meta.test.ts@@ -133,6 +133,20 @@ describe('background guide-meta', () => {});describe('generateGuideMetaOnStop', () => {+ it('applies the domain fallback title without calling the model when AI is off for the guide', async () => {+ localStorageGetMock.mockResolvedValue({+ aiApiKey: 'key',+ aiProvider: 'openai',+ aiModel: 'gpt-4o',+ aiForGuide: false,+ });++ await generateGuideMetaOnStop(GUIDE_ID);++ expect(generateGuideMetaMock).not.toHaveBeenCalled();+ expect(updateGuideTitleMock).toHaveBeenCalledWith(GUIDE_ID, 'background.guideOnDomain[example.com]');+ });+it('applies the domain fallback title without calling the model when no key is set', async () => {localStorageGetMock.mockResolvedValue({});diff --git a/src/locales/de.yml b/src/locales/de.ymlindex 850fce9..1ebd558 100644--- a/src/locales/de.yml+++ b/src/locales/de.yml@@ -113,6 +113,12 @@ settings:title: EinstellungenaiDescriptions: "Schrittbeschreibungen"aiDescriptionsHint: "Mimik schreibt den Text jedes Schritts und benennt deine Anleitung mit deinem KI-Anbieter."+ aiUseFor: "KI verwenden für"+ aiForSteps: "Schrittbeschreibungen"+ aiForStepsHint: "Der Text unter jedem Screenshot."+ aiForGuide: "Titel und Zusammenfassung der Anleitung"+ aiForGuideHint: "Wird geschrieben, wenn du die Aufnahme beendest."+ aiUnusedNote: "Schritte behalten ihre einfachen Titel, und die Anleitung wird nach der Website oder App benannt. Sprachaufnahme und Sprachausgabe nutzen deinen Schlüssel weiterhin."modelCustom: Eigenes ModellbaseUrl: Basis-URLownServerHintOpenai: "Funktioniert mit Ollama, LM Studio, vLLM oder jedem OpenAI-kompatiblen Server."diff --git a/src/locales/en.yml b/src/locales/en.ymlindex 85d7814..9f759f1 100644--- a/src/locales/en.yml+++ b/src/locales/en.yml@@ -99,6 +99,12 @@ settings:title: SettingsaiDescriptions: "Step descriptions"aiDescriptionsHint: "Mimik writes each step's text and names your guide with your AI provider."+ aiUseFor: "Use AI for"+ aiForSteps: "Step descriptions"+ aiForStepsHint: "The text under each screenshot."+ aiForGuide: "Guide title and summary"+ aiForGuideHint: "Written when you finish recording."+ aiUnusedNote: "Steps keep their basic titles and the guide is named after the site or app. Narration and voice-over still use your key."provider: Providermodel: ModelmodelCustom: Custom modeldiff --git a/src/locales/es.yml b/src/locales/es.ymlindex 361094e..84c0e4c 100644--- a/src/locales/es.yml+++ b/src/locales/es.yml@@ -99,6 +99,12 @@ settings:title: AjustesaiDescriptions: "Descripciones de los pasos"aiDescriptionsHint: "Mimik escribe el texto de cada paso y nombra tu guía con tu proveedor de IA."+ aiUseFor: "Usar IA para"+ aiForSteps: "Descripciones de los pasos"+ aiForStepsHint: "El texto bajo cada captura."+ aiForGuide: "Título y resumen de la guía"+ aiForGuideHint: "Se escriben al terminar la grabación."+ aiUnusedNote: "Los pasos conservan sus títulos básicos y la guía toma el nombre del sitio o la app. La narración y la locución siguen usando tu clave."provider: Proveedormodel: ModelomodelCustom: Modelo personalizadodiff --git a/src/locales/fr.yml b/src/locales/fr.ymlindex ce150ae..5ec44be 100644--- a/src/locales/fr.yml+++ b/src/locales/fr.yml@@ -99,6 +99,12 @@ settings:title: "Paramètres"aiDescriptions: "Descriptions des étapes"aiDescriptionsHint: "Mimik rédige le texte de chaque étape et nomme votre guide avec votre fournisseur d’IA."+ aiUseFor: "Utiliser l'IA pour"+ aiForSteps: "Descriptions des étapes"+ aiForStepsHint: "Le texte sous chaque capture."+ aiForGuide: "Titre et résumé du guide"+ aiForGuideHint: "Rédigés à la fin de l'enregistrement."+ aiUnusedNote: "Les étapes gardent leurs titres simples et le guide prend le nom du site ou de l'application. La narration et la voix off utilisent toujours votre clé."provider: Fournisseurmodel: "Modèle"modelCustom: Modèle personnalisédiff --git a/src/locales/pt-BR.yml b/src/locales/pt-BR.ymlindex ee3d883..49b8cfb 100644--- a/src/locales/pt-BR.yml+++ b/src/locales/pt-BR.yml@@ -99,6 +99,12 @@ settings:title: AjustesaiDescriptions: "Descrições das etapas"aiDescriptionsHint: "O Mimik escreve o texto de cada etapa e dá nome ao seu guia com o seu provedor de IA."+ aiUseFor: "Usar IA para"+ aiForSteps: "Descrições dos passos"+ aiForStepsHint: "O texto abaixo de cada captura."+ aiForGuide: "Título e resumo do guia"+ aiForGuideHint: "Escritos quando você termina a gravação."+ aiUnusedNote: "Os passos mantêm os títulos básicos e o guia recebe o nome do site ou app. A narração e a locução continuam usando sua chave."provider: Provedormodel: ModelomodelCustom: Modelo personalizadodiff --git a/src/locales/zh-CN.yml b/src/locales/zh-CN.ymlindex 593342a..1bd082f 100644--- a/src/locales/zh-CN.yml+++ b/src/locales/zh-CN.yml@@ -99,6 +99,12 @@ settings:title: 设置aiDescriptions: "步骤描述"aiDescriptionsHint: "Mimik 使用你的 AI 服务商撰写每个步骤的文字并为指南命名。"+ aiUseFor: "AI 用于"+ aiForSteps: "步骤描述"+ aiForStepsHint: "每张截图下方的文字。"+ aiForGuide: "指南标题和摘要"+ aiForGuideHint: "在结束录制时生成。"+ aiUnusedNote: "步骤保留基础标题,指南以网站或应用命名。语音旁白和配音仍使用你的密钥。"provider: 提供商model: 模型modelCustom: 自定义模型