@sansavision/vidra-web-capture 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Shape of the `window.__vidra` bridge object injected by the
+ * capture harness (`capture.js`).
+ */
+export interface VidraBridge {
+    /** Whether the page is currently being captured by Vidra. */
+    capturing: boolean;
+    /** Current logical frame number (0-based). */
+    frame: number;
+    /** Current logical time in seconds. */
+    time: number;
+    /** Timeline frames-per-second. */
+    fps: number;
+    /** Arbitrary key/value variables passed from the project IR. */
+    vars: Record<string, number>;
+    /**
+     * Emit a value back to the Vidra capture engine.
+     * Useful for communicating computed values (e.g. layout metrics)
+     * from the web content back to the video project.
+     */
+    emit: (key: string, value: unknown) => void;
+}
+declare global {
+    interface Window {
+        __vidra?: VidraBridge;
+        __vidra_advance_frame?: () => void;
+    }
+}
+/**
+ * Return the current Vidra bridge state, or sensible defaults when
+ * not running inside a capture harness.
+ */
+export interface VidraState {
+    /** Whether we are inside the Vidra capture harness. */
+    capturing: boolean;
+    /** Current frame number (0 when standalone). */
+    frame: number;
+    /** Current time in seconds (real clock when standalone). */
+    time: number;
+    /** Timeline FPS (60 when standalone). */
+    fps: number;
+    /** Project variables (empty object when standalone). */
+    vars: Record<string, number>;
+    /**
+     * Emit a value back to the engine. No-op when standalone.
+     */
+    emit: (key: string, value: unknown) => void;
+}
+/**
+ * A lightweight, framework-agnostic class for reading the Vidra capture
+ * bridge and emitting values back.
+ *
+ * @example
+ * ```js
+ * const capture = new VidraCapture();
+ * const { frame, time, fps, vars, capturing } = capture.getState();
+ * console.log(capturing ? `Capturing frame ${frame}` : 'Standalone mode');
+ * capture.emit('layout_height', document.body.scrollHeight);
+ * ```
+ */
+export declare class VidraCapture {
+    private startTime;
+    constructor();
+    /**
+     * Return the current bridge state. If `window.__vidra` exists,
+     * values come from the harness. Otherwise, real-time defaults are
+     * returned so the page works normally in a browser.
+     */
+    getState(): VidraState;
+    /**
+     * Convenience: emit a value to the capture engine.
+     * Safe to call even when not in a capture harness (no-op).
+     */
+    emit(key: string, value: unknown): void;
+    /**
+     * Returns `true` if the page is currently being captured by Vidra.
+     */
+    isCapturing(): boolean;
+}
+export default VidraCapture;

package/dist/index.js

@@ -0,0 +1,69 @@
+// ─── @sansavision/vidra-web-capture ─────────────────────────────────
+//
+// This module provides the bridge between user-authored web content
+// (React components, vanilla HTML pages) and the Vidra capture harness.
+//
+// When running inside Vidra's capture harness (Playwright or CDP), the
+// global `window.__vidra` object is injected. This class reads from it
+// and provides typed access. When running standalone (normal browser),
+// it gracefully degrades to real-time defaults.
+// ─── VidraCapture (vanilla JS) ──────────────────────────────────────
+/**
+ * A lightweight, framework-agnostic class for reading the Vidra capture
+ * bridge and emitting values back.
+ *
+ * @example
+ * ```js
+ * const capture = new VidraCapture();
+ * const { frame, time, fps, vars, capturing } = capture.getState();
+ * console.log(capturing ? `Capturing frame ${frame}` : 'Standalone mode');
+ * capture.emit('layout_height', document.body.scrollHeight);
+ * ```
+ */
+export class VidraCapture {
+    constructor() {
+        this.startTime = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    }
+    /**
+     * Return the current bridge state. If `window.__vidra` exists,
+     * values come from the harness. Otherwise, real-time defaults are
+     * returned so the page works normally in a browser.
+     */
+    getState() {
+        const bridge = typeof window !== 'undefined' ? window.__vidra : undefined;
+        if (bridge && bridge.capturing) {
+            return {
+                capturing: true,
+                frame: bridge.frame,
+                time: bridge.time,
+                fps: bridge.fps,
+                vars: bridge.vars ?? {},
+                emit: bridge.emit ?? (() => { }),
+            };
+        }
+        // Graceful degradation — standalone mode
+        const elapsed = ((typeof performance !== 'undefined' ? performance.now() : Date.now()) - this.startTime) / 1000;
+        return {
+            capturing: false,
+            frame: 0,
+            time: elapsed,
+            fps: 60,
+            vars: {},
+            emit: () => { },
+        };
+    }
+    /**
+     * Convenience: emit a value to the capture engine.
+     * Safe to call even when not in a capture harness (no-op).
+     */
+    emit(key, value) {
+        this.getState().emit(key, value);
+    }
+    /**
+     * Returns `true` if the page is currently being captured by Vidra.
+     */
+    isCapturing() {
+        return typeof window !== 'undefined' && !!window.__vidra?.capturing;
+    }
+}
+export default VidraCapture;

package/dist/react.d.ts

@@ -0,0 +1,34 @@
+import { type VidraState } from './index.js';
+export interface UseVidraSceneOptions {
+    /**
+     * How often (in ms) to poll the bridge for updates when in
+     * standalone mode. Defaults to 16ms (~60fps).
+     * In capture mode the harness drives updates via postMessage,
+     * so this value is only used for the real-time fallback.
+     */
+    pollInterval?: number;
+}
+/**
+ * React hook for making a component Vidra-capturable.
+ *
+ * When running inside the Vidra capture harness, it returns the
+ * current frame/time/fps/vars from the injected `window.__vidra`
+ * bridge. When running standalone in a normal browser, it returns
+ * sensible real-time defaults so the component renders normally.
+ *
+ * @example
+ * ```tsx
+ * import { useVidraScene } from '@sansavision/vidra-web-capture/react';
+ *
+ * export default function MyScene() {
+ *     const { frame, time, fps, vars, capturing, emit } = useVidraScene();
+ *     return (
+ *         <div style={{ opacity: vars.opacity ?? 1 }}>
+ *             {capturing ? `Frame ${frame}` : 'Live preview'}
+ *         </div>
+ *     );
+ * }
+ * ```
+ */
+export declare function useVidraScene(opts?: UseVidraSceneOptions): VidraState;
+export { VidraCapture, type VidraState, type VidraBridge } from './index.js';

package/dist/react.js

@@ -0,0 +1,63 @@
+// ─── @sansavision/vidra-web-capture/react ────────────────────────────
+//
+// React hook that wraps VidraCapture and provides reactive state.
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { VidraCapture } from './index.js';
+/**
+ * React hook for making a component Vidra-capturable.
+ *
+ * When running inside the Vidra capture harness, it returns the
+ * current frame/time/fps/vars from the injected `window.__vidra`
+ * bridge. When running standalone in a normal browser, it returns
+ * sensible real-time defaults so the component renders normally.
+ *
+ * @example
+ * ```tsx
+ * import { useVidraScene } from '@sansavision/vidra-web-capture/react';
+ *
+ * export default function MyScene() {
+ *     const { frame, time, fps, vars, capturing, emit } = useVidraScene();
+ *     return (
+ *         <div style={{ opacity: vars.opacity ?? 1 }}>
+ *             {capturing ? `Frame ${frame}` : 'Live preview'}
+ *         </div>
+ *     );
+ * }
+ * ```
+ */
+export function useVidraScene(opts = {}) {
+    const { pollInterval = 16 } = opts;
+    const captureRef = useRef(null);
+    if (!captureRef.current) {
+        captureRef.current = new VidraCapture();
+    }
+    const [state, setState] = useState(() => captureRef.current.getState());
+    // Listen for postMessage-based updates from the capture harness
+    useEffect(() => {
+        const onMessage = (ev) => {
+            if (ev.data?.type === 'vidra_frame') {
+                // The harness has advanced a frame — re-read bridge.
+                setState(captureRef.current.getState());
+            }
+        };
+        window.addEventListener('message', onMessage);
+        // In standalone mode, poll so that `time` updates for animations.
+        let timerId;
+        if (!captureRef.current.isCapturing()) {
+            timerId = setInterval(() => {
+                setState(captureRef.current.getState());
+            }, pollInterval);
+        }
+        return () => {
+            window.removeEventListener('message', onMessage);
+            if (timerId !== undefined)
+                clearInterval(timerId);
+        };
+    }, [pollInterval]);
+    // Stable emit callback
+    const emit = useCallback((key, value) => {
+        captureRef.current?.emit(key, value);
+    }, []);
+    return { ...state, emit };
+}
+export { VidraCapture } from './index.js';

package/dist/test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test.js

@@ -0,0 +1,20 @@
+// Standalone test for VidraCapture graceful degradation.
+// Run with: node dist/test.js
+import { VidraCapture } from './index.js';
+// ── Test 1: VidraCapture outside harness returns defaults ───────────
+const capture = new VidraCapture();
+const state = capture.getState();
+console.assert(state.capturing === false, 'Expected capturing=false in standalone');
+console.assert(state.frame === 0, 'Expected frame=0 in standalone');
+console.assert(typeof state.time === 'number' && state.time >= 0, 'Expected time>=0');
+console.assert(state.fps === 60, 'Expected fps=60 default');
+console.assert(typeof state.vars === 'object', 'Expected vars to be an object');
+console.assert(Object.keys(state.vars).length === 0, 'Expected empty vars');
+console.assert(typeof state.emit === 'function', 'Expected emit to be a function');
+// emit() should not throw when not capturing
+state.emit('test_key', 42);
+// ── Test 2: isCapturing() returns false ─────────────────────────────
+console.assert(capture.isCapturing() === false, 'isCapturing should be false');
+// ── Test 3: emit() convenience method works without error ───────────
+capture.emit('layout_height', 1080);
+console.log('✅ All VidraCapture standalone tests passed');

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@sansavision/vidra-web-capture",
+    "version": "0.1.5",
+    "description": "Client-side SDK for making React/JS apps Vidra-capturable as web() layers",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./react": {
+            "import": "./dist/react.js",
+            "types": "./dist/react.d.ts"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "test": "node --experimental-vm-modules dist/test.js"
+    },
+    "keywords": [
+        "vidra",
+        "video",
+        "web-capture",
+        "react",
+        "scene"
+    ],
+    "author": "Sansa Vision",
+    "license": "MIT",
+    "peerDependencies": {
+        "react": ">=17.0.0"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "typescript": "^5.0.0",
+        "@types/react": "^18.0.0"
+    },
+    "publishConfig": {
+        "access": "restricted"
+    }
+}