π¬ 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
fix: QA improvements β favicon fallback, capture accuracy, guide-me sidepanel
Luis Ortiz53dedf4e660d
diff --git a/src/core/capture/dom/element-meta.ts b/src/core/capture/dom/element-meta.tsindex 5055d83..d118bed 100644--- a/src/core/capture/dom/element-meta.ts+++ b/src/core/capture/dom/element-meta.ts@@ -1,6 +1,27 @@import { getCssSelector } from 'css-selector-generator';import type { ElementMeta } from '@/core/guides/types';+function getCleanText(el: HTMLElement): string | null {+ const clone = el.cloneNode(true) as HTMLElement;+ clone.style.position = 'absolute';+ clone.style.left = '-9999px';+ clone.style.pointerEvents = 'none';+ document.body.appendChild(clone);+ try {+ const hidden = clone.querySelectorAll('[aria-hidden="true"], [hidden], script, style');+ for (const h of Array.from(hidden)) h.remove();+ const text = clone.innerText?.trim();+ if (!text) return null;+ const firstLine = text+ .split('\n')+ .find((l) => l.trim().length > 2)+ ?.trim();+ return firstLine?.slice(0, 80) || null;+ } finally {+ clone.remove();+ }+}+export function extractElementMeta(el: HTMLElement): ElementMeta {const rect = el.getBoundingClientRect();let cssSelector: string;@@ -12,7 +33,7 @@ export function extractElementMeta(el: HTMLElement): ElementMeta {return {tag: el.tagName?.toLowerCase() ?? 'unknown',cssSelector,- textContent: el.textContent?.trim().slice(0, 200) || null,+ textContent: getCleanText(el),ariaLabel: el.getAttribute('aria-label'),placeholder: el.getAttribute('placeholder'),altText: el instanceof HTMLImageElement ? el.alt : null,diff --git a/src/core/capture/dom/element-utils.ts b/src/core/capture/dom/element-utils.tsindex 221b299..52052bf 100644--- a/src/core/capture/dom/element-utils.ts+++ b/src/core/capture/dom/element-utils.ts@@ -52,5 +52,37 @@ export function getFieldValue(el: HTMLElement): string {}export function getFieldLabel(el: HTMLElement): string {- return el.getAttribute('aria-label') || el.getAttribute('placeholder') || el.getAttribute('name') || 'text field';+ const ariaLabel = el.getAttribute('aria-label');+ if (ariaLabel) return ariaLabel;++ const placeholder = el.getAttribute('placeholder');+ if (placeholder) return placeholder;++ if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {+ const labels = el.labels;+ if (labels && labels.length > 0) {+ const labelText = labels[0].innerText?.trim();+ if (labelText) return labelText;+ }+ }++ const id = el.getAttribute('id');+ if (id) {+ const label = document.querySelector(`label[for="${CSS.escape(id)}"]`);+ if (label) {+ const labelText = (label as HTMLElement).innerText?.trim();+ if (labelText) return labelText;+ }+ }++ const parentLabel = el.closest('label');+ if (parentLabel) {+ const labelText = parentLabel.innerText?.trim();+ if (labelText) return labelText;+ }++ const name = el.getAttribute('name');+ if (name && !/[-_]test|[-_]id|[-_]key/i.test(name)) return name;++ return 'text field';}diff --git a/src/core/capture/events/handlers.ts b/src/core/capture/events/handlers.tsindex 89b1039..ed7d995 100644--- a/src/core/capture/events/handlers.ts+++ b/src/core/capture/events/handlers.ts@@ -8,6 +8,18 @@ import { InputSession } from './input-session';const DEDUP_MS = 300;const DRAG_MIN_PX = 30;const INTERCEPT_DELAY_MS = 100;+const PAINT_FRAMES = 3;++function waitForPaint(): Promise<void> {+ return new Promise((resolve) => {+ let remaining = PAINT_FRAMES;+ const tick = () => {+ if (--remaining <= 0) resolve();+ else requestAnimationFrame(tick);+ };+ requestAnimationFrame(tick);+ });+}let lastClickTarget: Element | null = null;let lastClickTime = 0;@@ -55,6 +67,7 @@ class CaptureController {}private async captureAction(action: string, target: HTMLElement) {+ await waitForPaint();await sendMessage('captureStep', {guideId: this.guideId,action,@@ -142,6 +155,8 @@ class CaptureController {return;}+ if (target instanceof HTMLInputElement && (target.type === 'checkbox' || target.type === 'radio')) return;+if (this.input.active && this.input.target !== target) {this.queue.add(() => this.input.finalize());}diff --git a/src/core/capture/step-description.ts b/src/core/capture/step-description.tsindex 584fa1a..c0c8766 100644--- a/src/core/capture/step-description.ts+++ b/src/core/capture/step-description.ts@@ -18,8 +18,10 @@ export function buildFallbackDescription(action: string, meta: ElementMeta): strswitch (action) {case 'click':case 'auxclick':- if (meta.tag === 'input' && meta.inputType === 'checkbox') return `Toggle checkbox ${target}`;- if (meta.tag === 'input' && meta.inputType === 'radio') return `Select radio ${target}`;+ if (meta.tag === 'input' && meta.inputType === 'checkbox') return `Toggle ${target}`;+ if (meta.tag === 'input' && meta.inputType === 'radio') return `Select ${target}`;+ if (meta.role === 'switch' || meta.role === 'checkbox') return `Toggle ${target}`;+ if (meta.role === 'radio') return `Select ${target}`;if (meta.href) return `Click link "${target}"`;return `Click ${target}`;case 'input':diff --git a/src/entrypoints/background/index.ts b/src/entrypoints/background/index.tsindex 0ae550e..40a07d0 100644--- a/src/entrypoints/background/index.ts+++ b/src/entrypoints/background/index.ts@@ -16,7 +16,7 @@ async function generateTitleInBackground(guideId: string) {const settings = await localStorage.get(['aiApiKey', 'aiProvider', 'aiModel']);if (!settings.aiApiKey) {const domain = await getGuideDomain(guideId);- if (domain) await updateGuideTitle(guideId, `Guide on ${domain}`);+ await updateGuideTitle(guideId, domain ? `Guide on ${domain}` : 'New Guide');return;}@@ -31,11 +31,14 @@ async function generateTitleInBackground(guideId: string) {if (title) {await updateGuideTitle(guideId, title);logger.info('Generated guide title:', title);+ } else {+ const domain = await getGuideDomain(guideId);+ await updateGuideTitle(guideId, domain ? `Guide on ${domain}` : 'New Guide');}} catch (err) {logger.error('Guide title generation failed', err);const domain = await getGuideDomain(guideId);- if (domain) await updateGuideTitle(guideId, `Guide on ${domain}`);+ await updateGuideTitle(guideId, domain ? `Guide on ${domain}` : 'New Guide');}}diff --git a/src/lib/utils.ts b/src/lib/utils.tsindex 29c363e..d01885c 100644--- a/src/lib/utils.ts+++ b/src/lib/utils.ts@@ -54,3 +54,22 @@ export function getFaviconUrl(url: string, size = 64): string {return '';}}++const INITIAL_GRADIENTS = [+ ['#6366F1', '#818CF8'],+ ['#8B5CF6', '#A78BFA'],+ ['#EC4899', '#F472B6'],+ ['#14B8A6', '#2DD4BF'],+ ['#F59E0B', '#FBBF24'],+ ['#3B82F6', '#60A5FA'],+] as const;++export function getDomainInitial(domain: string): { letter: string; gradient: readonly [string, string] } {+ const letter = domain.charAt(0).toUpperCase();+ let hash = 0;+ for (let i = 0; i < domain.length; i++) {+ hash = (hash * 31 + domain.charCodeAt(i)) | 0;+ }+ const gradient = INITIAL_GRADIENTS[Math.abs(hash) % INITIAL_GRADIENTS.length];+ return { letter, gradient };+}diff --git a/src/ui/fullview/GuideContent.tsx b/src/ui/fullview/GuideContent.tsxindex 6dd5bda..510f873 100644--- a/src/ui/fullview/GuideContent.tsx+++ b/src/ui/fullview/GuideContent.tsx@@ -11,8 +11,9 @@ import {} from '@/core/guides/service';import type { Guide, Screenshot, Step } from '@/core/guides/types';import { sendMessage } from '@/lib/messaging';-import { getFaviconUrl, getMostCommonDomain } from '@/lib/utils';+import { getMostCommonDomain } from '@/lib/utils';import { useFullview } from '@/stores/fullview';+import FaviconImg from '@/ui/shared/FaviconImg';import BlurCanvas from '@/ui/sidepanel/BlurCanvas';import GuideStepList from './components/GuideStepList';@@ -199,20 +200,14 @@ export default function GuideContent({ guideId }: GuideContentProps) {</span>{domain && (<span className="inline-flex items-center gap-1.5 text-[11px] font-medium text-muted-foreground bg-card border border-border pl-1.5 pr-2.5 py-0.5 rounded-full">- <img- src={getFaviconUrl(domain, 16)}- alt=""- className="w-3.5 h-3.5 rounded-full"- onError={(e) => {- (e.target as HTMLImageElement).style.display = 'none';- }}- />+ <FaviconImg domain={domain} size={14} className="rounded-full" />{domain}</span>)}{data.steps.length > 0 && (<buttononClick={async () => {+ await chrome.sidePanel.open({ windowId: chrome.windows.WINDOW_ID_CURRENT });await sendMessage('startGuideMe', { guideId });}}disabled={!data.steps.some((s) => s.elementMeta)}diff --git a/src/ui/fullview/SearchModal.tsx b/src/ui/fullview/SearchModal.tsxindex 1c4c7a3..d8c15a9 100644--- a/src/ui/fullview/SearchModal.tsx+++ b/src/ui/fullview/SearchModal.tsx@@ -2,7 +2,7 @@ import { Search, X } from 'lucide-react';import { useCallback, useEffect, useRef, useState } from 'react';import { getGuideDomain, getGuides } from '@/core/guides/service';import type { Guide } from '@/core/guides/types';-import { getFaviconUrl } from '@/lib/utils';+import { useFullview } from '@/stores/fullview';import { Dialog, DialogPortal } from '@/ui/components/ui/dialog';import { Input } from '@/ui/components/ui/input';@@ -12,7 +12,7 @@ import { navigate } from './router';interface GuideResult {guide: Guide;- favicon: string;+ domain: string;}export default function SearchModal() {@@ -31,7 +31,7 @@ export default function SearchModal() {const withFavicons = await Promise.all(guides.map(async (guide) => {const domain = await getGuideDomain(guide.id);- return { guide, favicon: domain ? getFaviconUrl(domain) : '' };+ return { guide, domain: domain || '' };}),);setResults(withFavicons);diff --git a/src/ui/fullview/components/SearchResults.tsx b/src/ui/fullview/components/SearchResults.tsxindex ad7eb50..6709d4a 100644--- a/src/ui/fullview/components/SearchResults.tsx+++ b/src/ui/fullview/components/SearchResults.tsx@@ -1,9 +1,10 @@import type { Guide } from '@/core/guides/types';import { formatDateShort } from '@/lib/utils';+import FaviconImg from '@/ui/shared/FaviconImg';interface GuideResult {guide: Guide;- favicon: string;+ domain: string;}interface SearchResultsProps {@@ -53,18 +54,7 @@ export default function SearchResults({ results, query, selected, onSelect, onHo}}>- {r.favicon ? (- <img- src={r.favicon}- alt=""- className="w-3.5 h-3.5"- onError={(e) => {- (e.target as HTMLImageElement).style.display = 'none';- }}- />- ) : (- r.guide.title.charAt(0).toUpperCase()- )}+ <FaviconImg domain={r.domain} size={14} /></div><div className="flex-1 min-w-0"><pdiff --git a/src/ui/shared/FaviconImg.tsx b/src/ui/shared/FaviconImg.tsxnew file mode 100644index 0000000..1f1a11e--- /dev/null+++ b/src/ui/shared/FaviconImg.tsx@@ -0,0 +1,49 @@+import { useState } from 'react';+import { getDomainInitial, getFaviconUrl } from '@/lib/utils';++interface FaviconImgProps {+ domain: string;+ size?: number;+ className?: string;+}++export default function FaviconImg({ domain, size = 20, className = '' }: FaviconImgProps) {+ const [failed, setFailed] = useState(false);+ const src = domain ? getFaviconUrl(domain, size > 32 ? 64 : 32) : '';++ if (!domain || failed) {+ const { letter, gradient } = getDomainInitial(domain || '?');+ const fontSize = Math.max(Math.round(size * 0.55), 6);+ return (+ <span+ className={className}+ style={{+ display: 'inline-flex',+ alignItems: 'center',+ justifyContent: 'center',+ width: size,+ height: size,+ borderRadius: '50%',+ background: `linear-gradient(135deg, ${gradient[0]}, ${gradient[1]})`,+ color: '#fff',+ fontSize,+ fontWeight: 600,+ lineHeight: 1,+ flexShrink: 0,+ }}+ >+ {letter}+ </span>+ );+ }++ return (+ <img+ src={src}+ alt=""+ className={className}+ style={{ width: size, height: size, flexShrink: 0 }}+ onError={() => setFailed(true)}+ />+ );+}diff --git a/src/ui/sidepanel/GuideEditor.tsx b/src/ui/sidepanel/GuideEditor.tsxindex 6cfb1dd..2c94cd0 100644--- a/src/ui/sidepanel/GuideEditor.tsx+++ b/src/ui/sidepanel/GuideEditor.tsx@@ -11,9 +11,10 @@ import {import type { Guide, Screenshot, Step } from '@/core/guides/types';import { createTab, focusWindow, getExtensionURL, queryTabs, updateTab } from '@/lib/browser-api';import { sendMessage } from '@/lib/messaging';-import { getFaviconUrl, getMostCommonDomain } from '@/lib/utils';+import { getMostCommonDomain } from '@/lib/utils';import { Input } from '@/ui/components/ui/input';import EmptyGuideState from '@/ui/shared/EmptyGuideState';+import FaviconImg from '@/ui/shared/FaviconImg';import BlurCanvas from './BlurCanvas';import ExportMenu from './ExportMenu';import StepCard from './StepCard';@@ -183,14 +184,7 @@ export default function GuideEditor({ guideId, onBack, onGuideMe }: GuideEditorPreturn (<span className="flex items-center gap-1"><span className="text-border">Β·</span>- <img- src={getFaviconUrl(d, 16)}- alt=""- className="w-3 h-3 rounded-full"- onError={(e) => {- (e.target as HTMLImageElement).style.display = 'none';- }}- />+ <FaviconImg domain={d} size={12} className="rounded-full" />{d}</span>);diff --git a/src/ui/sidepanel/GuideMeView.tsx b/src/ui/sidepanel/GuideMeView.tsxindex 3bac953..e482734 100644--- a/src/ui/sidepanel/GuideMeView.tsx+++ b/src/ui/sidepanel/GuideMeView.tsx@@ -6,7 +6,8 @@ import { SESSION_KEY } from '@/core/guideme/session';import { getGuide } from '@/core/guides/service';import type { Guide, Screenshot, Step } from '@/core/guides/types';import { sendMessage } from '@/lib/messaging';-import { extractDomain, getFaviconUrl } from '@/lib/utils';+import { extractDomain } from '@/lib/utils';+import FaviconImg from '@/ui/shared/FaviconImg';interface GuideMeViewProps {guideId: string;@@ -201,18 +202,7 @@ export default function GuideMeView({ guideId, onExit, onComplete }: GuideMeView</p>{viewedStep?.url && (<span className="flex items-center gap-1.5 text-[11px] text-muted-foreground mt-1.5">- <img- src={getFaviconUrl(extractDomain(viewedStep.url), 16)}- alt=""- className="w-3.5 h-3.5 rounded-full"- onError={(e) => {- (e.target as HTMLImageElement).replaceWith(- Object.assign(document.createElement('span'), {- innerHTML: `<svg xmlns="http://www.w3.org/2000/svg" width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M2 12h20M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/></svg>`,- }),- );- }}- />+ <FaviconImg domain={extractDomain(viewedStep.url)} size={14} className="rounded-full" />{extractDomain(viewedStep.url)}</span>)}diff --git a/src/ui/sidepanel/LibraryView.tsx b/src/ui/sidepanel/LibraryView.tsxindex a90951d..0f750d8 100644--- a/src/ui/sidepanel/LibraryView.tsx+++ b/src/ui/sidepanel/LibraryView.tsx@@ -9,7 +9,8 @@ import {toggleStar,} from '@/core/guides/service';import type { Guide } from '@/core/guides/types';-import { formatRelativeTime, getFaviconUrl } from '@/lib/utils';+import { formatRelativeTime } from '@/lib/utils';+import FaviconImg from '@/ui/shared/FaviconImg';interface LibraryViewProps {onOpen: (guideId: string) => void;@@ -19,7 +20,6 @@ interface LibraryViewProps {}interface GuideWithMeta extends Guide {- favicon: string;domain: string;}@@ -36,7 +36,6 @@ export default function LibraryView({ onOpen, searchQuery = '' }: LibraryViewProconst domain = await getGuideDomain(guide.id);return {...guide,- favicon: domain ? getFaviconUrl(domain) : '',domain,};}),@@ -117,19 +116,7 @@ export default function LibraryView({ onOpen, searchQuery = '' }: LibraryViewProonClick={() => onOpen(guide.id)}><div className="w-7 h-7 mt-0.5 rounded-full flex items-center justify-center shrink-0 overflow-hidden">- {guide.favicon ? (- <img- src={guide.favicon}- alt=""- className="w-5 h-5"- onError={(e) => {- const el = e.target as HTMLImageElement;- el.style.display = 'none';- }}- />- ) : (- <div className="w-full h-full rounded-full border-[1.5px] border-dashed border-border" />- )}+ <FaviconImg domain={guide.domain} size={20} /></div><div className="flex-1 min-w-0">