@spark-apps/quickpeek 1.0.1 → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Spark Apps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,101 +1,200 @@
-<div align="center">
-
-# QuickPeek Core
-
-**Core library for QuickPeek - AI-powered demo video generation**
-
-[![npm](https://img.shields.io/npm/v/@spark-apps/quickpeek?style=flat-square&logo=npm&logoColor=white&color=crimson)](https://www.npmjs.com/package/@spark-apps/quickpeek)
-[![MIT](https://img.shields.io/badge/License-MIT-blueviolet?style=flat-square)](../../LICENSE)
-
-</div>
-
----
-
-## Installation
-
-```bash
-npm install @spark-apps/quickpeek
-```
-
-## Overview
-
-This is the core library used by [`@spark-apps/quickpeek-cli`](https://www.npmjs.com/package/@spark-apps/quickpeek-cli). It provides:
-
-- **API Client** - Communication with QuickPeek backend for AI planning
-- **TTS Engine** - Text-to-speech via Edge TTS (60+ languages)
-- **FFmpeg Wrapper** - Video composition, watermarks, effects
-- **Prompt Builder** - System and user prompts for AI planning
-- **Web Crawler** - Page analysis for demo planning
-- **Utilities** - Caption styling, ASS subtitle generation, config management
-
-## Usage
-
-```typescript
-import {
-  callAI,
-  generateVoiceover,
-  composeVideo,
-  crawlPage,
-  buildSystemPrompt,
-  buildUserPrompt,
-  DEFAULT_CONFIG,
-  VERSION,
-} from '@spark-apps/quickpeek';
-
-// Crawl a page for interactive elements
-const { title, elements } = await crawlPage('https://example.com');
-
-// Generate AI demo plan
-const systemPrompt = buildSystemPrompt(8);
-const userPrompt = buildUserPrompt(url, title, elements, 'English', 'A todo app', 8);
-const result = await callAI(systemPrompt, userPrompt, 'user@email.com');
-
-// Generate voiceover
-const { voiceoverPath, stepAudio } = await generateVoiceover(
-  steps,
-  config,
-  workDir,
-  outputDir,
-  logError,
-  task,
-  info
-);
-
-// Compose final video
-await composeVideo({
-  videoPath,
-  assPath,
-  outputPath,
-  voiceoverPath,
-  musicPath,
-  // ... options
-});
-```
-
-## Exports
-
-| Module | Description |
-|--------|-------------|
-| `api-client` | Backend API communication |
-| `tts` | Text-to-speech generation |
-| `ffmpeg` | Video composition |
-| `prompts` | AI prompt templates |
-| `crawl` | Web page analysis |
-| `config` | Default configuration |
-| `utils` | ASS subtitles, color conversion |
-| `voices` | Voice mappings for 60+ languages |
-| `styles` | Caption styling |
-| `cursor` | Custom cursor CSS/JS |
-| `watermark` | Watermark generation |
-
-## Related Packages
-
-- [`@spark-apps/quickpeek-cli`](https://www.npmjs.com/package/@spark-apps/quickpeek-cli) - CLI tool
-
----
-
-<div align="center">
-
-MIT License - Made with ☕ by [Spark Apps](https://github.com/muammar-yacoob)
-
-</div>
+[license-link]: ./LICENSE
+[privacy-link]: ./PRIVACY.md
+[discord-link]: https://discord.gg/5skXfKRytR
+[stars-link]: ../../stargazers
+[issues-link]: ../../issues
+
+<div align="center">
+
+<img src=imgs/logo.png>
+
+**Demo videos for your web app with AI**
+
+*Because Tutorial Videos are Overrated!*
+
+[![npm](https://img.shields.io/npm/v/@spark-apps/quickpeek?style=flat-square&logo=npm&logoColor=white&color=crimson)](https://www.npmjs.com/package/@spark-apps/quickpeek)
+[![MIT](https://img.shields.io/badge/License-MIT-blueviolet?style=flat-square)][license-link]
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white)][discord-link]
+[![GitHub Stars](https://img.shields.io/github/stars/muammar-yacoob/quickpeek?style=flat-square)][stars-link]
+
+</div>
+
+---
+
+## Quick Start
+
+```bash
+npm install -g @spark-apps/quickpeek
+qp localhost:3000
+```
+
+**Requirements:** [ffmpeg](https://ffmpeg.org/download.html), [Groq API key](https://console.groq.com/keys) (free)
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **AI Planning** | Groq AI analyzes your app and generates demo steps |
+| **Script Mode** | Provide your own narration script, AI maps it to UI actions |
+| **Capture Mode** | Record your own interactions → replayable plan.json |
+| **Voice Over** | Free Edge TTS narration in 60+ languages |
+| **Karaoke Captions** | Word-by-word highlighted subtitles |
+| **Background Music** | Optional music with fade in/out |
+| **Smart Zoom** | Per-step zoom for focused demos |
+| **Chrome Extensions** | Record demos for Chrome extensions |
+
+## Examples
+
+### Basic — AI generates the plan
+
+```bash
+qp localhost:3000
+```
+
+### Script mode — you write the narration
+
+```bash
+qp localhost:3000 --script narration.txt
+```
+
+Script file format (one caption per line, `#` for comments):
+
+```
+# My app demo
+We start on the dashboard — your main workspace.
+Let's search for a customer by typing their name.
+Click the result to open their profile.
+```
+
+### Capture mode — record your own interactions
+
+```bash
+qp capture localhost:3000
+```
+
+Browse the app freely, press Enter when done. QuickPeek converts your clicks, typing, and scrolls into a `plan.json` that can be replayed as a polished video.
+
+### With options
+
+```bash
+qp localhost:3000 lang=es -d "A todo app for managing daily tasks"
+```
+
+### Chrome Extensions
+
+Record demos for Chrome extensions using the `chrome:` prefix:
+
+```bash
+qp chrome:your-extension-id
+```
+
+QuickPeek will automatically:
+1. Find the extension in your Chrome installation
+2. Load and analyze the extension popup UI
+3. Generate a demo plan with AI
+
+The popup URL is detected from the extension's manifest.
+
+| Option | Description |
+|--------|-------------|
+| `lang` | Voice language (en, es, ar, zh...) |
+| `-d, --description` | App description to guide AI |
+| `-s, --script` | Path to narration script file |
+| `video.width/height` | Resolution (default: 1080x1920) |
+| `video.quality` | Quality 0-1 (default: 0.5) |
+| `music.path` | Background music file |
+| `music.volume` | Music volume 0-1 (default: 0.3) |
+| `output.dir` | Output directory (default: ./demo) |
+
+Config is auto-generated on first run. Edit `quickpeek.config.json` to customize.
+
+<details>
+<summary><strong>Supported Languages</strong></summary>
+
+| Code | Language | Code | Language |
+|------|----------|------|----------|
+| `en` | English | `ar` | Arabic |
+| `es` | Spanish | `fr` | French |
+| `de` | German | `zh` | Chinese |
+| `ja` | Japanese | `ko` | Korean |
+| `pt` | Portuguese | `hi` | Hindi |
+| `it` | Italian | `ru` | Russian |
+
+See `src/voices.ts` for all 60+ supported languages.
+
+</details>
+
+<details>
+<summary><strong>Caption Style</strong></summary>
+
+Edit `captions.css` (auto-generated) to customize:
+
+![Classic Yellow](imgs/caption-classic.png)
+
+```css
+.caption {
+  font-family: Arial, sans-serif;
+  -webkit-text-stroke: 3px #000000;
+}
+.caption .regular {
+  font-size: 56px;
+  color: #FFFFFF;
+}
+.caption .highlight {
+  font-size: 64px;
+  color: #FFFF00;
+}
+```
+
+</details>
+
+## Plan Actions
+
+Edit `demo/plan.json` to customize your demo. Each step uses one of these actions:
+
+| Action | Target | Value | Description |
+|--------|--------|-------|-------------|
+| `wait` | - | - | Pause for narration (intro/outro) |
+| `click` | `"button text"` | - | Click button/link |
+| `click-N` | `"button text"` | - | Click N times (e.g., `click-2`, `click-3`) |
+| `type` | `input[name="field"]` | `"text to type"` | Type into input field |
+| `upload` | `input[type="file"]` | `"path/to/file"` | Upload file to form |
+| `select` | `select[name="field"]` | `"option text"` | Select dropdown option |
+| `check` | `input[type="checkbox"]` | - | Toggle checkbox |
+| `drag` | `input[type="range"]` | `"0"`-`"100"` | Drag slider to value |
+| `drag` | `canvas` | `"around"` | Full 360° rotation (returns to start) |
+| `drag` | `canvas` | `"rotate"` | Rotate ~270° (stays at new angle) |
+| `drag` | `canvas` | `"rotate:90"` | Rotate specific angle (circular) |
+| `drag` | `canvas` | `"rotate:x-90"` | Rotate on X axis (horizontal drag) |
+| `drag` | `canvas` | `"rotate:y45"` | Rotate on Y axis (vertical drag) |
+| `drag` | - | `"left"` `"right"` `"up"` `"down"` | Directional drag |
+| `scroll` | - | `"up"` `"down"` `"bottom"` | Scroll page |
+| `scroll` | - | `"-10"` to `"10"` | Zoom camera (negative=out, positive=in) |
+| `media` | `"scale"` or `"center"` | `"path/to/file"` | Display image/video fullscreen |
+| `showDownload` | - | - | Show the last downloaded file |
+
+**Target shortcuts:** For buttons and links, use simplified text like `"download"` or `"extract frame"` instead of CSS selectors.
+
+## Output
+
+| File | Description |
+|------|-------------|
+| `demo/demo.mp4` | Final video |
+| `demo/plan.json` | Editable script (re-run to apply changes) |
+
+## 🌱 Support & Contributions
+
+⭐ **Star the repo** & I power up like Mario 🍄  
+☕ **Devs run on coffee** - [Buy me one?][coffee-link]  
+💖 **Sponsor** [Your support][stars-link] helps maintain and improve the tool<br>
+💰 **Crypto tips welcome** - [Tip in crypto](https://tip.md/muammar-yacoob)  
+🤝 **Contributions are welcome** - [🍴 Fork][fork-link], improve, PR!  
+🎥 **Need help?** <img src="https://img.icons8.com/color/20/youtube-play.png" alt="YouTube" width="20" height="20" style="vertical-align: middle;"> [Setup Tutorial][vid-link] • <img src="https://img.icons8.com/color/20/discord--v2.png" alt="Discord" width="20" height="20" style="vertical-align: middle;"> [Join Discord][discord-link]
+
+<div align="center">
+
+---
+
+MIT License - Made with ☕ by [Spark Apps](https://github.com/muammar-yacoob)
+
+</div>

package/dist/highlight.css

@@ -0,0 +1,15 @@
+#qp-highlight-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.5);
+  z-index: 999998;
+  pointer-events: none;
+}
+
+[data-qp-highlight] {
+  position: relative !important;
+  z-index: 999999 !important;
+  outline: 3px solid #ffd700 !important;
+  outline-offset: 2px !important;
+  border-radius: 8px !important;
+}