Skip to content

armgit / mimik

Public Imported from GitHub
0

🎬 A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots πŸ“–

feat: add an OpenAI-compatible provider with a custom base URL

alvinlolloffae3b6696e2
diff --git a/AGENTS.md b/AGENTS.md
old mode 100644
new mode 100755
index 9a2bbb6..47dc3e3
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,247 +1 @@
-# Mimik
-
-Open-source Chrome extension that auto-captures browser workflows and generates step-by-step guides. No backend, no account, no data leaves the browser.
-
-## What It Does
-
-You click "Record," perform a workflow in your browser, and Mimik automatically captures each action as a step with an annotated screenshot and description. You can edit the guide, replay it on a live page, or export it as a file.
-
-**Core loop: Record β†’ Edit β†’ Replay or Export.**
-
-## Architecture
-
-**Everything runs in the Chrome extension. No backend.**
-
-- Storage: IndexedDB via Dexie.js (browser-local)
-- AI descriptions: optional, user provides their own API key in settings
-- Export: generated client-side (no server rendering)
-- No auth, no database, no hosting, no Docker
-
-### Directory Structure
-
-```
-src/
-β”œβ”€β”€ core/ # Business logic (no UI dependencies)
-β”‚ β”œβ”€β”€ capture/ # Recording pipeline
-β”‚ β”‚ β”œβ”€β”€ ai/ # AI description + title generation (Vercel AI SDK)
-β”‚ β”‚ β”‚ β”œβ”€β”€ description.ts # getAIDescription (DOM context β†’ AI β†’ step text)
-β”‚ β”‚ β”‚ β”œβ”€β”€ title.ts # generateGuideTitle (steps β†’ AI β†’ guide name)
-β”‚ β”‚ β”‚ β”œβ”€β”€ models.ts # AI_PROVIDERS config (OpenAI/Anthropic model lists)
-β”‚ β”‚ β”‚ β”œβ”€β”€ prompts.ts # Prompt templates
-β”‚ β”‚ β”‚ └── provider.ts # createModel factory (OpenAI/Anthropic)
-β”‚ β”‚ β”œβ”€β”€ dom/ # DOM extraction utilities
-β”‚ β”‚ β”‚ β”œβ”€β”€ context.ts # DOMContext extraction + serialization
-β”‚ β”‚ β”‚ β”œβ”€β”€ element-meta.ts # extractElementMeta (selector, text, aria, rect)
-β”‚ β”‚ β”‚ └── element-utils.ts # findFocusableAncestor, isTextField, etc.
-β”‚ β”‚ β”œβ”€β”€ events/ # Event capture system
-β”‚ β”‚ β”‚ β”œβ”€β”€ handlers.ts # CaptureController class + startCapture
-β”‚ β”‚ β”‚ └── input-session.ts # InputSession (typing lifecycle)
-β”‚ β”‚ β”œβ”€β”€ machine.ts # xstate capture state machine
-β”‚ β”‚ β”œβ”€β”€ session.ts # CaptureSession (lifecycle manager)
-β”‚ β”‚ β”œβ”€β”€ spa-nav.ts # SPA navigation tracking
-β”‚ β”‚ β”œβ”€β”€ start-notification.ts # Recording notification overlay
-β”‚ β”‚ └── step-description.ts # Fallback rule-based descriptions
-β”‚ β”œβ”€β”€ blur/ # Smart blur: regex presets, DOM scanner, element picker, panel UI
-β”‚ β”œβ”€β”€ export/ # HTML, PDF, DOCX, Markdown, video generators + shared utils
-β”‚ └── guides/ # Data layer: types, Dexie DB, CRUD service
-β”œβ”€β”€ entrypoints/ # Chrome extension entry points (WXT)
-β”‚ β”œβ”€β”€ background/ # Service worker: state machine, message handlers, tab management
-β”‚ β”œβ”€β”€ content.ts # Content script: CaptureSession, event listeners
-β”‚ β”œβ”€β”€ sidepanel/ # Side panel React mount
-β”‚ β”œβ”€β”€ fullview/ # Full-page view React mount
-β”‚ β”œβ”€β”€ onboarding/ # Onboarding wizard (opens on first install)
-β”‚ └── options/ # Settings page React mount
-β”œβ”€β”€ lib/ # Shared utilities
-β”‚ β”œβ”€β”€ messaging.ts # Extension messaging protocol (webext-core)
-β”‚ β”œβ”€β”€ port.ts # Long-lived port: background ↔ sidepanel
-β”‚ β”œβ”€β”€ browser-api.ts # Chrome API wrappers
-β”‚ β”œβ”€β”€ tab-messages.ts # Content script message types
-β”‚ β”œβ”€β”€ logger.ts # Logging utility
-β”‚ └── utils.ts # Shared helpers (dates, URLs, cn)
-β”œβ”€β”€ stores/ # Zustand state stores
-β”‚ └── fullview.ts # Fullview UI state (search, counts, guide data)
-└── ui/ # React components
- β”œβ”€β”€ components/ui/ # shadcn/ui primitives (button, input, dialog, badge)
- β”œβ”€β”€ fullview/ # Full-page dashboard
- β”‚ β”œβ”€β”€ components/ # Extracted sub-components (grid, list, search, etc.)
- β”‚ β”œβ”€β”€ App.tsx
- β”‚ β”œβ”€β”€ TopNav.tsx
- β”‚ β”œβ”€β”€ SearchModal.tsx
- β”‚ β”œβ”€β”€ GuideContent.tsx
- β”‚ β”œβ”€β”€ LibraryContent.tsx
- β”‚ └── router.ts
- β”œβ”€β”€ sidepanel/ # Side panel UI
- β”‚ β”œβ”€β”€ App.tsx
- β”‚ β”œβ”€β”€ LibraryView.tsx
- β”‚ β”œβ”€β”€ GuideEditor.tsx
- β”‚ β”œβ”€β”€ RecordingView.tsx
- β”‚ β”œβ”€β”€ StepCard.tsx
- β”‚ β”œβ”€β”€ ExportMenu.tsx
- β”‚ β”œβ”€β”€ BlurCanvas.tsx
- β”‚ └── ZoomScreenshot.tsx
- β”œβ”€β”€ onboarding/ # Onboarding wizard UI
- β”‚ └── App.tsx # 5-step wizard (welcome, AI, blur, pin, done)
- β”œβ”€β”€ shared/ # Shared UI components
- β”‚ └── SettingsView.tsx # AI settings (provider, model, API key)
- └── options/ # Settings page
- └── App.tsx
-```
-
-## State Management
-
-| Layer | Tool | Purpose |
-|-------|------|---------|
-| Capture lifecycle | xstate | State machine (IDLE ↔ RECORDING) in background service worker |
-| Fullview UI | Zustand | Search modal, guide counts, active guide data |
-| Persistence | Dexie (IndexedDB) | Guides, steps, screenshots, snapshots |
-| Service worker recovery | sessionStorage | xstate machine snapshot persistence |
-| Background β†’ Sidepanel | Port messaging | Real-time state broadcast |
-| Cross-context sync | BroadcastChannel | Guide mutations (star, delete) across sidepanel/fullview |
-
-## Extension Entry Points
-
-| Entry Point | File | Purpose |
-|-------------|------|---------|
-| Background | `entrypoints/background/` | Service worker: xstate actor, message handlers, tab management |
-| Content Script | `entrypoints/content.ts` | Injected into all tabs: CaptureSession, event listeners |
-| Side Panel | `entrypoints/sidepanel/` | Recording controls, library, guide editor, settings |
-| Full View | `entrypoints/fullview/` | Dashboard: library browse, guide viewer, Ctrl+K search |
-| Onboarding | `entrypoints/onboarding/` | First-install wizard: AI setup, smart blur, pin extension |
-| Options | `entrypoints/options/` | Settings page (shared SettingsView in centered card) |
-
-## Messaging
-
-```
-Content Script ←→ Background Service Worker ←→ Sidepanel / Fullview
-```
-
-**Extension messages** (webext-core, `lib/messaging.ts`):
-- `getState` β†’ current capture state, step count, guide ID
-- `startRecording({url})` β†’ creates guide, returns guideId
-- `stopRecording()` β†’ finalizes guide, generates AI title
-- `captureStep({guideId, action, elementMeta, domContext})` β†’ screenshots + creates step
-- `updateInputStep({stepId, description})` β†’ updates typing step description
-- `finalizeInputStep({stepId, elementMeta, domContext})` β†’ final screenshot + AI description
-
-**Tab messages** (content script ↔ background, `lib/tab-messages.ts`):
-- `PING` / `START_CAPTURE` / `STOP_CAPTURE` β€” lifecycle
-- `SHOW_NOTIFICATION` β€” "Recording started" overlay
-- `URL_CHANGED` / `GET_ROUTE` β€” SPA navigation tracking
-
-## Capture Pipeline
-
-**Start recording:**
-1. User clicks "Start Capture" in sidepanel
-2. Background transitions xstate machine IDLE β†’ RECORDING
-3. Creates Guide in IndexedDB, broadcasts `START_CAPTURE` to all tabs
-4. Content scripts create CaptureSession β†’ CaptureController (event listeners)
-5. Shows recording notification overlay on active tab
-
-**Capture a click:**
-1. Content script's CaptureController detects click via DOM event listener
-2. Click handler pushes async work into PQueue (concurrency: 1)
-3. Enqueueing hides the hover ring (`pointerdown` already did, on mouse paths); queue waits 3 frames then sends `captureStep`
-4. Background calls `captureVisibleTab` (ring is hidden, page hasn't reacted yet)
-5. Saves Screenshot + Step to IndexedDB
-6. Queues the AI description from DOM context text (serialized in the background; the step carries `aiPending` until it lands) rather than awaiting it
-7. Returns `{ stepId }` β†’ queue processes next event; the ring returns only once the queue is fully drained
-
-**Capture text input (typing):**
-1. Click on text field β†’ CaptureController starts InputSession β†’ `captureStep` with initial screenshot
-2. Each keystroke β†’ InputSession.update() β†’ `updateInputStep` (description only, fire-and-forget)
-3. Enter/Escape/focusout β†’ InputSession.finalize() β†’ `finalizeInputStep` β†’ final screenshot replaces initial + queued AI description
-4. Result: one step for entire typing interaction
-
-**Stop recording:**
-1. Background transitions RECORDING β†’ IDLE
-2. Broadcasts `STOP_CAPTURE`, content scripts flush pending input sessions
-3. Background drains queued step descriptions (20s cap), then generates the guide title from step descriptions + URLs via AI
-4. Opens fullview dashboard with the guide
-
-## DOM Context (AI Input)
-
-Instead of sending screenshots to the AI for step descriptions, Mimik extracts a lightweight DOM context (~50-100 tokens) from around the target element:
-
-```
-Page: "Public profile - Settings" /settings/profile
-Container: form "Public profile"
-Heading: "Public profile"
-Siblings: input "Name", input "Email", textarea "Bio", button "Update profile"
-β†’ Target: button "Update profile" (click)
-```
-
-Extraction walks up from the target element to find:
-- Page title + URL path
-- Nearest semantic container (form, nav, dialog, section) or 3 levels up
-- Nearest heading
-- Sibling interactive elements in the same container (max 10)
-
-## Export Formats
-
-| Format | Generator | Details |
-|--------|-----------|---------|
-| HTML | `core/export/html-export.ts` | Self-contained, base64 images, inline CSS |
-| PDF | `core/export/pdf-export.ts` | jsPDF, A4 portrait, auto page breaks |
-| Markdown | `core/export/markdown-export.ts` | Standard MD with base64 image data URLs |
-| DOCX | `core/export/docx-export.ts` | Lazy-imported, Word-compatible |
-| Video | `core/export/video-export.ts` | WebCodecs via mediabunny (lazy), mp4/H.264 with WebM/VP9 fallback |
-
-Video frames reuse `renderScreenshot`, so the auto-crop, click-target outline, annotations and
-redactions are already baked in. Each step holds 1.5s wide, eases into a crop around the target
-over 0.73s, holds 3s close, and consecutive steps cross-dissolve over 0.33s at 30fps. Capability
-probing lives in `video-support.ts`, which must stay free of mediabunny imports because both
-export UIs load it eagerly.
-
-## Tech Stack
-
-| Layer | Technology |
-|-------|-----------|
-| Extension framework | WXT (Manifest V3) |
-| Language | TypeScript |
-| UI | React 19 |
-| Styling | Tailwind CSS v4 |
-| Components | shadcn/ui |
-| State (capture) | xstate |
-| State (UI) | Zustand |
-| Storage | Dexie.js (IndexedDB) |
-| Messaging | webext-core |
-| Export | jsPDF, docx, mediabunny (WebCodecs video), client-side HTML/Markdown |
-| AI (optional) | Vercel AI SDK (`ai`, `@ai-sdk/openai`, `@ai-sdk/anthropic`) |
-| Event queue | p-queue (concurrency: 1) |
-| Icons | Lucide React |
-| Dates | dayjs |
-| DOM utils | css-selector-generator |
-
-## Design System
-
-All colors are defined as CSS variables in `src/ui/global.css` and used via Tailwind classes:
-
-| Token | Color | Usage |
-|-------|-------|-------|
-| `--color-foreground` | `#1E1B4B` | Primary text (deep navy) |
-| `--color-muted-foreground` | `#6B7280` | Secondary text |
-| `--color-border` | `#C7D2FE` | Borders, dividers (lavender) |
-| `--color-secondary` | `#EEF2FF` | Light wash backgrounds |
-| `--color-accent` | `#4F46E5` | Icons, links, focus rings, toggles, meters (indigo) β€” never a button fill |
-| `--color-primary` | `#1E1B4B` | Primary buttons, badges, dark backgrounds |
-| `--color-primary-foreground` | `#C7D2FE` | Text on dark backgrounds |
-| `--color-lavender` | `#C7D2FE` | Soft accent |
-| `--color-purple` | `#4F46E5` | Primary indigo |
-| `--color-deep` | `#1E1B4B` | Deepest navy |
-| `--color-violet` | `#38BDF8` | Sky blue accent |
-| `--color-success` | `#059669` | Success green |
-
-Font: Poppins (loaded via `@fontsource/poppins`).
-
-## Key Technical Details
-
-- **Async event queue** in content script (PQueue, concurrency 1) serializes capture work β€” each action awaits the background round-trip (screenshot + step write, not the AI description) before the next starts
-- **Hover ring hidden when work is enqueued** (`CaptureController.enqueue`, instant `display:none`), and `show()` stays suppressed until the queue drains β€” a second click while the first capture is still in flight can't bring the ring back before the screenshot. `pointerdown` hides it earlier still, on top of `captureAction`'s 3-frame wait
-- **Input session** aggregates all typing on a field into one step β€” click creates it, keystrokes update description, finalize takes final screenshot
-- **DOM context** sent as text to AI instead of screenshots β€” 15-30x cheaper per step
-- **Hover ring** (`lib/hover-ring.ts`) is a closed-Shadow-DOM host marked `data-mimik-ignore`, shared by recording and the blur picker (purple). Recording reads the user's `targetColor` so the live ring matches the dashed target baked into screenshots. Never drawn on `iframe`/`embed`/`object` β€” a capture inside a subframe can't hide the top frame's ring
-- **Content script injection** pings first, falls back to `chrome.scripting.executeScript()` for tabs without the script
-- **xstate snapshot** persisted to sessionStorage so the state machine survives service worker restarts
-- **Recording notification** uses `animationend` event (not hardcoded delays) for timing
-- **Font loading** uses `@fontsource/poppins` (CSP-safe, no CDN dependency)
-- **Cross-context sync** via BroadcastChannel β€” star/delete events update other views without full reload
+AGENTS.md
\ No newline at end of file
diff --git a/src/core/capture/ai/__tests__/models.test.ts b/src/core/capture/ai/__tests__/models.test.ts
index d023619..4aa9086 100644
--- a/src/core/capture/ai/__tests__/models.test.ts
+++ b/src/core/capture/ai/__tests__/models.test.ts
@@ -55,7 +55,24 @@ describe('custom model sentinel', () => {
describe('every provider default is selectable', () => {
it.each(Object.entries(AI_PROVIDERS))('%s lists its own default model', (_key, config) => {
- expect(config.models.some((option) => option.id === config.defaultModel)).toBe(true);
+ if (!config.baseUrl) {
+ expect(config.models.some((option) => option.id === config.defaultModel)).toBe(true);
+ }
+ });
+});
+
+describe('openaiCompatible provider', () => {
+ it('opts into a base URL and a free-text model', () => {
+ const config = AI_PROVIDERS.openaiCompatible;
+ expect(config.baseUrl).toBe(true);
+ expect(isCustomModel('llama3:70b', config)).toBe(true);
+ expect(isCustomModel('', config)).toBe(false);
+ });
+
+ it('carries the base URL label in every locale', () => {
+ for (const locale of LOCALES) {
+ expect(localeKeys(locale).has('settings.baseUrl')).toBe(true);
+ }
});
});
diff --git a/src/core/capture/ai/__tests__/validate.test.ts b/src/core/capture/ai/__tests__/validate.test.ts
index 47927d8..4deb824 100644
--- a/src/core/capture/ai/__tests__/validate.test.ts
+++ b/src/core/capture/ai/__tests__/validate.test.ts
@@ -70,4 +70,24 @@ describe('validateApiKey', () => {
expect(await validateApiKey('mystery', 'secret')).toEqual({ valid: false, reason: 'network' });
expect(fetchMock).not.toHaveBeenCalled();
});
+
+ it('checks a compatible key against the stored base URL, not openai', async () => {
+ fetchMock.mockResolvedValue({ ok: true, status: 200 });
+ expect(await validateApiKey('openaiCompatible', 'sk-key', 'https://api.example.com/v1')).toEqual({ valid: true });
+ const [url, init] = fetchMock.mock.calls[0];
+ expect(url).toBe('https://api.example.com/v1/models');
+ expect(init.headers.Authorization).toBe('Bearer sk-key');
+ });
+
+ it('strips trailing slashes from a compatible base URL', async () => {
+ fetchMock.mockResolvedValue({ ok: true, status: 200 });
+ await validateApiKey('openaiCompatible', 'sk-key', 'https://api.example.com/v1///');
+ const [url] = fetchMock.mock.calls[0];
+ expect(url).toBe('https://api.example.com/v1/models');
+ });
+
+ it('does not send a compatible key anywhere when no base URL is set', async () => {
+ expect(await validateApiKey('openaiCompatible', 'sk-key')).toEqual({ valid: false, reason: 'network' });
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
});
diff --git a/src/core/capture/ai/description.ts b/src/core/capture/ai/description.ts
index 38acf26..b66ace6 100644
--- a/src/core/capture/ai/description.ts
+++ b/src/core/capture/ai/description.ts
@@ -11,12 +11,13 @@ export async function getAIDescription(
provider: string,
model: string,
apiKey: string,
+ baseUrl?: string,
): Promise<string | null> {
try {
const settings = await localStorage.get(['aiLanguage']);
const locale = (settings.aiLanguage as string) || 'en';
const { text } = await generateText({
- model: createModel(provider, model, apiKey),
+ model: createModel(provider, model, apiKey, baseUrl),
prompt:
STEP_DESCRIPTION_PROMPT.replace('{{context}}', serializeDOMContext(domContext)) + getLanguageSuffix(locale),
maxOutputTokens: 50,
diff --git a/src/core/capture/ai/meta.ts b/src/core/capture/ai/meta.ts
index 7f683a0..e786de2 100644
--- a/src/core/capture/ai/meta.ts
+++ b/src/core/capture/ai/meta.ts
@@ -58,6 +58,7 @@ export async function generateGuideMeta(
provider: string,
model: string,
apiKey: string,
+ baseUrl?: string,
): Promise<GuideMeta | null> {
if (steps.length === 0) return null;
@@ -65,7 +66,7 @@ export async function generateGuideMeta(
const settings = await localStorage.get(['aiLanguage']);
const locale = (settings.aiLanguage as string) || 'en';
const prompt = GUIDE_META_PROMPT.replace('{{steps}}', formatted) + getLanguageSuffix(locale);
- const aiModel = createModel(provider, model, apiKey);
+ const aiModel = createModel(provider, model, apiKey, baseUrl);
try {
const { object } = await generateObject({
diff --git a/src/core/capture/ai/models.ts b/src/core/capture/ai/models.ts
index 9c7685a..f3e8642 100644
--- a/src/core/capture/ai/models.ts
+++ b/src/core/capture/ai/models.ts
@@ -7,6 +7,8 @@ export interface AIProviderConfig {
label: string;
defaultModel: string;
models: AIModelOption[];
+ /** Whether this provider uses a custom base URL (e.g. OpenAI-compatible endpoints). */
+ baseUrl?: boolean;
}
export const AI_PROVIDERS: Record<string, AIProviderConfig> = {
@@ -29,6 +31,12 @@ export const AI_PROVIDERS: Record<string, AIProviderConfig> = {
{ id: 'claude-sonnet-4-20250514', label: 'Claude Sonnet 4' },
],
},
+ openaiCompatible: {
+ label: 'OpenAI Compatible',
+ defaultModel: 'gpt-4o-mini',
+ models: [],
+ baseUrl: true,
+ },
};
export type AIProviderKey = keyof typeof AI_PROVIDERS;
diff --git a/src/core/capture/ai/provider.ts b/src/core/capture/ai/provider.ts
index 02a9c27..da882ae 100644
--- a/src/core/capture/ai/provider.ts
+++ b/src/core/capture/ai/provider.ts
@@ -1,7 +1,11 @@
import { createAnthropic } from '@ai-sdk/anthropic';
import { createOpenAI } from '@ai-sdk/openai';
-export function createModel(provider: string, model: string, apiKey: string) {
+export function createModel(provider: string, model: string, apiKey: string, baseUrl?: string) {
if (provider === 'anthropic') return createAnthropic({ apiKey })(model);
+ if (provider === 'openaiCompatible') {
+ const baseURL = baseUrl?.trim();
+ return createOpenAI(baseURL ? { apiKey, baseURL } : { apiKey })(model);
+ }
return createOpenAI({ apiKey })(model);
}
diff --git a/src/core/capture/ai/rewrite.ts b/src/core/capture/ai/rewrite.ts
index 6251307..ea99cb7 100644
--- a/src/core/capture/ai/rewrite.ts
+++ b/src/core/capture/ai/rewrite.ts
@@ -22,7 +22,7 @@ export function buildRewritePrompt(text: string, instruction: string, locale: st
}
export async function rewriteSelection(text: string, instruction: string): Promise<RewriteSelectionResponse> {
- const settings = await localStorage.get(['aiApiKey', 'aiProvider', 'aiModel', 'aiLanguage']);
+ const settings = await localStorage.get(['aiApiKey', 'aiProvider', 'aiModel', 'aiBaseUrl', 'aiLanguage']);
if (!settings.aiApiKey) return { error: 'no-api-key' };
const provider = (settings.aiProvider as string) || 'openai';
@@ -33,6 +33,7 @@ export async function rewriteSelection(text: string, instruction: string): Promi
provider,
(settings.aiModel as string) || AI_PROVIDERS[provider].defaultModel,
settings.aiApiKey as string,
+ settings.aiBaseUrl as string | undefined,
),
prompt: buildRewritePrompt(text, instruction, (settings.aiLanguage as string) || 'en'),
maxOutputTokens: 400,
diff --git a/src/core/capture/ai/validate.ts b/src/core/capture/ai/validate.ts
index 1aa7f09..ef4963a 100644
--- a/src/core/capture/ai/validate.ts
+++ b/src/core/capture/ai/validate.ts
@@ -4,34 +4,49 @@ export type KeyValidation = { valid: true } | { valid: false; reason: 'rejected'
const REQUEST_TIMEOUT_MS = 10_000;
-const ENDPOINTS: Record<string, { url: string; headers: (key: string) => Record<string, string> }> = {
- openai: {
- url: 'https://api.openai.com/v1/models',
- headers: (key) => ({ Authorization: `Bearer ${key}` }),
- },
- anthropic: {
- url: 'https://api.anthropic.com/v1/models',
- headers: (key) => ({
- 'x-api-key': key,
- 'anthropic-version': '2023-06-01',
- 'anthropic-dangerous-direct-browser-access': 'true',
- }),
- },
- groq: {
- url: 'https://api.groq.com/openai/v1/models',
- headers: (key) => ({ Authorization: `Bearer ${key}` }),
- },
-};
+const ENDPOINTS: Record<string, { url?: string; baseUrl?: boolean; headers: (key: string) => Record<string, string> }> =
+ {
+ openai: {
+ url: 'https://api.openai.com/v1/models',
+ headers: (key) => ({ Authorization: `Bearer ${key}` }),
+ },
+ anthropic: {
+ url: 'https://api.anthropic.com/v1/models',
+ headers: (key) => ({
+ 'x-api-key': key,
+ 'anthropic-version': '2023-06-01',
+ 'anthropic-dangerous-direct-browser-access': 'true',
+ }),
+ },
+ groq: {
+ url: 'https://api.groq.com/openai/v1/models',
+ headers: (key) => ({ Authorization: `Bearer ${key}` }),
+ },
+ openaiCompatible: {
+ baseUrl: true,
+ headers: (key) => ({ Authorization: `Bearer ${key}` }),
+ },
+ };
-export async function validateApiKey(provider: string, apiKey: string): Promise<KeyValidation> {
+function endpointUrl(provider: string, baseUrl?: string): string | null {
const endpoint = ENDPOINTS[provider];
- if (!endpoint) {
+ if (!endpoint) return null;
+ if (endpoint.baseUrl) {
+ const trimmed = baseUrl?.trim().replace(/\/+$/, '');
+ return trimmed ? `${trimmed}/models` : null;
+ }
+ return endpoint.url ?? null;
+}
+
+export async function validateApiKey(provider: string, apiKey: string, baseUrl?: string): Promise<KeyValidation> {
+ const url = endpointUrl(provider, baseUrl);
+ if (!url) {
logger.error('No API key validation endpoint for provider', provider);
return { valid: false, reason: 'network' };
}
try {
- const res = await fetch(endpoint.url, {
- headers: endpoint.headers(apiKey),
+ const res = await fetch(url, {
+ headers: ENDPOINTS[provider].headers(apiKey),
signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
});
if (res.ok) return { valid: true };
diff --git a/src/core/guides/types.ts b/src/core/guides/types.ts
index a5e0950..4c85e8f 100644
--- a/src/core/guides/types.ts
+++ b/src/core/guides/types.ts
@@ -59,8 +59,9 @@ export interface Screenshot {
export interface Settings {
aiApiKey: string;
- aiProvider: 'openai' | 'anthropic';
+ aiProvider: 'openai' | 'anthropic' | 'openaiCompatible';
aiModel: string;
+ aiBaseUrl?: string;
voiceEnabled: boolean;
voiceProvider: VoiceProvider;
voiceApiKey: string;
diff --git a/src/entrypoints/background/__tests__/guide-meta.test.ts b/src/entrypoints/background/__tests__/guide-meta.test.ts
index 2c4eb59..895c422 100644
--- a/src/entrypoints/background/__tests__/guide-meta.test.ts
+++ b/src/entrypoints/background/__tests__/guide-meta.test.ts
@@ -101,6 +101,7 @@ describe('background guide-meta', () => {
'anthropic',
AI_PROVIDERS.anthropic.defaultModel,
'key',
+ undefined,
);
});
@@ -114,6 +115,7 @@ describe('background guide-meta', () => {
'openai',
AI_PROVIDERS.openai.defaultModel,
'key',
+ undefined,
);
});
});
diff --git a/src/entrypoints/background/ai-description.ts b/src/entrypoints/background/ai-description.ts
index 85fca81..2df13ed 100644
--- a/src/entrypoints/background/ai-description.ts
+++ b/src/entrypoints/background/ai-description.ts
@@ -3,11 +3,17 @@ import type { DOMContext } from '@/core/capture/dom/context';
import { localStorage } from '@/lib/browser-api';
export async function generateAiDescription(domContext: DOMContext): Promise<string | undefined> {
- const settings = await localStorage.get(['aiApiKey', 'aiProvider', 'aiModel']);
+ const settings = await localStorage.get(['aiApiKey', 'aiProvider', 'aiModel', 'aiBaseUrl']);
if (!settings.aiApiKey) return undefined;
const provider = (settings.aiProvider as string) || 'openai';
const model = (settings.aiModel as string) || 'gpt-4o-mini';
- const description = await getAIDescription(domContext, provider, model, settings.aiApiKey as string);
+ const description = await getAIDescription(
+ domContext,
+ provider,
+ model,
+ settings.aiApiKey as string,
+ settings.aiBaseUrl as string | undefined,
+ );
return description || undefined;
}
diff --git a/src/entrypoints/background/guide-meta.ts b/src/entrypoints/background/guide-meta.ts
index b03eae9..edfce89 100644
--- a/src/entrypoints/background/guide-meta.ts
+++ b/src/entrypoints/background/guide-meta.ts
@@ -18,11 +18,18 @@ 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 }
+ | {
+ 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 settings = await localStorage.get(['aiApiKey', 'aiProvider', 'aiModel']);
+ const settings = await localStorage.get(['aiApiKey', 'aiProvider', 'aiModel', 'aiBaseUrl']);
if (!settings.aiApiKey) return { ok: false, reason: 'no-api-key' };
const steps = actionSteps(await getStepsForGuide(guideId));
@@ -36,6 +43,7 @@ async function resolveGuideMetaInputs(guideId: string): Promise<GuideMetaInputs>
provider,
model: (settings.aiModel as string) || AI_PROVIDERS[provider].defaultModel,
apiKey: settings.aiApiKey as string,
+ baseUrl: settings.aiBaseUrl as string | undefined,
};
}
@@ -63,7 +71,7 @@ export async function generateGuideMetaOnStop(guideId: string) {
return;
}
- const meta = await generateGuideMeta(inputs.steps, inputs.provider, inputs.model, inputs.apiKey);
+ const meta = await generateGuideMeta(inputs.steps, inputs.provider, inputs.model, inputs.apiKey, inputs.baseUrl);
if (!meta) {
await applyFallbackTitle(guideId);
return;
@@ -87,7 +95,7 @@ export async function generateDescriptionOnDemand(guideId: string): Promise<Gene
const inputs = await resolveGuideMetaInputs(guideId);
if (!inputs.ok) return { error: inputs.reason };
- const meta = await generateGuideMeta(inputs.steps, inputs.provider, inputs.model, inputs.apiKey);
+ 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);
diff --git a/src/entrypoints/background/index.ts b/src/entrypoints/background/index.ts
index c28016d..319cd52 100644
--- a/src/entrypoints/background/index.ts
+++ b/src/entrypoints/background/index.ts
@@ -184,7 +184,7 @@ export default defineBackground(() => {
onMessage('generateGuideDescription', ({ data }) => generateDescriptionOnDemand(data.guideId));
- onMessage('validateApiKey', ({ data }) => validateApiKey(data.provider, data.apiKey));
+ onMessage('validateApiKey', ({ data }) => validateApiKey(data.provider, data.apiKey, data.baseUrl));
onMessage('rewriteSelection', ({ data }) => rewriteSelection(data.text, data.instruction));
diff --git a/src/lib/messaging.ts b/src/lib/messaging.ts
index 6600c5b..c930784 100644
--- a/src/lib/messaging.ts
+++ b/src/lib/messaging.ts
@@ -110,6 +110,7 @@ export interface RewriteSelectionResponse {
export interface ValidateApiKeyData {
provider: string;
apiKey: string;
+ baseUrl?: string;
}
export interface ValidateApiKeyResponse {
diff --git a/src/locales/de.yml b/src/locales/de.yml
index c5468ee..a244f1e 100644
--- a/src/locales/de.yml
+++ b/src/locales/de.yml
@@ -97,6 +97,7 @@ settings:
title: Einstellungen
aiDescriptions: KI-Beschreibungen
modelCustom: Eigenes Modell
+ baseUrl: Basis-URL
provider: Anbieter
model: Modell
apiKey: API-SchlΓΌssel
diff --git a/src/locales/en.yml b/src/locales/en.yml
index f785866..d44d39a 100644
--- a/src/locales/en.yml
+++ b/src/locales/en.yml
@@ -87,6 +87,7 @@ settings:
provider: Provider
model: Model
modelCustom: Custom model
+ baseUrl: Base URL
apiKey: API Key
aiLanguage: Description Language
voiceNarration: Voice Narration
diff --git a/src/locales/es.yml b/src/locales/es.yml
index e3dfaa3..a373a2e 100644
--- a/src/locales/es.yml
+++ b/src/locales/es.yml
@@ -87,6 +87,7 @@ settings:
provider: Proveedor
model: Modelo
modelCustom: Modelo personalizado
+ baseUrl: URL base
apiKey: Clave API
aiLanguage: Idioma de descripciones
voiceNarration: "NarraciΓ³n por voz"
diff --git a/src/locales/fr.yml b/src/locales/fr.yml
index 9606a5c..c947397 100644
--- a/src/locales/fr.yml
+++ b/src/locales/fr.yml
@@ -87,6 +87,7 @@ settings:
provider: Fournisseur
model: "Modèle"
modelCustom: Modèle personnalisé
+ baseUrl: URL de base
apiKey: "ClΓ© API"
aiLanguage: Langue des descriptions
voiceNarration: "Narration vocale"
diff --git a/src/locales/pt-BR.yml b/src/locales/pt-BR.yml
index 469287e..c287609 100644
--- a/src/locales/pt-BR.yml
+++ b/src/locales/pt-BR.yml
@@ -87,6 +87,7 @@ settings:
provider: Provedor
model: Modelo
modelCustom: Modelo personalizado
+ baseUrl: URL base
apiKey: Chave da API
aiLanguage: "Idioma das descriΓ§Γ΅es"
voiceNarration: "NarraΓ§Γ£o por voz"
diff --git a/src/ui/onboarding/App.tsx b/src/ui/onboarding/App.tsx
index 235152b..ebd5263 100644
--- a/src/ui/onboarding/App.tsx
+++ b/src/ui/onboarding/App.tsx
@@ -1,4 +1,4 @@
-import { Mic, MousePointerClick, Shield } from 'lucide-react';
+import { Globe, Mic, MousePointerClick, Shield } from 'lucide-react';
import { useEffect, useState } from 'react';
import { browser, i18n } from '#imports';
import { PRESET_LABELS, type PresetKey } from '@/core/blur/regexes';
@@ -118,16 +118,18 @@ function AISetupStep({ onNext, onSkip, onBack, index, total }: StepProps) {
const [provider, setProvider] = useState<AIProviderKey>('openai');
const [model, setModel] = useState(AI_PROVIDERS.openai.defaultModel);
const [apiKey, setApiKey] = useState('');
+ const [baseUrl, setBaseUrl] = useState('');
const [aiLanguage, setAiLanguage] = useState<AILanguageCode>('en');
useEffect(() => {
const load = () =>
- localStorage.get(['aiProvider', 'aiModel', 'aiApiKey', 'aiLanguage']).then((stored) => {
+ localStorage.get(['aiProvider', 'aiModel', 'aiApiKey', 'aiBaseUrl', 'aiLanguage']).then((stored) => {
if (typeof stored.aiProvider === 'string' && stored.aiProvider in AI_PROVIDERS) {
setProvider(stored.aiProvider as AIProviderKey);
}
if (typeof stored.aiModel === 'string') setModel(stored.aiModel);
if (typeof stored.aiApiKey === 'string') setApiKey(stored.aiApiKey);
+ if (typeof stored.aiBaseUrl === 'string') setBaseUrl(stored.aiBaseUrl);
if (typeof stored.aiLanguage === 'string') setAiLanguage(stored.aiLanguage as AILanguageCode);
});
@@ -158,6 +160,11 @@ function AISetupStep({ onNext, onSkip, onBack, index, total }: StepProps) {
void localStorage.set({ aiApiKey: nextKey });
};
+ const handleBaseUrlChange = (nextUrl: string) => {
+ setBaseUrl(nextUrl);
+ void localStorage.set({ aiBaseUrl: nextUrl });
+ };
+
const handleLanguageChange = (nextLanguage: AILanguageCode) => {
setAiLanguage(nextLanguage);
void localStorage.set({ aiLanguage: nextLanguage });
@@ -194,20 +201,46 @@ function AISetupStep({ onNext, onSkip, onBack, index, total }: StepProps) {
<div>
<label className="block text-xs font-semibold text-foreground mb-1.5">{i18n.t('settings.model')}</label>
- <Select value={model} onValueChange={handleModelChange}>
- <SelectTrigger className="w-full rounded-xl px-4 py-2.5 text-sm focus:border-accent focus:ring-accent/10">
- <SelectValue />
- </SelectTrigger>
- <SelectContent>
- {providerConfig.models.map((m) => (
- <SelectItem key={m.id} value={m.id}>
- {m.label}
- </SelectItem>
- ))}
- </SelectContent>
- </Select>
+ {providerConfig.baseUrl ? (
+ <Input
+ type="text"
+ value={model}
+ onChange={(e) => handleModelChange(e.target.value)}
+ placeholder={providerConfig.defaultModel}
+ className="w-full rounded-xl px-4 py-2.5 text-sm focus:border-accent focus:ring-accent/10"
+ />
+ ) : (
+ <Select value={model} onValueChange={handleModelChange}>
+ <SelectTrigger className="w-full rounded-xl px-4 py-2.5 text-sm focus:border-accent focus:ring-accent/10">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {providerConfig.models.map((m) => (
+ <SelectItem key={m.id} value={m.id}>
+ {m.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )}
</div>
+ {providerConfig.baseUrl && (
+ <div>
+ <label className="block text-xs font-semibold text-foreground mb-1.5">
+ <Globe size={11} className="inline mr-1 -mt-px" />
+ {i18n.t('settings.baseUrl')}
+ </label>
+ <Input
+ type="text"
+ value={baseUrl}
+ onChange={(e) => handleBaseUrlChange(e.target.value)}
+ placeholder="https://api.example.com/v1"
+ className="w-full rounded-xl px-4 py-2.5 text-sm focus:border-accent focus:ring-accent/10"
+ />
+ </div>
+ )}
+
<div>
<label className="block text-xs font-semibold text-foreground mb-1.5">{i18n.t('settings.apiKey')}</label>
<Input
diff --git a/src/ui/shared/SettingsView.tsx b/src/ui/shared/SettingsView.tsx
index ffa7b34..0329038 100644
--- a/src/ui/shared/SettingsView.tsx
+++ b/src/ui/shared/SettingsView.tsx
@@ -48,14 +48,14 @@ function useKeyCheck() {
const [status, setStatus] = useState<KeyStatus>(null);
const validated = useRef('');
- const check = useCallback(async (provider: string, apiKey: string) => {
- const fingerprint = `${provider}:${apiKey}`;
+ const check = useCallback(async (provider: string, apiKey: string, baseUrl?: string) => {
+ const fingerprint = `${provider}:${apiKey}:${baseUrl ?? ''}`;
if (validated.current === fingerprint) {
setStatus('valid');
return;
}
setStatus('checking');
- const result = await sendMessage('validateApiKey', { provider, apiKey }).catch(() => null);
+ const result = await sendMessage('validateApiKey', { provider, apiKey, baseUrl }).catch(() => null);
if (result?.valid) validated.current = fingerprint;
setStatus(result?.valid ? 'valid' : result?.reason === 'rejected' ? 'rejected' : 'unreachable');
}, []);
@@ -98,6 +98,7 @@ export default function SettingsView({ onBack }: SettingsViewProps) {
const [provider, setProvider] = useState<AIProviderKey>('openai');
const [model, setModel] = useState(AI_PROVIDERS.openai.defaultModel);
const [apiKey, setApiKey] = useState('');
+ const [baseUrl, setBaseUrl] = useState('');
const [saved, setSaved] = useState(false);
const aiKeyCheck = useKeyCheck();
const voiceKeyCheck = useKeyCheck();
@@ -130,6 +131,7 @@ export default function SettingsView({ onBack }: SettingsViewProps) {
'aiApiKey',
'aiProvider',
'aiModel',
+ 'aiBaseUrl',
'aiLanguage',
'blurPresets',
'voiceProvider',
@@ -145,6 +147,7 @@ export default function SettingsView({ onBack }: SettingsViewProps) {
setProvider(p);
setModel((result.aiModel as string) || AI_PROVIDERS[p].defaultModel);
if (result.aiApiKey) setApiKey(result.aiApiKey as string);
+ if (result.aiBaseUrl) setBaseUrl(result.aiBaseUrl as string);
if (result.aiLanguage) setAiLanguage(result.aiLanguage as AILanguageCode);
if (result.blurPresets) setBlurPresets(result.blurPresets as Record<PresetKey, boolean>);
setVoiceProvider((result.voiceProvider as VoiceProvider) || 'openai');
@@ -162,6 +165,7 @@ export default function SettingsView({ onBack }: SettingsViewProps) {
aiApiKey: apiKey,
aiProvider: provider,
aiModel: model,
+ aiBaseUrl: baseUrl,
aiLanguage,
blurPresets,
voiceProvider,
@@ -329,6 +333,26 @@ export default function SettingsView({ onBack }: SettingsViewProps) {
)}
</div>
+ {providerConfig.baseUrl && (
+ <div>
+ <label className="block text-[11px] font-semibold text-foreground mb-1">
+ <Globe size={11} className="inline mr-1 -mt-px" />
+ {i18n.t('settings.baseUrl')}
+ </label>
+ <Input
+ type="text"
+ value={baseUrl}
+ onChange={(e) => {
+ setBaseUrl(e.target.value);
+ aiKeyCheck.setStatus(null);
+ }}
+ placeholder="https://api.example.com/v1"
+ aria-label={i18n.t('settings.baseUrl')}
+ className="h-8 text-[12px] rounded-lg border-border"
+ />
+ </div>
+ )}
+
<div>
<label className="block text-[11px] font-semibold text-foreground mb-1">{i18n.t('settings.apiKey')}</label>
<div className="flex items-center gap-1.5">
@@ -346,7 +370,7 @@ export default function SettingsView({ onBack }: SettingsViewProps) {
variant="outline"
size="sm"
disabled={!apiKey || aiKeyCheck.status === 'checking'}
- onClick={() => void aiKeyCheck.check(provider, apiKey)}
+ onClick={() => void aiKeyCheck.check(provider, apiKey, baseUrl)}
className="h-8 shrink-0 rounded-lg bg-card text-[11px] font-semibold"
>
{i18n.t('settings.checkKey')}