π¬ 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: centralize browser APIs and typed messaging
Luis Ortiz1df57f99d6c4
diff --git a/package-lock.json b/package-lock.jsonindex 57daf0a..7908b1c 100644--- a/package-lock.json+++ b/package-lock.json@@ -11,6 +11,7 @@"dependencies": {"@anthropic-ai/sdk": "^0.80.0","@tailwindcss/vite": "^4.2.2",+ "@webext-core/messaging": "^2.3.0","@wxt-dev/module-react": "^1.2.2","@xstate/react": "^6.1.0","clsx": "^2.1.1",@@ -985,6 +986,15 @@"@jridgewell/sourcemap-codec": "^1.4.14"}},+ "node_modules/@lukeed/csprng": {+ "version": "1.1.0",+ "resolved": "https://registry.npmjs.org/@lukeed/csprng/-/csprng-1.1.0.tgz",+ "integrity": "sha512-Z7C/xXCiGWsg0KuKsHTKJxbWhpI3Vs5GwLfOean7MGyVFGqdRgBbAjOCh6u4bbjPc/8MJ2pZmK/0DLdCbivLDA==",+ "license": "MIT",+ "engines": {+ "node": ">=8"+ }+ },"node_modules/@napi-rs/wasm-runtime": {"version": "1.1.1","resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.1.tgz",@@ -1940,6 +1950,17 @@"integrity": "sha512-NY39ACqCxdKBmHgw361M9pfJma8e4AZo20w9AY+5ZjIj1W2dvXC8J31G5fjfOGbulW9w4WKpT8fPooi0mLkn9A==","license": "MIT"},+ "node_modules/@webext-core/messaging": {+ "version": "2.3.0",+ "resolved": "https://registry.npmjs.org/@webext-core/messaging/-/messaging-2.3.0.tgz",+ "integrity": "sha512-gChSVKdRs7JEq5hFH0jVROSvTq+sKq9afXTA/gBswep3RWNLhXyDsXFlvPMkYbmML1XZ8QKKC9ou2MlCKRZwSQ==",+ "license": "MIT",+ "dependencies": {+ "serialize-error": "^11.0.0",+ "uid": "^2.0.2",+ "webextension-polyfill": "^0.10.0"+ }+ },"node_modules/@wxt-dev/browser": {"version": "0.1.38","resolved": "https://registry.npmjs.org/@wxt-dev/browser/-/browser-0.1.38.tgz",@@ -5863,6 +5884,33 @@"node": ">=10"}},+ "node_modules/serialize-error": {+ "version": "11.0.3",+ "resolved": "https://registry.npmjs.org/serialize-error/-/serialize-error-11.0.3.tgz",+ "integrity": "sha512-2G2y++21dhj2R7iHAdd0FIzjGwuKZld+7Pl/bTU6YIkrC2ZMbVUjm+luj6A6V34Rv9XfKJDKpTWu9W4Gse1D9g==",+ "license": "MIT",+ "dependencies": {+ "type-fest": "^2.12.2"+ },+ "engines": {+ "node": ">=14.16"+ },+ "funding": {+ "url": "https://github.com/sponsors/sindresorhus"+ }+ },+ "node_modules/serialize-error/node_modules/type-fest": {+ "version": "2.19.0",+ "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-2.19.0.tgz",+ "integrity": "sha512-RAH822pAdBgcNMAfWnCBU3CFZcfZ/i1eZjwFU/dsLKumyuuP3niueg2UAukXYF0E2AAoc82ZSSf9J0WQBinzHA==",+ "license": "(MIT OR CC0-1.0)",+ "engines": {+ "node": ">=12.20"+ },+ "funding": {+ "url": "https://github.com/sponsors/sindresorhus"+ }+ },"node_modules/set-value": {"version": "4.1.0","resolved": "https://registry.npmjs.org/set-value/-/set-value-4.1.0.tgz",@@ -6376,6 +6424,18 @@"integrity": "sha512-qz3o9CHXmJJPGBdqzab7qAYuW8kQGKNEuoHFYrBwV6hWIMcpAmxDLXojcHfFr9US1Pe6zUswEIJIbLI610fuqA==","license": "ISC"},+ "node_modules/uid": {+ "version": "2.0.2",+ "resolved": "https://registry.npmjs.org/uid/-/uid-2.0.2.tgz",+ "integrity": "sha512-u3xV3X7uzvi5b1MncmZo3i2Aw222Zk1keqLA1YkHldREkAhAqi65wuPfe7lHx8H/Wzy+8CE7S7uS3jekIM5s8g==",+ "license": "MIT",+ "dependencies": {+ "@lukeed/csprng": "^1.0.0"+ },+ "engines": {+ "node": ">=8"+ }+ },"node_modules/undici": {"version": "7.24.5","resolved": "https://registry.npmjs.org/undici/-/undici-7.24.5.tgz",@@ -6767,6 +6827,12 @@"npm": ">=8.0.0"}},+ "node_modules/webextension-polyfill": {+ "version": "0.10.0",+ "resolved": "https://registry.npmjs.org/webextension-polyfill/-/webextension-polyfill-0.10.0.tgz",+ "integrity": "sha512-c5s35LgVa5tFaHhrZDnr3FpQpjj1BB+RXhLTYUxGqBVN460HkbM8TBtEqdXWbpTKfzwCcjAZVF7zXCYSKtcp9g==",+ "license": "MPL-2.0"+ },"node_modules/webidl-conversions": {"version": "8.0.1","resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz",diff --git a/package.json b/package.jsonindex e0c5361..61be644 100644--- a/package.json+++ b/package.json@@ -12,6 +12,7 @@"dependencies": {"@anthropic-ai/sdk": "^0.80.0","@tailwindcss/vite": "^4.2.2",+ "@webext-core/messaging": "^2.3.0","@wxt-dev/module-react": "^1.2.2","@xstate/react": "^6.1.0","clsx": "^2.1.1",diff --git a/src/lib/browser-api.ts b/src/lib/browser-api.tsnew file mode 100644index 0000000..de9b27a--- /dev/null+++ b/src/lib/browser-api.ts@@ -0,0 +1,157 @@+import { browser, Browser } from "#imports";+import type { PublicPath } from "wxt/browser";++type HtmlPublicPath = Extract<PublicPath, `${string}.html`>;+type ScriptPath = Extract<PublicPath, `${string}.js`>;++export function sendMessage(msg: Record<string, unknown>): Promise<unknown> {+ return browser.runtime.sendMessage(msg);+}++export function sendMessageWithCallback(+ msg: Record<string, unknown>,+ callback: (response: unknown) => void,+): void {+ browser.runtime.sendMessage(msg, callback);+}++export function sendMessageToTab(+ tabId: number,+ msg: Record<string, unknown>,+): Promise<unknown> {+ return browser.tabs.sendMessage(tabId, msg);+}++export function onMessage(+ handler: (+ msg: unknown,+ sender: Browser.runtime.MessageSender,+ sendResponse: (response?: unknown) => void,+ ) => boolean | void,+): void {+ browser.runtime.onMessage.addListener(handler);+}++export function offMessage(handler: (...args: unknown[]) => unknown): void {+ browser.runtime.onMessage.removeListener(handler);+}++export function getLastError(): Browser.runtime.LastError | undefined {+ return browser.runtime.lastError;+}++export function getExtensionURL(path: PublicPath): string;+export function getExtensionURL(path: `${HtmlPublicPath}${string}`): string;+export function getExtensionURL(path: string): string {+ return (browser.runtime as { getURL(p: string): string }).getURL(path);+}++export function getExtensionId(): string {+ return browser.runtime.id;+}++export function queryTabs(+ query: Browser.tabs.QueryInfo,+): Promise<Browser.tabs.Tab[]> {+ return browser.tabs.query(query);+}++export async function getActiveTab(): Promise<Browser.tabs.Tab | undefined> {+ const tabs = await browser.tabs.query({+ active: true,+ lastFocusedWindow: true,+ });+ return tabs[0];+}++export function getTab(tabId: number): Promise<Browser.tabs.Tab> {+ return browser.tabs.get(tabId);+}++export function createTab(+ options: Browser.tabs.CreateProperties,+): Promise<Browser.tabs.Tab> {+ return browser.tabs.create(options);+}++export function updateTab(+ tabId: number,+ props: Browser.tabs.UpdateProperties,+): Promise<Browser.tabs.Tab | undefined> {+ return browser.tabs.update(tabId, props);+}++export function onTabActivated(+ handler: (activeInfo: Browser.tabs.OnActivatedInfo) => void,+): void {+ browser.tabs.onActivated.addListener(handler);+}++export function onTabUpdated(+ handler: (+ tabId: number,+ changeInfo: Browser.tabs.OnUpdatedInfo,+ tab: Browser.tabs.Tab,+ ) => void,+): void {+ browser.tabs.onUpdated.addListener(handler);+}++export function getAllWindows(): Promise<Browser.windows.Window[]> {+ return browser.windows.getAll({ populate: true });+}++export function focusWindow(windowId: number): Promise<Browser.windows.Window> {+ return browser.windows.update(windowId, { focused: true });+}++export function captureVisibleTab(+ format: "jpeg" | "png" = "jpeg",+ quality = 90,+): Promise<string> {+ return browser.tabs.captureVisibleTab({ format, quality });+}++export function executeScript(+ tabId: number,+ files: ScriptPath[],+ allFrames = true,+): Promise<unknown> {+ return browser.scripting.executeScript({+ target: { tabId, allFrames },+ files,+ });+}++export const sessionStorage = {+ get: (key: string) => browser.storage.session.get(key),+ set: (items: Record<string, unknown>) => browser.storage.session.set(items),+ remove: (key: string) => browser.storage.session.remove(key),+};++export const localStorage = {+ get: (keys: string[]) => browser.storage.local.get(keys),+ set: (items: Record<string, unknown>) => browser.storage.local.set(items),+};++export function setSidePanelBehavior(openOnActionClick: boolean): void {+ browser.sidePanel.setPanelBehavior({+ openPanelOnActionClick: openOnActionClick,+ });+}++export function onNavigationCompleted(+ handler: (+ details: Browser.webNavigation.WebNavigationFramedCallbackDetails,+ ) => void,+): void {+ browser.webNavigation.onCompleted.addListener(handler);+}++export function onHistoryStateUpdated(+ handler: (+ details: Browser.webNavigation.WebNavigationTransitionCallbackDetails,+ ) => void,+): void {+ browser.webNavigation.onHistoryStateUpdated.addListener(handler);+}diff --git a/src/lib/messaging.ts b/src/lib/messaging.tsnew file mode 100644index 0000000..cd5b2e9--- /dev/null+++ b/src/lib/messaging.ts@@ -0,0 +1,29 @@+import { defineExtensionMessaging } from '@webext-core/messaging';+import type { ElementMeta } from '@/guides/types';++interface MimikProtocol {+ ping(): { alive: boolean };++ getState(): {+ state: string;+ stepCount: number;+ currentGuideId: string | null;+ };++ startRecording(data: { url: string }): { guideId: string };+ stopRecording(): { success: boolean; guideId?: string };++ userAction(data: {+ guideId: string;+ action: string;+ elementMeta: ElementMeta;+ }): { stepId: string } | { ignored: true } | { error: string };++ rrwebChunk(data: {+ guideId: string;+ events: unknown[];+ timestamp: number;+ }): { stored: boolean };+}++export const { sendMessage, onMessage } = defineExtensionMessaging<MimikProtocol>();diff --git a/src/options/App.tsx b/src/options/App.tsxindex 0143365..74bb639 100644--- a/src/options/App.tsx+++ b/src/options/App.tsx@@ -1,4 +1,5 @@import { useState, useEffect } from 'react';+import { localStorage } from '@/lib/browser-api';export default function App() {const [apiKey, setApiKey] = useState('');@@ -6,14 +7,14 @@ export default function App() {const [saved, setSaved] = useState(false);useEffect(() => {- chrome.storage.local.get(['aiApiKey', 'aiProvider']).then((result) => {- if (result.aiApiKey) setApiKey(result.aiApiKey);- if (result.aiProvider) setProvider(result.aiProvider);+ localStorage.get(['aiApiKey', 'aiProvider']).then((result) => {+ if (result.aiApiKey) setApiKey(result.aiApiKey as string);+ if (result.aiProvider) setProvider(result.aiProvider as 'openai' | 'anthropic');});}, []);const handleSave = async () => {- await chrome.storage.local.set({ aiApiKey: apiKey, aiProvider: provider });+ await localStorage.set({ aiApiKey: apiKey, aiProvider: provider });setSaved(true);setTimeout(() => setSaved(false), 2000);};diff --git a/src/sidepanel/App.tsx b/src/sidepanel/App.tsxindex dac65e6..fd35c5d 100644--- a/src/sidepanel/App.tsx+++ b/src/sidepanel/App.tsx@@ -1,5 +1,7 @@import { useState, useEffect, useCallback } from 'react';import { Video, Search } from 'lucide-react';+import { sendMessage } from '@/lib/messaging';+import { getActiveTab } from '@/lib/browser-api';import LibraryView from './LibraryView';import GuideEditor from './GuideEditor';import RecordingView from './RecordingView';@@ -39,60 +41,58 @@ export default function App() {const [search, setSearch] = useState('');useEffect(() => {- chrome.runtime.sendMessage({ type: 'PING' }, (response) => {- if (response?.alive) setIsAlive(true);- });+ sendMessage('ping', undefined).then(res => {+ if (res.alive) setIsAlive(true);+ }).catch(() => {});const interval = setInterval(() => {- chrome.runtime.sendMessage({ type: 'GET_STATE' }, (response) => {- if (chrome.runtime.lastError) return;- if (response?.state === 'recording') {+ sendMessage('getState', undefined).then(res => {+ if (res.state === 'recording') {setIsRecording(true);- if (response.currentGuideId) {+ if (res.currentGuideId) {setView(prev => {if (prev.name === 'recording') return prev;- return { name: 'recording', guideId: response.currentGuideId };+ return { name: 'recording', guideId: res.currentGuideId! };});}} else {setIsRecording(false);}- });+ }).catch(() => {});}, 1000);return () => clearInterval(interval);}, []);const handleStartRecording = useCallback(async () => {- const tabs = await chrome.tabs.query({ active: true, lastFocusedWindow: true });- const url = tabs[0]?.url || '';-- chrome.runtime.sendMessage(- { type: 'START_RECORDING', url },- (response) => {- if (chrome.runtime.lastError) {- console.error('[Mimik] START_RECORDING error', chrome.runtime.lastError);- return;- }- if (response?.guideId) {- setIsRecording(true);- setView({ name: 'recording', guideId: response.guideId });- }+ const tab = await getActiveTab();+ const url = tab?.url || '';++ try {+ const res = await sendMessage('startRecording', { url });+ if (res.guideId) {+ setIsRecording(true);+ setView({ name: 'recording', guideId: res.guideId });}- );+ } catch (err) {+ console.error('[Mimik] START_RECORDING error', err);+ }}, []);- const handleStopRecording = useCallback(() => {- chrome.runtime.sendMessage({ type: 'STOP_RECORDING' }, (response) => {- if (response?.success) {+ const handleStopRecording = useCallback(async () => {+ try {+ const res = await sendMessage('stopRecording', undefined);+ if (res.success) {setIsRecording(false);- if (response.guideId) {- setView({ name: 'editor', guideId: response.guideId });+ if (res.guideId) {+ setView({ name: 'editor', guideId: res.guideId });} else {setView({ name: 'library' });}}- });+ } catch (err) {+ console.error('[Mimik] STOP_RECORDING error', err);+ }}, []);if (view.name === 'recording') {diff --git a/src/sidepanel/GuideEditor.tsx b/src/sidepanel/GuideEditor.tsxindex 9c0fe22..1dfc0ce 100644--- a/src/sidepanel/GuideEditor.tsx+++ b/src/sidepanel/GuideEditor.tsx@@ -1,7 +1,8 @@import { useState, useEffect, useCallback } from 'react';import { ArrowLeft, Maximize2 } from 'lucide-react';-import { getGuide, updateGuideTitle, updateStepDescription, deleteStep, reorderSteps, updateScreenshotBlob } from '../shared/guide-service';-import type { Guide, Step, Screenshot } from '../shared/types';+import { getExtensionURL, queryTabs, updateTab, focusWindow, createTab } from '@/lib/browser-api';+import { getGuide, updateGuideTitle, updateStepDescription, deleteStep, reorderSteps, updateScreenshotBlob } from '@/guides/service';+import type { Guide, Step, Screenshot } from '@/guides/types';import StepCard from './StepCard';import BlurCanvas from './BlurCanvas';import ExportMenu from './ExportMenu';@@ -130,13 +131,13 @@ export default function GuideEditor({ guideId, onBack }: GuideEditorProps) {/><buttononClick={() => {- const url = chrome.runtime.getURL(`/fullview.html?guideId=${guideId}`);- chrome.tabs.query({ url: chrome.runtime.getURL('/fullview.html*') }).then(tabs => {+ const url = getExtensionURL(`/fullview.html?guideId=${guideId}`);+ queryTabs({ url: getExtensionURL('/fullview.html') }).then(tabs => {if (tabs.length > 0 && tabs[0].id) {- chrome.tabs.update(tabs[0].id, { active: true, url: chrome.runtime.getURL(`/fullview.html?guideId=${guideId}`) });- if (tabs[0].windowId) chrome.windows.update(tabs[0].windowId, { focused: true });+ updateTab(tabs[0].id, { active: true, url: getExtensionURL(`/fullview.html?guideId=${guideId}`) });+ if (tabs[0].windowId) focusWindow(tabs[0].windowId);} else {- chrome.tabs.create({ url });+ createTab({ url });}});}}diff --git a/src/sidepanel/LibraryView.tsx b/src/sidepanel/LibraryView.tsxindex 3c453d2..9d76d70 100644--- a/src/sidepanel/LibraryView.tsx+++ b/src/sidepanel/LibraryView.tsx@@ -1,7 +1,7 @@import { useState, useEffect, useCallback } from 'react';import { Trash2, FileText } from 'lucide-react';-import { getGuides, softDeleteGuide, getFirstStepUrl } from '../shared/guide-service';-import type { Guide } from '../shared/types';+import { getGuides, softDeleteGuide, getFirstStepUrl } from '@/guides/service';+import type { Guide } from '@/guides/types';function formatRelativeTime(timestamp: number): string {const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });diff --git a/src/sidepanel/RecordingView.tsx b/src/sidepanel/RecordingView.tsxindex e0c683f..2c6c2f5 100644--- a/src/sidepanel/RecordingView.tsx+++ b/src/sidepanel/RecordingView.tsx@@ -1,7 +1,8 @@import { useState, useEffect, useCallback, useRef } from 'react';import { Check, Trash2, Square } from 'lucide-react';-import { db } from '../shared/db-schema';-import type { Step, Screenshot } from '../shared/types';+import { getActiveTab } from '@/lib/browser-api';+import { db } from '@/guides/db';+import type { Step, Screenshot } from '@/guides/types';import ZoomScreenshot from './ZoomScreenshot';interface RecordingViewProps {@@ -86,8 +87,8 @@ export default function RecordingView({ guideId, onStop }: RecordingViewProps) {}, [steps.length]);useEffect(() => {- chrome.tabs.query({ active: true, lastFocusedWindow: true }, (tabs) => {- if (tabs[0]?.url) setSiteUrl(tabs[0].url);+ getActiveTab().then(tab => {+ if (tab?.url) setSiteUrl(tab.url);});}, []);