@yassine-bouassida/scenecap 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Yassine Bouassida
+
+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

@@ -0,0 +1,183 @@
+# Scenecap
+
+Record scripted screen scenarios as MP4/WebM videos directly from your React app — entirely in the browser, zero backend.
+
+Describe what should happen in **plain English**, and Scenecap parses it, executes the actions on-screen (virtual cursor, animations, zoom, annotations), and captures everything into a downloadable video file.
+
+> Think of it as "Playwright meets screen recorder meets annotation tool" — but running entirely in the browser.
+
+---
+
+## Installation
+
+```bash
+npm install scenecap
+```
+
+---
+
+## Quick Start
+
+### React Hook (recommended for Next.js)
+
+```tsx
+'use client';
+import { useScenecap } from 'scenecap';
+
+export default function MyPage() {
+  const { containerRef, record, download, isRecording, progress } = useScenecap();
+
+  const handleRecord = async () => {
+    await record(`
+      Click the "Login" button
+      Type "user@mail.com" in the email input
+      Zoom in on the password field
+      Circle the submit button in red
+    `);
+    download('my-demo.webm');
+  };
+
+  return (
+    <>
+      <button onClick={handleRecord} disabled={isRecording}>
+        {isRecording ? `${Math.round(progress)}%` : 'Record'}
+      </button>
+      <div ref={containerRef}>
+        {/* your UI */}
+      </div>
+    </>
+  );
+}
+```
+
+### Vanilla JS / Imperative
+
+```ts
+import { createScenecap } from 'scenecap';
+
+const sc = createScenecap({ recording: { fps: 30 } });
+const blob = await sc.record(`
+  Click the signup button
+  Type "hello" in the name field
+`, document.getElementById('app')!);
+
+const a = document.createElement('a');
+a.href = URL.createObjectURL(blob);
+a.download = 'recording.webm';
+a.click();
+```
+
+### Structured Scenario (skip NLP)
+
+```ts
+import { ScenarioRunner } from 'scenecap';
+
+const runner = new ScenarioRunner();
+const blob = await runner.recordScenario({
+  name: 'Login Flow',
+  actions: [
+    { type: 'click', target: '#login-btn' },
+    { type: 'type', target: 'input[name="email"]', value: 'test@test.com' },
+    { type: 'zoom', target: '#submit', zoomLevel: 2.0 },
+    { type: 'circle', target: '#submit', color: '#ff0000' },
+  ],
+}, containerEl);
+```
+
+---
+
+## Supported Actions
+
+| What you write | What it does |
+|---|---|
+| `Click the "Submit" button` | Clicks element by text content |
+| `Type "hello" in the email field` | Keystroke-by-keystroke typing |
+| `Zoom in on the navbar to 200%` | Smooth CSS transform zoom |
+| `Zoom out` | Resets zoom to 100% |
+| `Circle the logo in red` | Animated ellipse with glow effect |
+| `Highlight the error message in yellow` | Semi-transparent overlay |
+| `Draw an arrow to the submit button` | Animated arrow pointing to element |
+| `Add text "Click here!" near the button` | Pill-shaped label |
+| `Scroll down 500px` | Smooth scroll by pixel amount |
+| `Scroll to the footer` | Scrolls element into view |
+| `Hover over the menu` | Dispatches mouseenter/mouseover |
+| `Wait 2 seconds` | Pauses execution |
+| `Navigate to /dashboard` | Changes window location |
+| `Take a screenshot` | White flash effect |
+
+---
+
+## Configuration
+
+```ts
+createScenecap({
+  recording: {
+    format: 'webm',         // 'webm' | 'mp4' (mp4 depends on browser support)
+    fps: 30,
+    videoBitrate: 5_000_000,
+    width: 1280,
+    height: 720,
+    audio: false,
+    backgroundColor: '#ffffff',
+    devicePixelRatio: 1,
+  },
+  annotations: {
+    circleColor: '#ff3b30',
+    highlightColor: '#ffcc02',
+    arrowColor: '#ff3b30',
+    textColor: '#1a1a1a',
+    thickness: 3,
+  },
+  animation: {
+    defaultDuration: 800,   // ms per action
+    defaultEasing: 'ease-in-out',
+    zoomDuration: 600,
+  },
+  callbacks: {
+    onActionStart: (action, index) => {},
+    onActionComplete: (action, index) => {},
+    onProgress: (percent) => {},
+    onError: (error) => {},
+    onComplete: (blob) => {},
+  },
+});
+```
+
+---
+
+## Browser Requirements
+
+| API | Minimum versions |
+|---|---|
+| MediaRecorder | Chrome 49+, Firefox 25+, Edge 79+, Safari 14.1+ |
+| Canvas captureStream | Chrome 51+, Firefox 43+, Edge 79+, Safari 14.1+ |
+
+Does **not** work in Node.js / SSR — all recording logic is browser-only.
+
+---
+
+## Known Limitations
+
+- **DOM fidelity**: The SVG foreignObject approach doesn't capture cross-origin images, iframes, or some CSS effects (backdrop-filter, complex shadows).
+- **MP4 output**: MediaRecorder natively outputs WebM. True MP4 requires ffmpeg.wasm (not yet integrated).
+- **NLP parser**: Regex-based — handles common phrasings well but won't understand arbitrary sentences.
+- **No iframe support**: Can only record elements within the same document.
+- **Single-tab only**: Cross-page navigations will break the recording session.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build   # compile to dist/ (CJS + ESM + types)
+npm run dev     # watch mode
+npm run lint
+npm run test
+```
+
+---
+
+## License
+
+MIT — free for personal and commercial use.

package/dist/index.d.mts

@@ -0,0 +1,376 @@
+type ActionType = 'click' | 'type' | 'scroll' | 'hover' | 'wait' | 'zoom' | 'circle' | 'highlight' | 'arrow' | 'annotate' | 'navigate' | 'screenshot';
+interface ScenarioAction {
+    /** The type of action to perform */
+    type: ActionType;
+    /** CSS selector or natural language description of the target element */
+    target?: string;
+    /** Value for type actions, text for annotations, URL for navigate */
+    value?: string;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Delay before executing this action (ms) */
+    delay?: number;
+    /** Zoom level for zoom actions (1.0 = 100%) */
+    zoomLevel?: number;
+    /** Color for annotations/highlights (CSS color string) */
+    color?: string;
+    /** Thickness for circles/arrows (px) */
+    thickness?: number;
+    /** Position offset for annotations */
+    offset?: {
+        x: number;
+        y: number;
+    };
+    /** Easing function for animations */
+    easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+}
+interface Scenario {
+    /** Unique name for this scenario */
+    name: string;
+    /** Description of what this scenario demonstrates */
+    description?: string;
+    /** The URL to start recording from */
+    startUrl?: string;
+    /** Viewport width */
+    viewportWidth?: number;
+    /** Viewport height */
+    viewportHeight?: number;
+    /** Ordered list of actions to perform */
+    actions: ScenarioAction[];
+}
+interface RecordingOptions {
+    /** Output format */
+    format: 'webm' | 'mp4';
+    /** Frames per second */
+    fps: number;
+    /** Video bitrate in bits/s */
+    videoBitrate: number;
+    /** Viewport dimensions */
+    width: number;
+    height: number;
+    /** Whether to record audio */
+    audio: boolean;
+    /** Background color */
+    backgroundColor: string;
+    /** Device pixel ratio (for retina) */
+    devicePixelRatio: number;
+}
+interface RecordingSession {
+    /** Unique session ID */
+    id: string;
+    /** The scenario being recorded */
+    scenario: Scenario;
+    /** Recording options */
+    options: RecordingOptions;
+    /** Current status */
+    status: 'idle' | 'preparing' | 'recording' | 'processing' | 'complete' | 'error';
+    /** Progress 0-100 */
+    progress: number;
+    /** Error message if failed */
+    error?: string;
+    /** The final video blob */
+    result?: Blob;
+}
+interface OverlayAnnotation {
+    id: string;
+    type: 'circle' | 'highlight' | 'arrow' | 'text' | 'zoom-indicator';
+    target: DOMRect;
+    color: string;
+    thickness: number;
+    text?: string;
+    opacity: number;
+    /** Animation progress 0-1 */
+    animProgress: number;
+}
+interface ParsedInstruction {
+    raw: string;
+    action: ScenarioAction;
+    confidence: number;
+}
+interface ScenecapCallbacks {
+    onActionStart?: (action: ScenarioAction, index: number) => void;
+    onActionComplete?: (action: ScenarioAction, index: number) => void;
+    onProgress?: (progress: number) => void;
+    onError?: (error: Error) => void;
+    onComplete?: (blob: Blob) => void;
+}
+interface ScenecapConfig {
+    /** Default recording options */
+    recording?: Partial<RecordingOptions>;
+    /** Default annotation styles */
+    annotations?: {
+        circleColor?: string;
+        highlightColor?: string;
+        arrowColor?: string;
+        textColor?: string;
+        thickness?: number;
+        fontFamily?: string;
+        fontSize?: number;
+    };
+    /** Animation defaults */
+    animation?: {
+        defaultDuration?: number;
+        defaultEasing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+        zoomDuration?: number;
+    };
+    /** Callbacks */
+    callbacks?: ScenecapCallbacks;
+}
+
+declare class ScenarioRunner {
+    private config;
+    private callbacks;
+    private session;
+    private overlay;
+    private recorder;
+    private zoom;
+    private cursor;
+    constructor(config?: Partial<ScenecapConfig>);
+    /**
+     * Record a scenario described in natural language.
+     *
+     * @param script - Natural language description of the scenario
+     * @param container - The DOM element to record
+     * @param options - Additional scenario options
+     * @returns The recorded video as a Blob
+     *
+     * @example
+     * ```ts
+     * const blob = await runner.record(`
+     *   Click on the "Sign Up" button
+     *   Type "john@email.com" in the email field
+     *   Zoom in on the submit button
+     *   Circle the success message in green
+     * `, document.getElementById('app')!);
+     * ```
+     */
+    record(script: string, container: HTMLElement, options?: {
+        name?: string;
+        description?: string;
+        startUrl?: string;
+    }): Promise<Blob>;
+    /**
+     * Record a structured scenario object.
+     */
+    recordScenario(scenario: Scenario, container: HTMLElement): Promise<Blob>;
+    /**
+     * Parse a natural language script without recording (for previewing).
+     */
+    parse(script: string): Scenario;
+    /**
+     * Get current session info.
+     */
+    getSession(): RecordingSession | null;
+    private executeAction;
+    private cleanup;
+}
+
+/**
+ * Records a DOM element to a video file using the Canvas capture API.
+ * This captures the visual output of a container element frame-by-frame.
+ */
+declare class VideoRecorder {
+    private options;
+    private mediaRecorder;
+    private chunks;
+    private canvas;
+    private stream;
+    private captureInterval;
+    constructor(options?: Partial<RecordingOptions>);
+    /**
+     * Start recording from a canvas element.
+     */
+    startFromCanvas(canvas: HTMLCanvasElement): Promise<void>;
+    /**
+     * Start recording a DOM element by continuously painting it to a canvas.
+     */
+    startFromElement(element: HTMLElement): Promise<void>;
+    /**
+     * Stop recording and return the video blob.
+     */
+    stop(): Promise<Blob>;
+    private cleanup;
+    get isRecording(): boolean;
+}
+
+/**
+ * Manages viewport zoom transformations during recording.
+ * Uses CSS transforms on a container for smooth, GPU-accelerated zooming.
+ */
+declare class ZoomController {
+    private container;
+    private currentZoom;
+    private currentTranslateX;
+    private currentTranslateY;
+    constructor(container: HTMLElement);
+    /**
+     * Zoom into a specific element.
+     */
+    zoomTo(target: DOMRect, level?: number, duration?: number): Promise<void>;
+    /**
+     * Reset zoom to default.
+     */
+    resetZoom(duration?: number): Promise<void>;
+    get zoom(): number;
+    destroy(): void;
+}
+
+declare class AnnotationOverlay {
+    private canvas;
+    private ctx;
+    private annotations;
+    private animationFrame;
+    constructor(container: HTMLElement);
+    private resize;
+    addCircle(id: string, target: DOMRect, color?: string, thickness?: number): void;
+    addHighlight(id: string, target: DOMRect, color?: string, thickness?: number): void;
+    addArrow(id: string, target: DOMRect, color?: string, thickness?: number): void;
+    addText(id: string, target: DOMRect, text: string, color?: string): void;
+    addZoomIndicator(id: string, target: DOMRect): void;
+    remove(id: string): void;
+    clear(): void;
+    private startAnimation;
+    private stopAnimation;
+    private update;
+    private render;
+    private drawCircle;
+    private drawHighlight;
+    private drawArrow;
+    private drawText;
+    private drawZoomIndicator;
+    destroy(): void;
+}
+
+declare function parseInstruction(text: string): ParsedInstruction;
+declare function parseNaturalLanguageScenario(script: string, options?: {
+    name?: string;
+    description?: string;
+    startUrl?: string;
+}): Scenario;
+
+interface UseScenecapReturn {
+    /** Ref to attach to the container element you want to record */
+    containerRef: React.RefObject<HTMLElement>;
+    /** Record a natural language script */
+    record: (script: string, options?: {
+        name?: string;
+        description?: string;
+    }) => Promise<Blob | null>;
+    /** Record a structured scenario */
+    recordScenario: (scenario: Scenario) => Promise<Blob | null>;
+    /** Parse a script into a scenario (for previewing actions) */
+    parse: (script: string) => Scenario;
+    /** Download the last recording */
+    download: (filename?: string) => void;
+    /** Whether a recording is in progress */
+    isRecording: boolean;
+    /** Current progress 0-100 */
+    progress: number;
+    /** Current session info */
+    session: RecordingSession | null;
+    /** Last error, if any */
+    error: string | null;
+    /** The last recorded blob */
+    blob: Blob | null;
+}
+/**
+ * React hook for using Scenecap in Next.js / React projects.
+ *
+ * @example
+ * ```tsx
+ * function DemoRecorder() {
+ *   const { containerRef, record, isRecording, progress, download } = useScenecap();
+ *
+ *   const handleRecord = async () => {
+ *     await record(`
+ *       Click the "Get Started" button
+ *       Type "hello@example.com" in the email input
+ *       Zoom in on the submit button
+ *       Circle the success message in green
+ *     `);
+ *     download('demo.webm');
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleRecord} disabled={isRecording}>
+ *         {isRecording ? `Recording... ${progress}%` : 'Record Demo'}
+ *       </button>
+ *       <div ref={containerRef}>
+ *         {/* Your app UI here *\/}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useScenecap(config?: Partial<ScenecapConfig>): UseScenecapReturn;
+
+/**
+ * Resolves a CSS selector (including custom :has-text()) to a DOM element.
+ * Falls back through multiple strategies to find the best match.
+ */
+declare function resolveElement(selector: string, root?: Element): Element | null;
+/**
+ * Smoothly scrolls an element into view.
+ */
+declare function scrollIntoView(el: Element, smooth?: boolean): Promise<void>;
+/**
+ * Simulates a mouse click with visual feedback.
+ */
+declare function simulateClick(el: Element): void;
+/**
+ * Simulates typing text into an input field.
+ */
+declare function simulateType(el: Element, text: string, speed?: number): Promise<void>;
+
+/**
+ * Virtual cursor that appears in recordings.
+ * Renders a smooth macOS-style pointer that animates between targets.
+ */
+declare class VirtualCursor {
+    private el;
+    private x;
+    private y;
+    private visible;
+    constructor(container: HTMLElement);
+    show(): void;
+    hide(): void;
+    /**
+     * Smoothly move cursor to a position.
+     */
+    moveTo(targetX: number, targetY: number, duration?: number): Promise<void>;
+    /**
+     * Move to center of a DOM element.
+     */
+    moveToElement(el: Element, duration?: number): Promise<void>;
+    /**
+     * Click animation at current position.
+     */
+    clickAnimation(): Promise<void>;
+    destroy(): void;
+}
+
+/**
+ * Create a Scenecap instance with the given config.
+ *
+ * @example
+ * ```ts
+ * import { createScenecap } from 'scenecap';
+ *
+ * const sc = createScenecap({
+ *   recording: { format: 'webm', fps: 30 },
+ *   annotations: { circleColor: '#ff0000' },
+ * });
+ *
+ * const blob = await sc.record(`
+ *   Click on the login button
+ *   Type "admin" in the username field
+ *   Zoom in on the password field
+ *   Circle the submit button
+ * `, document.getElementById('app')!);
+ * ```
+ */
+declare function createScenecap(config?: Partial<ScenecapConfig>): ScenarioRunner;
+
+export { type ActionType, AnnotationOverlay, type OverlayAnnotation, type ParsedInstruction, type RecordingOptions, type RecordingSession, type Scenario, type ScenarioAction, ScenarioRunner, type ScenecapCallbacks, type ScenecapConfig, type UseScenecapReturn, VideoRecorder, VirtualCursor, ZoomController, createScenecap, parseInstruction, parseNaturalLanguageScenario, resolveElement, scrollIntoView, simulateClick, simulateType, useScenecap };