clipwise 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -492,6 +492,7 @@ declare const OutputConfigSchema: z.ZodObject<{
     height: z.ZodDefault<z.ZodNumber>;
     fps: z.ZodDefault<z.ZodNumber>;
     quality: z.ZodDefault<z.ZodNumber>;
+    preset: z.ZodOptional<z.ZodEnum<["social", "balanced", "archive"]>>;
     outputDir: z.ZodDefault<z.ZodString>;
     filename: z.ZodDefault<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
@@ -502,12 +503,14 @@ declare const OutputConfigSchema: z.ZodObject<{
     quality: number;
     outputDir: string;
     filename: string;
+    preset?: "social" | "balanced" | "archive" | undefined;
 }, {
     format?: "gif" | "mp4" | "webm" | "png-sequence" | undefined;
     width?: number | undefined;
     height?: number | undefined;
     fps?: number | undefined;
     quality?: number | undefined;
+    preset?: "social" | "balanced" | "archive" | undefined;
     outputDir?: string | undefined;
     filename?: string | undefined;
 }>;
@@ -1146,6 +1149,7 @@ declare const ScenarioSchema: z.ZodObject<{
         height: z.ZodDefault<z.ZodNumber>;
         fps: z.ZodDefault<z.ZodNumber>;
         quality: z.ZodDefault<z.ZodNumber>;
+        preset: z.ZodOptional<z.ZodEnum<["social", "balanced", "archive"]>>;
         outputDir: z.ZodDefault<z.ZodString>;
         filename: z.ZodDefault<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
@@ -1156,12 +1160,14 @@ declare const ScenarioSchema: z.ZodObject<{
         quality: number;
         outputDir: string;
         filename: string;
+        preset?: "social" | "balanced" | "archive" | undefined;
     }, {
         format?: "gif" | "mp4" | "webm" | "png-sequence" | undefined;
         width?: number | undefined;
         height?: number | undefined;
         fps?: number | undefined;
         quality?: number | undefined;
+        preset?: "social" | "balanced" | "archive" | undefined;
         outputDir?: string | undefined;
         filename?: string | undefined;
     }>>;
@@ -1543,6 +1549,7 @@ declare const ScenarioSchema: z.ZodObject<{
         quality: number;
         outputDir: string;
         filename: string;
+        preset?: "social" | "balanced" | "archive" | undefined;
     };
     steps: {
         actions: ({
@@ -1749,6 +1756,7 @@ declare const ScenarioSchema: z.ZodObject<{
         height?: number | undefined;
         fps?: number | undefined;
         quality?: number | undefined;
+        preset?: "social" | "balanced" | "archive" | undefined;
         outputDir?: string | undefined;
         filename?: string | undefined;
     } | undefined;
@@ -1775,6 +1783,8 @@ interface CapturedFrame {
         width: number;
         height: number;
     };
+    /** Device pixel ratio used during capture (1 = normal, 2 = Retina/HiDPI). */
+    deviceScaleFactor?: number;
     stepName?: string;
     stepIndex?: number;
     actionType?: string;
@@ -1804,6 +1814,7 @@ declare class ClipwiseRecorder {
     private currentStepIndex;
     private cursorPosition;
     private viewport;
+    private deviceScaleFactor;
     private isCapturing;
     private targetFps;
     private cursorSpeed;
@@ -1868,6 +1879,11 @@ declare class ClipwiseRecorder {
      * Interpolate cursor position at a given timestamp using the cursor timeline.
      */
     private interpolateCursorAt;
+    /**
+     * Binary search: returns the index of the last entry whose timestamp <= target.
+     * Assumes the array is sorted by timestamp in ascending order.
+     */
+    private binarySearchTimeline;
     /**
      * Clean up browser resources. Always called after recording.
      */
@@ -1882,25 +1898,15 @@ interface FrameContext {
         y: number;
     }>;
 }
+
 declare class CanvasRenderer {
     private effects;
     private output;
     private steps;
     constructor(effects: EffectsConfig, output: OutputConfig, steps?: Step[]);
     /**
-     * Apply the full effects pipeline to a single captured frame.
-     *
-     * Pipeline order:
-     *  1. Device frame (browser chrome / mobile mockup)
-     *  2. Cursor highlight (Screen Studio glow)
-     *  3. Cursor trail
-     *  4. Cursor rendering
-     *  5. Click ripple effect (animated progress)
-     *  6. Keystroke HUD
-     *  7. Zoom (adaptive, cursor-following)
-     *  8. Background (padding, gradient, rounded corners)
-     *  9. Watermark overlay
-     *  10. Final resize
+     * Apply the full effects pipeline to a single frame.
+     * Delegates to the standalone composeFrame function.
      */
     composeFrame(frame: CapturedFrame, context?: Partial<FrameContext>): Promise<ComposedFrame>;
     /**
@@ -1909,22 +1915,25 @@ declare class CanvasRenderer {
      * Multi-pass approach:
      *   Pass 1: Speed ramping (adjust frame set).
      *   Pass 2: Calculate per-frame contexts (zoom, click, trail).
-     *   Pass 3: Render each frame with effects.
+     *   Pass 3: Render frames in parallel using worker threads.
      *   Pass 4: Apply scene transitions at step boundaries.
      */
     composeAll(frames: CapturedFrame[]): Promise<ComposedFrame[]>;
     /**
-     * Calculate per-frame rendering context (zoom, click progress, cursor trail, tilt).
+     * Distribute frame composition across a pool of worker threads.
+     * Workers process frames concurrently; results are collected in order.
+     */
+    private processWithWorkers;
+    /**
+     * Calculate per-frame rendering context (zoom scale, click progress, cursor trail).
      */
     private calculateFrameContexts;
     /**
      * Apply speed ramping: slow down near actions, speed up during idle.
-     * Returns a new frame array with frames duplicated or skipped.
      */
     private applySpeedRamp;
     /**
      * Apply crossfade transitions at step boundaries where configured.
-     * Modifies the composed array in-place.
      */
     private applyTransitions;
 }
@@ -1935,15 +1944,22 @@ declare class CanvasRenderer {
  */
 declare function encodeGif(frames: ComposedFrame[], config: OutputConfig): Promise<Buffer>;
 /**
- * Encode a sequence of composed frames into an MP4 file using ffmpeg.
- * Writes frames as PNG sequence to a temp directory, then runs ffmpeg.
+ * Encode a sequence of composed frames into an MP4 buffer.
+ *
+ * Uses FFmpeg stdin piping (raw video) to eliminate disk I/O overhead.
+ * Encoder priority: hevc_videotoolbox (macOS HEVC HW) → h264_videotoolbox
+ * (macOS H.264 HW) → libx264 (software fallback).
+ *
+ * Encoding quality is controlled by the output.preset field:
+ *   social   — screen-recording quality, ~2–4 MB / 30s
+ *   balanced — high fidelity, ~4–8 MB / 30s
+ *   archive  — near-lossless, uncapped bitrate
  *
  * Requires ffmpeg to be installed and available in PATH.
  */
 declare function encodeMp4(frames: ComposedFrame[], config: OutputConfig): Promise<Buffer>;
 /**
  * Save a sequence of composed frames as individual PNG files.
- * Returns an array of file paths for the saved images.
  */
 declare function savePngSequence(frames: ComposedFrame[], config: OutputConfig): Promise<string[]>;
 
@@ -1982,26 +1998,28 @@ declare function lerpZoom(current: number, target: number, factor: number): numb
 type CursorEffect = EffectsConfig["cursor"];
 /**
  * Render a glowing highlight circle around the cursor (Screen Studio style).
+ * @param dpr - Device pixel ratio (default 1). Scales position and size for HiDPI.
  */
 declare function renderCursorHighlight(frameBuffer: Buffer, position: {
     x: number;
     y: number;
-}, config: CursorEffect, frameWidth: number, frameHeight: number): Promise<Buffer>;
+}, config: CursorEffect, frameWidth: number, frameHeight: number, dpr?: number): Promise<Buffer>;
 /**
  * Render a cursor trail (fading line segments following cursor path).
  * Each segment fades from transparent (oldest) to opaque (newest).
+ * @param dpr - Device pixel ratio (default 1). Scales positions for HiDPI.
  */
 declare function renderCursorTrail(frameBuffer: Buffer, positions: Array<{
     x: number;
     y: number;
-}>, config: CursorEffect, frameWidth: number, frameHeight: number): Promise<Buffer>;
+}>, config: CursorEffect, frameWidth: number, frameHeight: number, dpr?: number): Promise<Buffer>;
 
 type KeystrokeConfig = EffectsConfig["keystroke"];
 /**
  * Render a keystroke HUD overlay showing recently typed keys.
  * Inspired by KeyCastr / CursorClip.
  */
-declare function renderKeystrokeHud(frameBuffer: Buffer, keystrokes: KeystrokeEvent[], frameTimestamp: number, config: KeystrokeConfig, frameWidth: number, frameHeight: number): Promise<Buffer>;
+declare function renderKeystrokeHud(frameBuffer: Buffer, keystrokes: KeystrokeEvent[], frameTimestamp: number, config: KeystrokeConfig, frameWidth: number, frameHeight: number, dpr?: number): Promise<Buffer>;
 
 /**
  * Apply a crossfade transition between two frame buffers.