π¬ 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: persistent port connection and typed state sync
Luis Ortiz540edafffe01
diff --git a/src/entrypoints/background/index.ts b/src/entrypoints/background/index.tsindex 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.tsindex 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.tsindex 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 }): booexport 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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);}}, []);