π¬ 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: simplify Guide Me overlay to action-only label card
Luis Ortiza16fd0bfe360
diff --git a/src/core/guideme/overlay.ts b/src/core/guideme/overlay.tsindex aa3fcb0..95f2d79 100644--- a/src/core/guideme/overlay.ts+++ b/src/core/guideme/overlay.ts@@ -1,17 +1,5 @@-import { db } from '@/core/guides/db';-import type { Screenshot, Step } from '@/core/guides/types';--interface GuideMeCallbacks {- onAdvance: (stepIndex: number) => void;- onPrev: (stepIndex: number) => void;- onCancel: () => void;-}--function escapeHtml(text: string): string {- const div = document.createElement('div');- div.textContent = text;- return div.innerHTML;-}+const ELEMENT_TAG = 'mimik-guideme';+const PAD = 6;const STYLES = `:host {@@ -19,126 +7,71 @@ const STYLES = `inset: 0;z-index: 2147483646;pointer-events: none;- font-family: 'Poppins', sans-serif;- }-- .spotlight {- position: fixed;- inset: 0;- pointer-events: none;- }-- .spotlight path {- pointer-events: auto;- cursor: default;+ font-family: 'Poppins', system-ui, sans-serif;}.highlight {position: fixed;border: 2px solid #F59E0B;border-radius: 4px;- box-shadow: 0 0 0 4px rgba(245, 158, 11, 0.25), 0 0 20px rgba(245, 158, 11, 0.15);+ box-shadow: 0 0 0 3px rgba(245, 158, 11, 0.15), 0 0 12px rgba(245, 158, 11, 0.2);pointer-events: none;transition: all 0.3s ease;}- .tooltip {+ .label {position: fixed;- background: #451a03;- color: #FDE68A;- border-radius: 12px;- padding: 16px;- max-width: 320px;- min-width: 240px;- pointer-events: auto;- box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);- font-size: 14px;- transition: all 0.3s ease;- }-- .tooltip-step {- font-size: 11px;- font-weight: 600;- opacity: 0.6;- margin-bottom: 6px;- }-- .tooltip-description {- font-weight: 500;- margin-bottom: 12px;- }-- .tooltip-screenshot {- width: 100%;- border-radius: 8px;- border: 1px solid rgba(253, 230, 138, 0.2);- margin-bottom: 12px;- }-- .tooltip-actions {+ background: white;+ border-radius: 10px;+ padding: 10px 14px;+ box-shadow: 0 4px 20px rgba(0, 0, 0, 0.25);+ border: 1px solid rgba(0, 0, 0, 0.06);display: flex;+ align-items: center;gap: 8px;+ max-width: 320px;+ pointer-events: none;}- .tooltip-actions button {- font-size: 12px;- font-weight: 600;- padding: 6px 14px;- border-radius: 8px;- border: none;- cursor: pointer;- font-family: 'Poppins', sans-serif;- }-- .btn-nav {- background: rgba(253, 230, 138, 0.15);- color: #FDE68A;- }-- .btn-next {+ .label .num {+ width: 22px;+ height: 22px;+ border-radius: 50%;background: #F59E0B;+ display: flex;+ align-items: center;+ justify-content: center;+ font-size: 10px;+ font-weight: 800;color: #451a03;- margin-left: auto;+ flex-shrink: 0;}- .btn-cancel {- background: transparent;- color: rgba(253, 230, 138, 0.5);- padding: 6px 8px;- font-size: 11px;- }-- .fallback-msg {+ .label .text {font-size: 12px;- color: rgba(253, 230, 138, 0.7);- margin-bottom: 8px;+ font-weight: 600;+ color: #451a03;+ line-height: 1.35;}`;-const PAD = 6;-const CUTOUT_RADIUS = 4;-const TOOLTIP_GAP = 12;+function escapeHtml(text: string): string {+ const div = document.createElement('div');+ div.textContent = text;+ return div.innerHTML;+}export class GuideMeOverlay {private host: HTMLElement;private shadow: ShadowRoot;- private spotlight: SVGSVGElement | null = null;private highlightEl: HTMLDivElement | null = null;- private tooltipEl: HTMLDivElement | null = null;- private resizeObserver: ResizeObserver | null = null;- private scrollHandler: (() => void) | null = null;- private escapeHandler: ((e: KeyboardEvent) => void) | null = null;- private targetClickHandler: (() => void) | null = null;- private targetKeyHandler: ((e: KeyboardEvent) => void) | null = null;+ private labelEl: HTMLDivElement | null = null;private currentTarget: HTMLElement | null = null;- private currentStepIndex = 0;- private screenshotUrl: string | null = null;- private autoAdvanceTimer: ReturnType<typeof setTimeout> | null = null;- private callbacks: GuideMeCallbacks;+ private scrollHandler: (() => void) | null = null;+ private resizeObserver: ResizeObserver | null = null;- constructor(callbacks: GuideMeCallbacks) {- this.callbacks = callbacks;- this.host = document.createElement('mimik-guideme');+ constructor() {+ this.host = document.createElement(ELEMENT_TAG);this.host.setAttribute('data-mimik-ignore', '');this.shadow = this.host.attachShadow({ mode: 'closed' });@@ -149,311 +82,86 @@ export class GuideMeOverlay {document.documentElement.appendChild(this.host);}- async show(step: Step, stepIndex: number, totalSteps: number, targetElement: HTMLElement | null): Promise<void> {+ show(description: string, stepNumber: number, targetElement: HTMLElement | null): void {this.cleanup();- this.currentStepIndex = stepIndex;this.currentTarget = targetElement;if (targetElement) {targetElement.scrollIntoView({ behavior: 'smooth', block: 'center' });- await new Promise((r) => setTimeout(r, 400));- this.renderWithTarget(targetElement, step, stepIndex, totalSteps);- this.setupActionDetection(step, targetElement);- } else {- await this.renderFallback(step, stepIndex, totalSteps);- }-- this.setupGlobalListeners();- }-- destroy(): void {- this.cleanup();- this.host.remove();- }-- private cleanup(): void {- if (this.autoAdvanceTimer) {- clearTimeout(this.autoAdvanceTimer);- this.autoAdvanceTimer = null;- }-- if (this.targetClickHandler && this.currentTarget) {- this.currentTarget.removeEventListener('click', this.targetClickHandler);- this.targetClickHandler = null;- }-- if (this.targetKeyHandler && this.currentTarget) {- this.currentTarget.removeEventListener('keydown', this.targetKeyHandler);- this.targetKeyHandler = null;- }-- if (this.escapeHandler) {- document.removeEventListener('keydown', this.escapeHandler);- this.escapeHandler = null;- }-- if (this.scrollHandler) {- window.removeEventListener('scroll', this.scrollHandler, true);- this.scrollHandler = null;- }-- if (this.resizeObserver) {- this.resizeObserver.disconnect();- this.resizeObserver = null;- }-- if (this.screenshotUrl) {- URL.revokeObjectURL(this.screenshotUrl);- this.screenshotUrl = null;- }-- if (this.spotlight) {- this.spotlight.remove();- this.spotlight = null;- }-- if (this.highlightEl) {- this.highlightEl.remove();- this.highlightEl = null;- }-- if (this.tooltipEl) {- this.tooltipEl.remove();- this.tooltipEl = null;+ setTimeout(() => this.render(description, stepNumber, targetElement), 400);}}- private renderWithTarget(target: HTMLElement, step: Step, stepIndex: number, totalSteps: number): void {+ private render(description: string, stepNumber: number, target: HTMLElement): void {const rect = target.getBoundingClientRect();- this.renderSpotlight(rect);- this.renderHighlight(rect);- this.renderTooltip(step, stepIndex, totalSteps, false, rect);- }-- private async renderFallback(step: Step, stepIndex: number, totalSteps: number): Promise<void> {- if (step.screenshotId) {- const screenshot: Screenshot | undefined = await db.screenshots.get(step.screenshotId);- if (screenshot) {- this.screenshotUrl = URL.createObjectURL(screenshot.blob);- }- }-- this.renderSpotlight(null);- this.renderTooltip(step, stepIndex, totalSteps, true, null);- }-- private renderSpotlight(rect: DOMRect | null): void {- const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');- svg.setAttribute('class', 'spotlight');- svg.setAttribute('width', '100%');- svg.setAttribute('height', '100%');-- const vw = window.innerWidth;- const vh = window.innerHeight;- svg.setAttribute('viewBox', `0 0 ${vw} ${vh}`);-- let pathD: string;- if (rect) {- const x = rect.left - PAD;- const y = rect.top - PAD;- const w = rect.width + PAD * 2;- const h = rect.height + PAD * 2;- const r = CUTOUT_RADIUS;-- pathD =- `M0,0 H${vw} V${vh} H0 Z ` +- `M${x + r},${y} ` +- `H${x + w - r} Q${x + w},${y} ${x + w},${y + r} ` +- `V${y + h - r} Q${x + w},${y + h} ${x + w - r},${y + h} ` +- `H${x + r} Q${x},${y + h} ${x},${y + h - r} ` +- `V${y + r} Q${x},${y} ${x + r},${y} Z`;- } else {- pathD = `M0,0 H${vw} V${vh} H0 Z`;- }- const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');- path.setAttribute('fill-rule', 'evenodd');- path.setAttribute('fill', 'rgba(0,0,0,0.4)');- path.setAttribute('d', pathD);-- svg.appendChild(path);- path.addEventListener('click', (e) => e.stopPropagation());- this.shadow.appendChild(svg);- this.spotlight = svg;- }-- private renderHighlight(rect: DOMRect): void {- const div = document.createElement('div');- div.className = 'highlight';- div.style.left = `${rect.left - PAD}px`;- div.style.top = `${rect.top - PAD}px`;- div.style.width = `${rect.width + PAD * 2}px`;- div.style.height = `${rect.height + PAD * 2}px`;- this.shadow.appendChild(div);- this.highlightEl = div;- }-- private renderTooltip(- step: Step,- stepIndex: number,- totalSteps: number,- isFallback: boolean,- rect: DOMRect | null,- ): void {- const div = document.createElement('div');- div.className = 'tooltip';-- let html = `<div class="tooltip-step">Step ${stepIndex + 1} of ${totalSteps}</div>`;- html += `<div class="tooltip-description">${escapeHtml(step.description)}</div>`;-- if (isFallback) {- html += `<div class="fallback-msg">Could not find the target element on this page.</div>`;- if (this.screenshotUrl) {- html += `<img class="tooltip-screenshot" src="${this.screenshotUrl}" alt="Step screenshot" />`;- }- }-- html += `<div class="tooltip-actions">`;- if (stepIndex > 0) {- html += `<button class="btn-nav" data-action="prev">Prev</button>`;- }- html += `<button class="btn-cancel" data-action="cancel">Cancel</button>`;- if (isFallback) {- html += `<button class="btn-next" data-action="next">Next</button>`;- }- html += `</div>`;-- div.innerHTML = html;-- div.addEventListener('click', (e) => {- const target = (e.target as HTMLElement).closest('button');- if (!target) return;- const action = target.getAttribute('data-action');- if (action === 'prev') this.callbacks.onPrev(stepIndex);- else if (action === 'next') this.callbacks.onAdvance(stepIndex);- else if (action === 'cancel') this.callbacks.onCancel();- });-- this.shadow.appendChild(div);- this.tooltipEl = div;-- this.positionTooltip(rect);- }-- private positionTooltip(rect: DOMRect | null): void {- if (!this.tooltipEl) return;-- if (!rect) {- this.tooltipEl.style.left = '50%';- this.tooltipEl.style.top = '50%';- this.tooltipEl.style.transform = 'translate(-50%, -50%)';- return;- }-- this.tooltipEl.style.transform = '';-- const tooltipRect = this.tooltipEl.getBoundingClientRect();- const vw = window.innerWidth;- const vh = window.innerHeight;-- const belowY = rect.bottom + PAD + TOOLTIP_GAP;- const aboveY = rect.top - PAD - TOOLTIP_GAP - tooltipRect.height;- const centerX = Math.max(- 8,- Math.min(rect.left + rect.width / 2 - tooltipRect.width / 2, vw - tooltipRect.width - 8),- );-- if (belowY + tooltipRect.height < vh) {- this.tooltipEl.style.left = `${centerX}px`;- this.tooltipEl.style.top = `${belowY}px`;+ this.highlightEl = document.createElement('div');+ this.highlightEl.className = 'highlight';+ this.positionHighlight(rect);+ this.shadow.appendChild(this.highlightEl);++ this.labelEl = document.createElement('div');+ this.labelEl.className = 'label';+ this.labelEl.innerHTML = `<span class="num">${stepNumber}</span><span class="text">${escapeHtml(description)}</span>`;+ this.shadow.appendChild(this.labelEl);+ this.positionLabel(rect);++ this.scrollHandler = () => this.reposition();+ window.addEventListener('scroll', this.scrollHandler, true);+ this.resizeObserver = new ResizeObserver(() => this.reposition());+ this.resizeObserver.observe(document.documentElement);+ }++ private positionHighlight(rect: DOMRect): void {+ if (!this.highlightEl) return;+ this.highlightEl.style.left = `${rect.left - PAD}px`;+ this.highlightEl.style.top = `${rect.top - PAD}px`;+ this.highlightEl.style.width = `${rect.width + PAD * 2}px`;+ this.highlightEl.style.height = `${rect.height + PAD * 2}px`;+ }++ private positionLabel(rect: DOMRect): void {+ if (!this.labelEl) return;+ const gap = 10;+ const labelRect = this.labelEl.getBoundingClientRect();+ const belowY = rect.bottom + PAD + gap;+ const aboveY = rect.top - PAD - gap - labelRect.height;+ const leftX = Math.max(8, Math.min(rect.left, window.innerWidth - labelRect.width - 8));++ if (belowY + labelRect.height < window.innerHeight) {+ this.labelEl.style.top = `${belowY}px`;+ this.labelEl.style.left = `${leftX}px`;} else if (aboveY > 0) {- this.tooltipEl.style.left = `${centerX}px`;- this.tooltipEl.style.top = `${aboveY}px`;+ this.labelEl.style.top = `${aboveY}px`;+ this.labelEl.style.left = `${leftX}px`;} else {- const rightX = rect.right + PAD + TOOLTIP_GAP;- const rightY = Math.max(- 8,- Math.min(rect.top + rect.height / 2 - tooltipRect.height / 2, vh - tooltipRect.height - 8),- );- this.tooltipEl.style.left = `${rightX}px`;- this.tooltipEl.style.top = `${rightY}px`;+ this.labelEl.style.top = `${rect.top}px`;+ this.labelEl.style.left = `${rect.right + PAD + gap}px`;}}private reposition(): void {if (!this.currentTarget) return;-const rect = this.currentTarget.getBoundingClientRect();-- if (this.spotlight) {- this.spotlight.remove();- this.spotlight = null;- }- this.renderSpotlight(rect);-- if (this.highlightEl) {- this.highlightEl.style.left = `${rect.left - PAD}px`;- this.highlightEl.style.top = `${rect.top - PAD}px`;- this.highlightEl.style.width = `${rect.width + PAD * 2}px`;- this.highlightEl.style.height = `${rect.height + PAD * 2}px`;- }-- this.positionTooltip(rect);+ this.positionHighlight(rect);+ this.positionLabel(rect);}- private setupGlobalListeners(): void {- this.escapeHandler = (e: KeyboardEvent) => {- if (e.key === 'Escape') {- e.preventDefault();- e.stopPropagation();- this.callbacks.onCancel();- }- };- document.addEventListener('keydown', this.escapeHandler);-- if (this.currentTarget) {- this.scrollHandler = () => this.reposition();- window.addEventListener('scroll', this.scrollHandler, true);-- this.resizeObserver = new ResizeObserver(() => this.reposition());- this.resizeObserver.observe(document.documentElement);+ private cleanup(): void {+ if (this.scrollHandler) {+ window.removeEventListener('scroll', this.scrollHandler, true);+ this.scrollHandler = null;}+ this.resizeObserver?.disconnect();+ this.resizeObserver = null;+ this.highlightEl?.remove();+ this.highlightEl = null;+ this.labelEl?.remove();+ this.labelEl = null;}- private setupActionDetection(step: Step, target: HTMLElement): void {- if (step.action === 'click') {- this.targetClickHandler = () => {- this.callbacks.onAdvance(this.currentStepIndex);- };- target.addEventListener('click', this.targetClickHandler);- } else if (step.action === 'input') {- if (target instanceof HTMLElement && target.getAttribute('contenteditable') !== null) {- target.textContent = step.inputValue ?? '';- } else if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {- const proto =- target instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;- const nativeSetter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;- if (nativeSetter) {- nativeSetter.call(target, step.inputValue ?? '');- } else {- target.value = step.inputValue ?? '';- }- }-- target.dispatchEvent(new Event('input', { bubbles: true }));- target.dispatchEvent(new Event('change', { bubbles: true }));-- this.autoAdvanceTimer = setTimeout(() => {- this.callbacks.onAdvance(this.currentStepIndex);- }, 500);- } else if (step.action.startsWith('keydown:')) {- const expectedKey = step.action.replace('keydown:', '');- this.targetKeyHandler = (e: KeyboardEvent) => {- if (e.key === expectedKey) {- this.callbacks.onAdvance(this.currentStepIndex);- }- };- target.addEventListener('keydown', this.targetKeyHandler);- }+ destroy(): void {+ this.cleanup();+ this.host.remove();}}