π¬ 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
feat(video): add a step-list preview player and download progress
Luis Ortiz48167727ad1e
diff --git a/package.json b/package.jsonindex 3a6073c..4206c5c 100644--- a/package.json+++ b/package.json@@ -29,6 +29,7 @@"@ai-sdk/openai": "^3.0.49","@fontsource/poppins": "^5.2.7","@tailwindcss/vite": "^4.2.2",+ "@vidstack/react": "^1.15.6","@webext-core/messaging": "^2.3.0","@wxt-dev/module-react": "^1.2.2","@xstate/react": "^6.1.0",diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex e9c7529..8a638a5 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -25,6 +25,9 @@ importers:'@tailwindcss/vite':specifier: ^4.2.2+ '@vidstack/react':+ specifier: ^1.15.6+ version: 1.15.6(@types/[email protected])([email protected])'@webext-core/messaging':specifier: ^2.3.0version: 2.3.0@@ -1607,6 +1610,13 @@ packages:resolution: {integrity: sha512-Fw28YZpRnA3cAHHDlkt7xQHiJ0fcL+NRcIqsocZQUSmbzeIKRpwttJjik5ZGanXP+vlA4SbTg+AbA3bP363l+w==}engines: {node: '>= 20'}+ '@vidstack/[email protected]':+ resolution: {integrity: sha512-hO7cLld5yfxCdDnDCYqh5aS7JxmHfsmX43PmKBJWzDTwK40P3hh5qAdDQzl3qDtEJLYjuo3Sv+kr6tt/VRtJzQ==}+ engines: {node: '>=18'}+ peerDependencies:+ '@types/react': ^18.0.0 || ^19.0.0+ react: ^18.0.0 || ^19.0.0+'@vitejs/[email protected]':resolution: {integrity: sha512-l9X/E3cDb+xY3SWzlG1MOGt2usfEHGMNIaegaUGFsLkb3RCn/k8/TOXBcab+OndDI4TBtktT8/9BwwW8Vi9KUQ==}engines: {node: ^20.19.0 || >=22.12.0}@@ -2702,6 +2712,10 @@ packages:resolution: {integrity: sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ==}+ resolution: {integrity: sha512-cyDNmuZvvO4H27rcBq2Eudxo9IZRDCOX/I7VEyqbxsEiD2Ei7UYUhG/Sc5fvMZjmathgz3fEK7iAKqvpY+Ux1w==}+ engines: {node: '>=16'}+resolution: {integrity: sha512-rMGwH5fykDCSA55LG9aWkE433wwHrycq3J5mRf+djBnHBZzmJGvIwg6Qfcfr4rRkzkmrdmewxQozLkOM1H1C6Q==}@@ -5039,6 +5053,13 @@ snapshots:'@vercel/[email protected]': {}+ dependencies:+ '@floating-ui/dom': 1.7.6+ '@types/react': 19.2.14+ media-captions: 1.0.4+ react: 19.2.4+'@vitejs/[email protected]([email protected](@types/[email protected])([email protected])([email protected]))':dependencies:'@rolldown/pluginutils': 1.0.0-rc.7@@ -6097,6 +6118,8 @@ snapshots:+ [email protected]: {}+dependencies:'@types/dom-mediacapture-transform': 0.1.12diff --git a/src/ui/fullview/ExportPreviewModal.tsx b/src/ui/fullview/ExportPreviewModal.tsxindex d70e755..c9a7904 100644--- a/src/ui/fullview/ExportPreviewModal.tsx+++ b/src/ui/fullview/ExportPreviewModal.tsx@@ -1,5 +1,5 @@import { FileCode, FileDown, FileText, Loader2, Video } from 'lucide-react';-import { useEffect, useState } from 'react';+import { lazy, Suspense, useEffect, useRef, useState } from 'react';import { i18n } from '#imports';import { downloadBlob, downloadText, safeFilename } from '@/core/export/download';import { exportGuideAsHTML } from '@/core/export/html-export';@@ -9,14 +9,18 @@ import {type ImageScale,loadExportOptions,saveExportOptions,+ VIDEO_RESOLUTIONS,} from '@/core/export/options';import { exportGuideAsPDF } from '@/core/export/pdf-export';import { paginatePreview, withPreviewStyles } from '@/core/export/preview';+import type { VideoChapter } from '@/core/export/video-export';import { canExportVideo, STEP_SECONDS } from '@/core/export/video-support';import type { Guide, Screenshot, Step } from '@/core/guides/types';import { Button } from '@/ui/components/ui/button';import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/ui/components/ui/dialog';+const VideoStepPlayer = lazy(() => import('@/ui/fullview/VideoStepPlayer'));+const VIDEO_AUTOPLAY_STEP_LIMIT = 25;const IMAGE_SCALES: ImageScale[] = ['small', 'medium', 'large'];@@ -39,6 +43,9 @@ export default function ExportPreviewModal({ open, onOpenChange, guide, steps, sconst [videoSupported, setVideoSupported] = useState(false);const [mode, setMode] = useState<PreviewMode>('document');const [videoUrl, setVideoUrl] = useState<string | null>(null);+ const [videoChapters, setVideoChapters] = useState<VideoChapter[]>([]);+ const [downloadProgress, setDownloadProgress] = useState(0);+ const downloadAbort = useRef<AbortController | null>(null);const [videoError, setVideoError] = useState<string | null>(null);const [videoProgress, setVideoProgress] = useState(0);const [videoRequested, setVideoRequested] = useState(false);@@ -58,7 +65,7 @@ export default function ExportPreviewModal({ open, onOpenChange, guide, steps, s}, []);const videoPending = steps.length > VIDEO_AUTOPLAY_STEP_LIMIT && !videoRequested;- const cover = options.cover;+ const { cover, stepDescriptions, resolution } = options;useEffect(() => {if (!open) setVideoRequested(false);@@ -89,11 +96,11 @@ export default function ExportPreviewModal({ open, onOpenChange, guide, steps, sconst timer = setTimeout(async () => {try {const { exportGuideAsVideo } = await import('@/core/export/video-export');- const { blob } = await exportGuideAsVideo(+ const { blob, chapters } = await exportGuideAsVideo(guide,steps,screenshots,- { cover },+ { cover, stepDescriptions, resolution },{signal: controller.signal,onProgress: (encoded, frames) => {@@ -103,6 +110,7 @@ export default function ExportPreviewModal({ open, onOpenChange, guide, steps, s);if (controller.signal.aborted) return;url = URL.createObjectURL(blob);+ setVideoChapters(chapters);setVideoUrl(url);} catch (error) {if (controller.signal.aborted || (error instanceof DOMException && error.name === 'AbortError')) return;@@ -115,7 +123,7 @@ export default function ExportPreviewModal({ open, onOpenChange, guide, steps, sif (url) URL.revokeObjectURL(url);setVideoUrl(null);};- }, [open, mode, guide, steps, screenshots, cover, videoPending]);+ }, [open, mode, guide, steps, screenshots, cover, stepDescriptions, resolution, videoPending]);const update = (patch: Partial<ExportOptions>) => {const next = { ...options, ...patch };@@ -135,15 +143,24 @@ export default function ExportPreviewModal({ open, onOpenChange, guide, steps, sconst { exportGuideAsDOCX } = await import('@/core/export/docx-export');downloadBlob(await exportGuideAsDOCX(guide, steps, screenshots, options), safeFilename(guide.title, 'docx'));} else if (format === 'video') {+ const controller = new AbortController();+ downloadAbort.current = controller;+ setDownloadProgress(0);const { exportGuideAsVideo } = await import('@/core/export/video-export');- const { blob, extension } = await exportGuideAsVideo(guide, steps, screenshots, options);+ const { blob, extension } = await exportGuideAsVideo(guide, steps, screenshots, options, {+ signal: controller.signal,+ onProgress: (encoded, frames) => setDownloadProgress(frames > 0 ? encoded / frames : 0),+ });downloadBlob(blob, safeFilename(guide.title, extension));} else {const { exportGuideAsMarkdown } = await import('@/core/export/markdown-export');const md = await exportGuideAsMarkdown(guide, steps, screenshots);downloadText(md, safeFilename(guide.title, 'md'), 'text/markdown');}+ } catch (error) {+ if (!(error instanceof DOMException && error.name === 'AbortError')) throw error;} finally {+ downloadAbort.current = null;setExporting(null);}}@@ -152,6 +169,11 @@ export default function ExportPreviewModal({ open, onOpenChange, guide, steps, s{ key: 'cover', label: i18n.t('exportPreview.cover'), hint: i18n.t('exportPreview.coverHint') },{ key: 'screenshots', label: i18n.t('exportPreview.screenshots'), hint: i18n.t('exportPreview.screenshotsHint') },{ key: 'stepUrls', label: i18n.t('exportPreview.stepUrls'), hint: i18n.t('exportPreview.stepUrlsHint') },+ {+ key: 'stepDescriptions',+ label: i18n.t('exportPreview.stepDescriptions'),+ hint: i18n.t('exportPreview.stepDescriptionsHint'),+ },];const modes: Array<{ key: PreviewMode; icon: typeof FileText; label: string }> = [@@ -223,20 +245,49 @@ export default function ExportPreviewModal({ open, onOpenChange, guide, steps, s</div></div>+ {videoSupported && (+ <div className="pt-3 border-t border-border">+ <div className="text-[12px] font-semibold text-foreground mb-2">+ {i18n.t('exportPreview.resolution')}+ </div>+ <div className="flex gap-1.5">+ {VIDEO_RESOLUTIONS.map((value) => (+ <button+ key={value}+ type="button"+ onClick={() => update({ resolution: value })}+ className={`flex-1 px-2 py-1.5 rounded-lg border text-[11px] transition-colors ${+ options.resolution === value+ ? 'border-accent text-accent'+ : 'border-border text-muted-foreground hover:border-accent hover:text-foreground'+ }`}+ >+ {i18n.t(`exportPreview.res_${value}`)}+ </button>+ ))}+ </div>+ </div>+ )}+<div className="pt-3 border-t border-border space-y-1.5">- {formats.map(({ key, icon: Icon, label }) => (- <Button- key={key}- size="sm"- variant="ghost"- disabled={exporting !== null}- onClick={() => handleExport(key)}- className="w-full justify-start gap-2 border border-border hover:border-accent"- >- {exporting === key ? <Loader2 size={14} className="animate-spin" /> : <Icon size={14} />}- {i18n.t('exportPreview.download', [label])}- </Button>- ))}+ {formats.map(({ key, icon: Icon, label }) => {+ const cancellable = exporting === key && key === 'video';+ return (+ <Button+ key={key}+ size="sm"+ variant="ghost"+ disabled={exporting !== null && !cancellable}+ onClick={() => (cancellable ? downloadAbort.current?.abort() : handleExport(key))}+ className="w-full justify-start gap-2 border border-border hover:border-accent"+ >+ {exporting === key ? <Loader2 size={14} className="animate-spin" /> : <Icon size={14} />}+ {cancellable+ ? i18n.t('exportMenu.cancelProgress', [String(Math.round(downloadProgress * 100))])+ : i18n.t('exportPreview.download', [label])}+ </Button>+ );+ })}</div></div>@@ -307,15 +358,9 @@ export default function ExportPreviewModal({ open, onOpenChange, guide, steps, s<div className="mt-1 text-[11px] text-muted-foreground leading-snug">{videoError}</div></div>) : videoUrl ? (- <video- key={videoUrl}- src={videoUrl}- controls- autoPlay- muted- loop- className="w-full h-full object-contain"- />+ <Suspense fallback={null}>+ <VideoStepPlayer key={videoUrl} src={videoUrl} chapters={videoChapters} />+ </Suspense>) : (<div className="flex flex-col items-center gap-2 bg-card border border-border rounded-xl px-4 py-3"><div className="text-[11px] text-muted-foreground">{i18n.t('exportPreview.encodingVideo')}</div>diff --git a/src/ui/fullview/VideoStepPlayer.tsx b/src/ui/fullview/VideoStepPlayer.tsxnew file mode 100644index 0000000..b678bfc--- /dev/null+++ b/src/ui/fullview/VideoStepPlayer.tsx@@ -0,0 +1,161 @@+import {+ FullscreenButton,+ MediaPlayer,+ MediaProvider,+ PlayButton,+ useMediaRemote,+ useMediaState,+} from '@vidstack/react';+import { ChevronLeft, ChevronRight, Maximize, Minimize, Pause, Play } from 'lucide-react';+import { useEffect, useRef } from 'react';+import { i18n } from '#imports';+import type { StepKind, VideoChapter } from '@/core/export/video-export';++const RATES = [1, 1.25, 1.5, 2];++const KIND_DOT: Record<StepKind, string> = {+ click: 'bg-accent',+ type: 'bg-violet-light',+ key: 'bg-violet',+ navigate: 'bg-lavender',+ note: 'bg-muted-foreground',+};++interface VideoStepPlayerProps {+ src: string;+ chapters: VideoChapter[];+}++function formatClock(seconds: number): string {+ const total = Number.isFinite(seconds) ? Math.max(0, Math.round(seconds)) : 0;+ return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;+}++function activeIndex(chapters: VideoChapter[], time: number): number {+ for (let i = chapters.length - 1; i >= 0; i--) {+ if (time >= chapters[i].start) return i;+ }+ return -1;+}++function StepList({+ chapters,+ index,+ onJump,+}: {+ chapters: VideoChapter[];+ index: number;+ onJump: (n: number) => void;+}) {+ const list = useRef<HTMLElement>(null);++ useEffect(() => {+ list.current?.querySelectorAll('button')[index]?.scrollIntoView({ block: 'nearest' });+ }, [index]);++ return (+ <aside ref={list} className="w-[228px] shrink-0 overflow-y-auto border-l border-white/10 bg-[#141232]">+ <div className="px-3 pb-2 pt-3 font-mono text-[9px] uppercase tracking-[0.1em] text-white/45">+ {i18n.t('videoPlayer.stepCount', [String(chapters.length)])}+ </div>+ {chapters.map((chapter, i) => (+ <button+ key={chapter.stepId}+ type="button"+ onClick={() => onJump(i)}+ className={`flex w-full items-start gap-2.5 border-l-2 px-3 py-1.5 text-left transition-colors ${+ i === index ? 'border-l-accent bg-white/10' : 'border-l-transparent hover:bg-white/5'+ }`}+ >+ <span className={`mt-1.5 size-1.5 shrink-0 rounded-full ${KIND_DOT[chapter.kind]}`} />+ <span className="min-w-0 flex-1 text-[10.5px] leading-snug text-white/80">{chapter.title}</span>+ <span className="pt-0.5 font-mono text-[9px] tabular-nums text-white/40">{formatClock(chapter.start)}</span>+ </button>+ ))}+ </aside>+ );+}++function PlayerBody({ chapters }: { chapters: VideoChapter[] }) {+ const remote = useMediaRemote();+ const time = useMediaState('currentTime');+ const duration = useMediaState('duration');+ const rate = useMediaState('playbackRate');+ const paused = useMediaState('paused');+ const fullscreen = useMediaState('fullscreen');++ const index = activeIndex(chapters, time);+ const seekTo = (seconds: number) => remote.seek(Math.max(0, seconds + 0.01));+ const jump = (i: number) => chapters[i] && seekTo(chapters[i].start);++ return (+ <>+ <div className="relative min-w-0 flex-1">+ <MediaProvider className="size-full [&_video]:size-full [&_video]:object-contain" />++ <div className="absolute inset-x-0 bottom-0 flex items-center gap-2 bg-gradient-to-t from-black/85 to-transparent px-3 pb-2.5 pt-8 text-white">+ <PlayButton className="rounded-md p-1 hover:bg-white/15">+ {paused ? <Play size={16} fill="currentColor" /> : <Pause size={16} fill="currentColor" />}+ </PlayButton>++ <button+ type="button"+ disabled={index <= 0}+ onClick={() => jump(index - 1)}+ aria-label={i18n.t('videoPlayer.previousStep')}+ className="rounded-md p-1 hover:bg-white/15 disabled:opacity-35 disabled:hover:bg-transparent"+ >+ <ChevronLeft size={16} />+ </button>+ <button+ type="button"+ disabled={index < 0 || index >= chapters.length - 1}+ onClick={() => jump(index + 1)}+ aria-label={i18n.t('videoPlayer.nextStep')}+ className="rounded-md p-1 hover:bg-white/15 disabled:opacity-35 disabled:hover:bg-transparent"+ >+ <ChevronRight size={16} />+ </button>++ <span className="font-mono text-[11px] tabular-nums text-white/75">+ {formatClock(time)} / {formatClock(duration)}+ </span>++ <span className="flex-1" />++ <button+ type="button"+ onClick={() => remote.changePlaybackRate(RATES[(RATES.indexOf(rate) + 1) % RATES.length])}+ aria-label={i18n.t('videoPlayer.speed')}+ className="rounded-md px-1.5 py-1 font-mono text-[11px] tabular-nums hover:bg-white/15"+ >+ {rate}x+ </button>++ <FullscreenButton className="rounded-md p-1 hover:bg-white/15">+ {fullscreen ? <Minimize size={16} /> : <Maximize size={16} />}+ </FullscreenButton>+ </div>+ </div>++ {chapters.length > 0 && <StepList chapters={chapters} index={index} onJump={jump} />}+ </>+ );+}++export default function VideoStepPlayer({ src, chapters }: VideoStepPlayerProps) {+ return (+ <MediaPlayer+ src={{ src, type: 'video/mp4' }}+ autoPlay+ muted+ playsInline+ load="eager"+ viewType="video"+ streamType="on-demand"+ className="flex size-full bg-[#0E0C28]"+ >+ <PlayerBody chapters={chapters} />+ </MediaPlayer>+ );+}diff --git a/src/ui/fullview/__tests__/ExportPreviewModal.test.tsx b/src/ui/fullview/__tests__/ExportPreviewModal.test.tsxindex b63e554..1fa156a 100644--- a/src/ui/fullview/__tests__/ExportPreviewModal.test.tsx+++ b/src/ui/fullview/__tests__/ExportPreviewModal.test.tsx@@ -9,6 +9,7 @@ const exportGuideAsHTML = vi.hoisted(() => vi.fn());const canExportVideo = vi.hoisted(() => vi.fn());vi.mock('@/core/export/video-export', () => ({ exportGuideAsVideo }));+vi.mock('@/ui/fullview/VideoStepPlayer', () => ({ default: () => <div data-testid="video-player" /> }));vi.mock('@/core/export/html-export', () => ({ exportGuideAsHTML }));vi.mock('@/core/export/video-support', async (importOriginal) => ({...(await importOriginal<typeof import('@/core/export/video-support')>()),@@ -59,7 +60,7 @@ describe('ExportPreviewModal video preview', () => {vi.clearAllMocks();canExportVideo.mockResolvedValue(true);exportGuideAsHTML.mockResolvedValue('<html lang="en"><head></head><body></body></html>');- exportGuideAsVideo.mockResolvedValue({ blob: new Blob(['video']), extension: 'mp4' });+ exportGuideAsVideo.mockResolvedValue({ blob: new Blob(['video']), extension: 'mp4', chapters: [] });URL.createObjectURL = vi.fn(() => 'blob:video');URL.revokeObjectURL = vi.fn();});diff --git a/src/ui/sidepanel/ExportMenu.tsx b/src/ui/sidepanel/ExportMenu.tsxindex f594154..e0776c7 100644--- a/src/ui/sidepanel/ExportMenu.tsx+++ b/src/ui/sidepanel/ExportMenu.tsx@@ -28,7 +28,9 @@ export default function ExportMenu({const [open, setOpen] = useState(false);const [exporting, setExporting] = useState(false);const [videoSupported, setVideoSupported] = useState(false);+ const [videoProgress, setVideoProgress] = useState<number | null>(null);const menuRef = useRef<HTMLDivElement>(null);+ const videoAbort = useRef<AbortController | null>(null);useEffect(() => {let active = true;@@ -67,13 +69,23 @@ export default function ExportMenu({const md = await exportGuideAsMarkdown(guide, steps, screenshots);downloadText(md, safeFilename(guide.title, 'md'), 'text/markdown');} else if (type === 'video') {+ const controller = new AbortController();+ videoAbort.current = controller;+ setVideoProgress(0);const { exportGuideAsVideo } = await import('@/core/export/video-export');- const { blob, extension } = await exportGuideAsVideo(guide, steps, screenshots);+ const { blob, extension } = await exportGuideAsVideo(guide, steps, screenshots, undefined, {+ signal: controller.signal,+ onProgress: (encoded, frames) => setVideoProgress(frames > 0 ? encoded / frames : 0),+ });downloadBlob(blob, safeFilename(guide.title, extension));} else {downloadBlob(await exportGuideAsPDF(guide, steps, screenshots), safeFilename(guide.title, 'pdf'));}+ } catch (error) {+ if (!(error instanceof DOMException && error.name === 'AbortError')) throw error;} finally {+ videoAbort.current = null;+ setVideoProgress(null);setExporting(false);}}@@ -88,9 +100,15 @@ export default function ExportMenu({return (<div ref={menuRef} className="relative">- <Button size="sm" onClick={() => setOpen((prev) => !prev)} disabled={exporting}>+ <Button+ size="sm"+ onClick={() => (videoProgress === null ? setOpen((prev) => !prev) : videoAbort.current?.abort())}+ disabled={exporting && videoProgress === null}+ >{exporting ? <Loader2 size={14} className="animate-spin" /> : <Download size={14} />}- {i18n.t('common.export')}+ {videoProgress === null+ ? i18n.t('common.export')+ : i18n.t('exportMenu.cancelProgress', [String(Math.round(videoProgress * 100))])}</Button>{open && !exporting && (