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 πŸ“–

refactor: persistent port connection and typed state sync

Luis Ortiz540edafffe01
diff --git a/src/entrypoints/background/index.ts b/src/entrypoints/background/index.ts
index 8efd05e..882bebd 100644
--- a/src/entrypoints/background/index.ts
+++ b/src/entrypoints/background/index.ts
@@ -1,69 +1,82 @@
-import { defineBackground } from '#imports';
-import { setSidePanelBehavior } from '@/lib/browser-api';
-import { onMessage } from '@/lib/messaging';
-import { db } from '@/guides/db';
-import { initActor, initActorFallback, getActor, ready } from './actor';
-import { injectAllTabs, broadcastStartCapture, broadcastStopCapture } from './tab-manager';
-import { handleUserAction } from './step-pipeline';
-import { registerNavigationListeners } from './navigation';
+import { defineBackground } from "#imports";
+import { logger } from "@/lib/logger";
+import { setSidePanelBehavior } from "@/lib/browser-api";
+import { onMessage } from "@/lib/messaging";
+import { setupPortListener, broadcastStateToPanel } from "@/lib/port";
+import { createGuide, saveRrwebChunk } from "@/guides/service";
+import {
+ initActor,
+ initActorFallback,
+ getActor,
+ getStateUpdate,
+ waitUntilReady,
+} from "./actor";
+import { broadcastStartCapture, broadcastStopCapture } from "./tab-manager";
+import { handleUserAction } from "./step-pipeline";
+import { registerNavigationListeners } from "./navigation";
export default defineBackground(() => {
- setSidePanelBehavior(true);
+ logger.info("Background service worker started");
+ setSidePanelBehavior(true);
initActor().catch(initActorFallback);
- injectAllTabs();
registerNavigationListeners();
- onMessage('ping', () => {
- return { alive: true };
+ setupPortListener((port) => {
+ logger.debug("Panel connected via port");
+ waitUntilReady().then(() => {
+ try {
+ port.postMessage(getStateUpdate());
+ } catch {
+ /* disconnected */
+ }
+ });
+ });
+
+ waitUntilReady().then(() => {
+ getActor().subscribe(() => broadcastStateToPanel(getStateUpdate()));
});
- onMessage('getState', async () => {
- await ready;
- const snap = getActor().getSnapshot();
- return {
- state: (snap.value as string) ?? 'unknown',
- stepCount: snap.context.stepCount,
- currentGuideId: snap.context.currentGuideId,
- };
+ onMessage("getState", async () => {
+ await waitUntilReady();
+ const update = getStateUpdate();
+ logger.debug("getState β†’", update.state);
+ return update;
});
- onMessage('startRecording', async ({ data }) => {
- await ready;
+ onMessage("startRecording", async ({ data }) => {
+ logger.info("startRecording β†’", data.url);
+ await waitUntilReady();
const actor = getActor();
- actor.send({ type: 'START_RECORDING', url: data.url });
+ actor.send({ type: "START_RECORDING", url: data.url });
const guideId = actor.getSnapshot().context.currentGuideId!;
- await db.guides.add({
- id: guideId,
- title: 'Untitled Guide',
- createdAt: Date.now(),
- updatedAt: Date.now(),
- stepIds: [],
- starred: false,
- deletedAt: null,
- });
+ await createGuide(guideId);
await broadcastStartCapture(guideId);
+ logger.info("Recording started β†’ guideId:", guideId);
return { guideId };
});
- onMessage('stopRecording', async () => {
- await ready;
+ onMessage("stopRecording", async () => {
+ await waitUntilReady();
const actor = getActor();
const guideId = actor.getSnapshot().context.currentGuideId;
+ logger.info("stopRecording β†’ guideId:", guideId);
await broadcastStopCapture();
- actor.send({ type: 'STOP_RECORDING' });
+ actor.send({ type: "STOP_RECORDING" });
return { success: true, guideId: guideId ?? undefined };
});
- onMessage('userAction', async (message) => {
- await ready;
+ onMessage("userAction", async (message) => {
+ await waitUntilReady();
+ logger.debug("userAction β†’", message.data.action);
return handleUserAction(message.data, message.sender);
});
- onMessage('rrwebChunk', async ({ data }) => {
- await db.rrwebEvents.add({
+ onMessage("rrwebChunk", async ({ data }) => {
+ logger.debug("rrwebChunk β†’", data.events.length, "events");
+ await saveRrwebChunk({
id: crypto.randomUUID(),
guideId: data.guideId,
events: data.events,
diff --git a/src/entrypoints/background/navigation.ts b/src/entrypoints/background/navigation.ts
index ce4ecac..1675d5a 100644
--- a/src/entrypoints/background/navigation.ts
+++ b/src/entrypoints/background/navigation.ts
@@ -1,35 +1,49 @@
-import { onNavigationCompleted, onHistoryStateUpdated, onTabActivated, onTabUpdated, sendMessageToTab, getTab } from '@/lib/browser-api';
-import { isInjectableTab, injectContentScript } from './tab-manager';
-import { getActor, ready } from './actor';
+import { logger } from "@/lib/logger";
+import {
+ onNavigationCompleted,
+ onHistoryStateUpdated,
+ onTabActivated,
+ onTabUpdated,
+ sendMessageToTab,
+ getTab,
+} from "@/lib/browser-api";
+import { TabMessage } from "@/lib/tab-messages";
+import { isInjectableTab, injectContentScript } from "./tab-manager";
+import { getActor, waitUntilReady } from "./actor";
+import { CaptureState } from "@/capture/machine";
export function registerNavigationListeners() {
onNavigationCompleted(async (details) => {
if (details.frameId !== 0) return;
- await ready;
+ await waitUntilReady();
const state = getActor().getSnapshot();
- if (state.value === 'recording') {
- getActor().send({ type: 'SPA_NAVIGATE', url: details.url });
+ if (state.value === CaptureState.RECORDING) {
+ logger.debug("URL changed (navigation) β†’", details.url);
+ getActor().send({ type: "URL_CHANGED", url: details.url });
}
});
onHistoryStateUpdated(async (details) => {
if (details.frameId !== 0) return;
- await ready;
+ await waitUntilReady();
const state = getActor().getSnapshot();
- if (state.value === 'recording') {
- getActor().send({ type: 'SPA_NAVIGATE', url: details.url });
+ if (state.value === CaptureState.RECORDING) {
+ logger.debug("URL changed (SPA pushState) β†’", details.url);
+ getActor().send({ type: "URL_CHANGED", url: details.url });
}
});
onTabActivated(async (activeInfo) => {
- await ready;
+ await waitUntilReady();
const state = getActor().getSnapshot();
- if (state.value !== 'recording') return;
+ if (state.value !== CaptureState.RECORDING) return;
if (!state.context.currentGuideId) return;
try {
- await sendMessageToTab(activeInfo.tabId, { type: 'PING' });
+ await sendMessageToTab(activeInfo.tabId, { type: TabMessage.PING });
+ logger.debug("Tab switched β†’ content script alive on tab", activeInfo.tabId);
} catch {
+ logger.debug("Tab switched β†’ injecting content script on tab", activeInfo.tabId);
try {
const tab = await getTab(activeInfo.tabId);
if (isInjectableTab(tab)) {
@@ -41,15 +55,16 @@ export function registerNavigationListeners() {
});
onTabUpdated(async (tabId, changeInfo, tab) => {
- if (changeInfo.status !== 'complete') return;
- await ready;
+ if (changeInfo.status !== "complete") return;
+ await waitUntilReady();
const state = getActor().getSnapshot();
- if (state.value !== 'recording') return;
+ if (state.value !== CaptureState.RECORDING) return;
if (!isInjectableTab(tab)) return;
try {
- await sendMessageToTab(tabId, { type: 'PING' });
+ await sendMessageToTab(tabId, { type: TabMessage.PING });
} catch {
+ logger.debug("Tab loaded β†’ injecting content script on tab", tabId);
try {
await injectContentScript(tabId);
} catch {
diff --git a/src/entrypoints/background/tab-manager.ts b/src/entrypoints/background/tab-manager.ts
index d2a87ac..460fdc8 100644
--- a/src/entrypoints/background/tab-manager.ts
+++ b/src/entrypoints/background/tab-manager.ts
@@ -1,4 +1,6 @@
-import { sendMessageToTab, executeScript, getAllWindows, queryTabs } from '@/lib/browser-api';
+import { logger } from '@/lib/logger';
+import { sendMessageToTab, executeScript, queryTabs } from '@/lib/browser-api';
+import { TabMessage } from '@/lib/tab-messages';
export function isInjectableTab(tab: { url?: string; pendingUrl?: string }): boolean {
const url = tab.url || tab.pendingUrl || '';
@@ -15,7 +17,7 @@ export function isInjectableTab(tab: { url?: string; pendingUrl?: string }): boo
export async function injectContentScript(tabId: number): Promise<void> {
try {
- await sendMessageToTab(tabId, { type: 'PING' });
+ await sendMessageToTab(tabId, { type: TabMessage.PING });
} catch {
try {
await executeScript(tabId, ['/content-scripts/content.js']);
@@ -24,31 +26,16 @@ export async function injectContentScript(tabId: number): Promise<void> {
}
}
-export async function injectAllTabs(): Promise<void> {
- try {
- const windows = await getAllWindows();
- for (const win of windows) {
- for (const tab of win.tabs || []) {
- if (tab.id && isInjectableTab(tab)) {
- injectContentScript(tab.id);
- }
- }
- }
- } catch (err) {
- console.warn('[Mimik] injectAllTabs failed', err);
- }
-}
-
export async function broadcastStartCapture(guideId: string): Promise<void> {
try {
const tabs = await queryTabs({});
for (const tab of tabs) {
if (tab.id && isInjectableTab(tab)) {
- sendMessageToTab(tab.id, { type: 'START_CAPTURE', guideId }).catch(() => {});
+ sendMessageToTab(tab.id, { type: TabMessage.START_CAPTURE, guideId }).catch(() => {});
}
}
} catch (err) {
- console.warn('[Mimik] broadcastStartCapture failed', err);
+ logger.warn(' broadcastStartCapture failed', err);
}
}
@@ -57,10 +44,10 @@ export async function broadcastStopCapture(): Promise<void> {
const tabs = await queryTabs({});
for (const tab of tabs) {
if (tab.id) {
- sendMessageToTab(tab.id, { type: 'STOP_CAPTURE' }).catch(() => {});
+ sendMessageToTab(tab.id, { type: TabMessage.STOP_CAPTURE }).catch(() => {});
}
}
} catch (err) {
- console.warn('[Mimik] broadcastStopCapture failed', err);
+ logger.warn(' broadcastStopCapture failed', err);
}
}
diff --git a/src/entrypoints/content.ts b/src/entrypoints/content.ts
index c1221c6..06fc036 100644
--- a/src/entrypoints/content.ts
+++ b/src/entrypoints/content.ts
@@ -1,6 +1,9 @@
+import { logger } from '@/lib/logger';
import { browser } from '#imports';
import { defineContentScript } from 'wxt/utils/define-content-script';
import { sendMessage } from '@/lib/messaging';
+import { TabMessage } from '@/lib/tab-messages';
+import { CaptureState } from '@/capture/machine';
import { startCapture } from '@/capture/events';
import { startRrwebRecording } from '@/capture/rrweb-recorder';
import { updateUrl } from '@/capture/spa-nav';
@@ -22,6 +25,7 @@ export default defineContentScript({
function beginCapture(guideId: string) {
if (destroyed) return;
+ logger.info('Begin capture β†’ guideId:', guideId);
stopCapture?.();
stopRrweb?.();
stopCapture = startCapture(guideId);
@@ -29,6 +33,7 @@ export default defineContentScript({
}
function endCapture() {
+ if (stopCapture) logger.info('End capture');
stopCapture?.();
stopRrweb?.();
stopCapture = null;
@@ -52,29 +57,29 @@ export default defineContentScript({
) {
if (destroyed) return false;
- if (msg.type === 'PING') {
+ if (msg.type === TabMessage.PING) {
sendResponse({ alive: true });
return true;
}
- if (msg.type === 'GET_ROUTE') {
+ if (msg.type === TabMessage.GET_ROUTE) {
sendResponse({ alive: true, capturing: !!stopCapture });
return true;
}
- if (msg.type === 'START_CAPTURE' && msg.guideId) {
+ if (msg.type === TabMessage.START_CAPTURE && msg.guideId) {
beginCapture(msg.guideId as string);
sendResponse({ started: true });
return true;
}
- if (msg.type === 'STOP_CAPTURE') {
+ if (msg.type === TabMessage.STOP_CAPTURE) {
endCapture();
sendResponse({ stopped: true });
return true;
}
- if (msg.type === 'SPA_NAVIGATE' && msg.url) {
+ if (msg.type === TabMessage.URL_CHANGED && msg.url) {
updateUrl(msg.url as string);
sendResponse({ updated: true });
return true;
@@ -88,12 +93,12 @@ export default defineContentScript({
sendMessage('getState', undefined)
.then(res => {
if (destroyed) return;
- if (res.state === 'recording' && res.currentGuideId) {
+ if (res.state === CaptureState.RECORDING && res.currentGuideId) {
beginCapture(res.currentGuideId);
}
})
.catch(() => {});
- console.log('[Mimik] Content script loaded');
+ logger.info('Content script loaded β†’', window.location.href);
},
});
diff --git a/src/lib/messaging.ts b/src/lib/messaging.ts
index cd5b2e9..e4da564 100644
--- a/src/lib/messaging.ts
+++ b/src/lib/messaging.ts
@@ -1,29 +1,53 @@
import { defineExtensionMessaging } from '@webext-core/messaging';
import type { ElementMeta } from '@/guides/types';
+import type { CaptureStateValue } from '@/capture/machine';
+
+export interface GetStateResponse {
+ state: CaptureStateValue;
+ stepCount: number;
+ currentGuideId: string | null;
+}
+
+export interface StartRecordingData {
+ url: string;
+}
+
+export interface StartRecordingResponse {
+ guideId: string;
+}
+
+export interface StopRecordingResponse {
+ success: boolean;
+ guideId?: string;
+}
+
+export interface UserActionData {
+ guideId: string;
+ action: string;
+ elementMeta: ElementMeta;
+}
+
+export type UserActionResponse =
+ | { stepId: string }
+ | { ignored: true }
+ | { error: string };
+
+export interface RrwebChunkData {
+ guideId: string;
+ events: unknown[];
+ timestamp: number;
+}
+
+export interface RrwebChunkResponse {
+ stored: boolean;
+}
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 };
+ getState(): GetStateResponse;
+ startRecording(data: StartRecordingData): StartRecordingResponse;
+ stopRecording(): StopRecordingResponse;
+ userAction(data: UserActionData): UserActionResponse;
+ rrwebChunk(data: RrwebChunkData): RrwebChunkResponse;
}
export const { sendMessage, onMessage } = defineExtensionMessaging<MimikProtocol>();
diff --git a/src/lib/port.ts b/src/lib/port.ts
new file mode 100644
index 0000000..f165295
--- /dev/null
+++ b/src/lib/port.ts
@@ -0,0 +1,86 @@
+import { browser } from '#imports';
+import { logger } from '@/lib/logger';
+import type { CaptureStateValue } from '@/capture/machine';
+
+const PORT_NAME = 'mimik-panel';
+
+export interface PanelStateUpdate {
+ type: 'STATE_UPDATE';
+ state: CaptureStateValue;
+ stepCount: number;
+ currentGuideId: string | null;
+}
+
+type PortMessage = PanelStateUpdate;
+
+export function connectToBackground(callbacks: {
+ onStateUpdate: (update: PanelStateUpdate) => void;
+ onConnect: () => void;
+ onDisconnect: () => void;
+}): () => void {
+ let port: ReturnType<typeof browser.runtime.connect> | null = null;
+ let destroyed = false;
+
+ function connect() {
+ if (destroyed) return;
+
+ try {
+ port = browser.runtime.connect({ name: PORT_NAME });
+ logger.debug('Port connected to background');
+ callbacks.onConnect();
+
+ port.onMessage.addListener((msg: PortMessage) => {
+ if (msg.type === 'STATE_UPDATE') {
+ callbacks.onStateUpdate(msg);
+ }
+ });
+
+ port.onDisconnect.addListener(() => {
+ port = null;
+ if (!destroyed) {
+ logger.debug('Port disconnected, reconnecting in 1s...');
+ callbacks.onDisconnect();
+ setTimeout(connect, 1000);
+ }
+ });
+ } catch {
+ if (!destroyed) {
+ logger.debug('Port connect failed, retrying in 1s...');
+ setTimeout(connect, 1000);
+ }
+ }
+ }
+
+ connect();
+
+ return () => {
+ destroyed = true;
+ port?.disconnect();
+ port = null;
+ };
+}
+
+const connectedPorts = new Set<ReturnType<typeof browser.runtime.connect>>();
+
+export function setupPortListener(onPanelConnect?: (port: ReturnType<typeof browser.runtime.connect>) => void) {
+ browser.runtime.onConnect.addListener((port) => {
+ if (port.name !== PORT_NAME) return;
+
+ connectedPorts.add(port);
+ onPanelConnect?.(port);
+
+ port.onDisconnect.addListener(() => {
+ connectedPorts.delete(port);
+ });
+ });
+}
+
+export function broadcastStateToPanel(update: PanelStateUpdate): void {
+ for (const port of connectedPorts) {
+ try {
+ port.postMessage(update);
+ } catch {
+ connectedPorts.delete(port);
+ }
+ }
+}
diff --git a/src/lib/tab-messages.ts b/src/lib/tab-messages.ts
new file mode 100644
index 0000000..516aeee
--- /dev/null
+++ b/src/lib/tab-messages.ts
@@ -0,0 +1,10 @@
+
+export const TabMessage = {
+ PING: 'PING',
+ START_CAPTURE: 'START_CAPTURE',
+ STOP_CAPTURE: 'STOP_CAPTURE',
+ GET_ROUTE: 'GET_ROUTE',
+ URL_CHANGED: 'URL_CHANGED',
+} as const;
+
+export type TabMessageType = (typeof TabMessage)[keyof typeof TabMessage];
diff --git a/src/sidepanel/App.tsx b/src/sidepanel/App.tsx
index fd35c5d..06aa64a 100644
--- a/src/sidepanel/App.tsx
+++ b/src/sidepanel/App.tsx
@@ -1,7 +1,10 @@
+import { logger } from '@/lib/logger';
import { useState, useEffect, useCallback } from 'react';
import { Video, Search } from 'lucide-react';
import { sendMessage } from '@/lib/messaging';
import { getActiveTab } from '@/lib/browser-api';
+import { connectToBackground } from '@/lib/port';
+import { CaptureState } from '@/capture/machine';
import LibraryView from './LibraryView';
import GuideEditor from './GuideEditor';
import RecordingView from './RecordingView';
@@ -41,27 +44,25 @@ export default function App() {
const [search, setSearch] = useState('');
useEffect(() => {
- sendMessage('ping', undefined).then(res => {
- if (res.alive) setIsAlive(true);
- }).catch(() => {});
-
- const interval = setInterval(() => {
- sendMessage('getState', undefined).then(res => {
- if (res.state === 'recording') {
+ const disconnect = connectToBackground({
+ onConnect: () => setIsAlive(true),
+ onDisconnect: () => setIsAlive(false),
+ onStateUpdate: (update) => {
+ if (update.state === CaptureState.RECORDING) {
setIsRecording(true);
- if (res.currentGuideId) {
+ if (update.currentGuideId) {
setView(prev => {
if (prev.name === 'recording') return prev;
- return { name: 'recording', guideId: res.currentGuideId! };
+ return { name: 'recording', guideId: update.currentGuideId! };
});
}
} else {
setIsRecording(false);
}
- }).catch(() => {});
- }, 1000);
+ },
+ });
- return () => clearInterval(interval);
+ return disconnect;
}, []);
const handleStartRecording = useCallback(async () => {
@@ -75,7 +76,7 @@ export default function App() {
setView({ name: 'recording', guideId: res.guideId });
}
} catch (err) {
- console.error('[Mimik] START_RECORDING error', err);
+ logger.error(' START_RECORDING error', err);
}
}, []);
@@ -91,7 +92,7 @@ export default function App() {
}
}
} catch (err) {
- console.error('[Mimik] STOP_RECORDING error', err);
+ logger.error(' STOP_RECORDING error', err);
}
}, []);