Skip to content

Create polished demo videos without editing skills. Mac/Windows/Linux

feat: extension system with marketplace, permissions, and security hardening

webadderall18d5a091f884
diff --git a/EXTENSIONS.md b/EXTENSIONS.md
new file mode 100644
index 00000000..60b40493
--- /dev/null
+++ b/EXTENSIONS.md
@@ -0,0 +1,346 @@
+# Recordly Extension API
+
+Extensions add render hooks, device frames, click animations, audio cues, and custom settings UI to Recordly. They run in the renderer process and use a permission-gated host API to hook into the frame render pipeline.
+
+## Quick Start
+
+Create a folder under `public/builtin-extensions/` (for built-ins) or install via the Extensions tab.
+
+### Minimum Extension
+
+```
+my-extension/
+ recordly-extension.json
+ index.js
+```
+
+**recordly-extension.json**
+
+```json
+{
+ "id": "com.example.my-extension",
+ "name": "My Extension",
+ "version": "1.0.0",
+ "description": "A short description",
+ "author": "Your Name",
+ "license": "MIT",
+ "main": "index.js",
+ "permissions": ["render"]
+}
+```
+
+**index.js**
+
+```js
+export function activate(api) {
+ api.log('Hello from my extension!');
+}
+
+export function deactivate() {}
+```
+
+## Extension Manifest
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | ✅ | Unique identifier (reverse-domain style) |
+| `name` | `string` | ✅ | Display name |
+| `version` | `string` | ✅ | Semver version |
+| `description` | `string` | ✅ | One-line summary |
+| `author` | `string` | | Author or org name |
+| `homepage` | `string` | | Repository/homepage URL |
+| `license` | `string` | | SPDX license identifier |
+| `engine` | `string` | | Minimum Recordly version |
+| `icon` | `string` | | Path to icon relative to extension root |
+| `main` | `string` | ✅ | Entry point JS file |
+| `permissions` | `string[]` | ✅ | Required API permissions |
+| `contributes` | `object` | | Optional metadata for bundled assets; behavior is still registered from `activate()` |
+
+### Permissions
+
+| Permission | Grants access to |
+|-----------|-----------------|
+| `render` | Frame render pipeline hooks |
+| `cursor` | Cursor telemetry & cursor effect registration |
+| `audio` | Sound playback |
+| `timeline` | Timeline lifecycle events |
+| `ui` | Settings panels & frames |
+| `assets` | Bundled asset path resolution |
+| `export` | Export lifecycle hooks |
+
+Manifest `contributes` entries are metadata only today. Recordly does not auto-register them at runtime; extensions still need to call APIs like `registerFrame()`, `registerSettingsPanel()`, `resolveAsset()`, and `playSound()` from `activate()`.
+
+## API Reference
+
+The `api` object passed to `activate()` provides the following methods.
+
+### Render Hooks
+
+```js
+const dispose = api.registerRenderHook(phase, (ctx) => {
+ // Draw on ctx.ctx (a CanvasRenderingContext2D)
+});
+```
+
+**Phases** (in pipeline order):
+
+| Phase | Timing |
+|-------|--------|
+| `background` | Before video frame (custom backgrounds) |
+| `post-video` | After video, before zoom |
+| `post-zoom` | After zoom transform |
+| `post-cursor` | After cursor (click effects, trails) |
+| `post-webcam` | After webcam overlay |
+| `post-annotations` | After annotations |
+| `final` | Last pass (watermarks, HUD overlays) |
+
+**RenderHookContext** fields:
+
+- `width`, `height` — output canvas dimensions
+- `timeMs` — current playback time in ms
+- `durationMs` — total video duration
+- `cursor` — `{ cx, cy, interactionType } | null` (normalized 0-1)
+- `smoothedCursor` — `{ cx, cy, trail } | null` using the live rendered cursor smoothing state
+- `ctx` — `CanvasRenderingContext2D` to draw on
+- `videoLayout` — `{ maskRect, borderRadius, padding }`
+- `zoom` — `{ scale, focusX, focusY, progress }`
+- `shadow` — `{ enabled, intensity }`
+
+### Cursor Effects
+
+```js
+api.registerCursorEffect((ctx) => {
+ // ctx.cx, ctx.cy — cursor position (normalized 0-1)
+ // ctx.elapsedMs — time since the click
+ // ctx.interactionType — 'click', 'double-click', 'right-click', 'mouseup'
+ // ctx.ctx — CanvasRenderingContext2D
+ // ctx.width, ctx.height — canvas dimensions
+
+ // Return true to keep animating, false to stop
+ return ctx.elapsedMs < 600;
+});
+```
+
+### Device Frames
+
+Register browser chrome, laptop bezels, or any device overlay.
+
+**Preferred: draw function** (resolution-independent, no bitmap artifacts):
+
+```js
+api.registerFrame({
+ id: 'my-frame',
+ label: 'My Frame',
+ category: 'browser', // 'browser' | 'laptop' | 'phone' | 'tablet' | 'desktop' | 'custom'
+ appearance: 'dark', // 'light' | 'dark'
+ screenInsets: { top: 0.05, right: 0.005, bottom: 0.005, left: 0.005 },
+ draw(ctx, width, height) {
+ // Draw frame chrome at the given dimensions.
+ // Leave the screen area transparent (use globalCompositeOperation: 'destination-out').
+ // All dimensions are proportional — the function is called at whatever
+ // resolution is needed (preview, export, thumbnail).
+ },
+});
+```
+
+**Legacy: static image** (scaled as bitmap — may produce artifacts):
+
+```js
+api.registerFrame({
+ id: 'my-frame',
+ label: 'My Frame',
+ category: 'browser',
+ file: 'frames/my-frame.png', // relative to extension root
+ screenInsets: { top: 0.05, right: 0.01, bottom: 0.01, left: 0.01 },
+});
+```
+
+**`screenInsets`** define where the video content sits inside the frame, as fractions (0–1) of the frame dimensions. Example: `{ top: 0.05 }` means the top 5% of the frame image is the title bar/bezel.
+
+### Settings Panels
+
+```js
+api.registerSettingsPanel({
+ id: 'my-settings',
+ label: 'My Extension',
+ icon: 'sparkles', // Lucide icon name
+ parentSection: 'cursor', // Nest inside an existing section
+ fields: [
+ { id: 'enabled', label: 'Enable', type: 'toggle', defaultValue: true },
+ { id: 'color', label: 'Color', type: 'color', defaultValue: '#2563EB' },
+ { id: 'size', label: 'Size', type: 'slider', defaultValue: 1.0, min: 0.1, max: 3.0, step: 0.1 },
+ { id: 'style', label: 'Style', type: 'select', defaultValue: 'ripple',
+ options: [{ label: 'Ripple', value: 'ripple' }, { label: 'Pulse', value: 'pulse' }] },
+ { id: 'name', label: 'Label', type: 'text', defaultValue: '' },
+ ],
+});
+```
+
+**`parentSection`** options:
+- `'cursor'` — appears inside the Cursor settings section
+- `'scene'` — inside Scene settings
+- Omit for a **standalone section** with its own icon in the settings rail
+
+**Reading/writing settings:**
+
+```js
+const color = api.getSetting('color');
+api.setSetting('color', '#FF0000');
+```
+
+### Events
+
+```js
+api.on('cursor:click', (event) => {
+ // event.timeMs, event.data
+});
+```
+
+- `timeline` permission is required for `playback:*` and `timeline:*` subscriptions.
+- `cursor` permission is required for `cursor:*` subscriptions.
+- `export` permission is required for `export:*` subscriptions.
+
+| Event | Description |
+|-------|-------------|
+| `playback:timeupdate` | Playback time changed |
+| `playback:play` | Playback started |
+| `playback:pause` | Playback paused |
+| `cursor:click` | Mouse click detected |
+| `cursor:move` | Cursor moved |
+| `timeline:region-added` | Zoom/trim region added |
+| `timeline:region-removed` | Region removed |
+| `export:start` | Export began |
+| `export:frame` | Frame exported |
+| `export:complete` | Export finished |
+
+### Sound Playback
+
+```js
+const stop = api.playSound('sounds/click.mp3', { volume: 0.8 });
+// Call stop() to cancel playback early
+```
+
+### Query APIs
+
+Read-only access to project state:
+
+```js
+api.getVideoInfo() // { width, height, durationMs, fps } | null
+api.getVideoLayout() // { maskRect, canvasWidth, canvasHeight, borderRadius, padding } | null
+api.getCursorAt(timeMs) // { cx, cy, timeMs, interactionType, pressure } | null
+api.getSmoothedCursor() // { cx, cy, timeMs, trail } | null
+api.getZoomState() // { scale, focusX, focusY, progress } | null
+api.getShadowConfig() // { enabled, intensity }
+api.getKeystrokesInRange(startMs, endMs) // [{ timeMs, key, modifiers }]
+```
+
+### Asset Resolution
+
+```js
+const url = api.resolveAsset('images/overlay.png');
+// Returns a file:// URL scoped to the extension directory
+```
+
+### Logging
+
+```js
+api.log('Debug message', someData);
+// Output: [ext:com.example.my-extension] Debug message ...
+```
+
+## Lifecycle
+
+1. **Discovery**: Recordly scans `public/builtin-extensions/` and user extension directories
+2. **Activation**: `activate(api)` is called — register hooks, effects, panels
+3. **Runtime**: Hooks/effects execute each frame; settings panel renders in the UI
+4. **Deactivation**: `deactivate()` is called; all registered hooks are auto-disposed
+
+All `register*` methods return a dispose function for early cleanup:
+
+```js
+const dispose = api.registerRenderHook('final', myHook);
+// Later: dispose() to unregister
+```
+
+## Built-in Extensions
+
+| Extension | What it does |
+|-----------|-------------|
+| `recordly.frames` | Browser chrome, macOS window, MacBook bezel frames |
+| `recordly.click-effects` | Animated ripple/sparkle/pulse effects at click positions |
+
+## Example: Full Click Effect Extension
+
+```js
+const DURATION = 600;
+
+export function activate(api) {
+ api.registerSettingsPanel({
+ id: 'settings',
+ label: 'My Click Effect',
+ icon: 'mouse-pointer-click',
+ parentSection: 'cursor',
+ fields: [
+ { id: 'color', label: 'Color', type: 'color', defaultValue: '#FF6B6B' },
+ ],
+ });
+
+ api.registerCursorEffect((ctx) => {
+ const progress = ctx.elapsedMs / DURATION;
+ if (progress >= 1) return false;
+
+ const px = ctx.cx * ctx.width;
+ const py = ctx.cy * ctx.height;
+ const radius = 30 * progress;
+ const alpha = 1 - progress;
+ const color = api.getSetting('color') || '#FF6B6B';
+
+ ctx.ctx.beginPath();
+ ctx.ctx.arc(px, py, radius, 0, Math.PI * 2);
+ ctx.ctx.strokeStyle = color;
+ ctx.ctx.globalAlpha = alpha;
+ ctx.ctx.lineWidth = 2;
+ ctx.ctx.stroke();
+ ctx.ctx.globalAlpha = 1;
+
+ return true;
+ });
+}
+
+export function deactivate() {}
+```
+
+## Example: Resolution-Independent Device Frame
+
+```js
+function drawMyFrame(ctx, W, H) {
+ const titleBarH = Math.round(H * 0.04);
+ const border = Math.round(H * 0.003);
+ const radius = Math.round(W * 0.005);
+
+ // Draw outer frame
+ ctx.fillStyle = '#1E1E2E';
+ ctx.beginPath();
+ ctx.roundRect(0, 0, W, H, radius);
+ ctx.fill();
+
+ // Cut out screen area
+ ctx.save();
+ ctx.globalCompositeOperation = 'destination-out';
+ ctx.fillStyle = '#000';
+ ctx.fillRect(border, titleBarH, W - border * 2, H - titleBarH - border);
+ ctx.restore();
+}
+
+export function activate(api) {
+ api.registerFrame({
+ id: 'my-frame',
+ label: 'My Custom Frame',
+ category: 'custom',
+ screenInsets: { top: 0.04, right: 0.003, bottom: 0.003, left: 0.003 },
+ draw: drawMyFrame,
+ });
+}
+
+export function deactivate() {}
+```
diff --git a/electron/electron-env.d.ts b/electron/electron-env.d.ts
index cad0d8b4..97194dfa 100644
--- a/electron/electron-env.d.ts
+++ b/electron/electron-env.d.ts
@@ -411,6 +411,46 @@ interface Window {
cancelCountdown: () => Promise<{ success: boolean }>;
getActiveCountdown: () => Promise<{ success: boolean; seconds: number | null }>;
onCountdownTick: (callback: (seconds: number) => void) => () => void;
+ extensionsDiscover: () => Promise<any[]>;
+ extensionsList: () => Promise<any[]>;
+ extensionsGet: (id: string) => Promise<any | null>;
+ extensionsEnable: (id: string) => Promise<{ success: boolean; error?: string }>;
+ extensionsDisable: (id: string) => Promise<{ success: boolean; error?: string }>;
+ extensionsInstallFromFolder: () => Promise<{
+ success: boolean;
+ extension?: any;
+ message?: string;
+ error?: string;
+ canceled?: boolean;
+ }>;
+ extensionsUninstall: (id: string) => Promise<{ success: boolean; error?: string }>;
+ extensionsGetDirectory: () => Promise<{ success: boolean; path?: string; error?: string }>;
+ extensionsOpenDirectory: () => Promise<{ success: boolean; path?: string; error?: string }>;
+ extensionsMarketplaceSearch: (params: {
+ query?: string;
+ tags?: string[];
+ sort?: string;
+ page?: number;
+ pageSize?: number;
+ }) => Promise<any>;
+ extensionsMarketplaceGet: (id: string) => Promise<any | null>;
+ extensionsMarketplaceInstall: (
+ extensionId: string,
+ downloadUrl: string,
+ ) => Promise<{ success: boolean; error?: string }>;
+ extensionsMarketplaceSubmit: (
+ extensionId: string,
+ ) => Promise<{ success: boolean; reviewId?: string; error?: string }>;
+ extensionsReviewsList: (params: {
+ status?: string;
+ page?: number;
+ pageSize?: number;
+ }) => Promise<{ reviews: any[]; total: number }>;
+ extensionsReviewUpdate: (
+ reviewId: string,
+ status: string,
+ notes?: string,
+ ) => Promise<{ success: boolean; error?: string }>;
};
}
diff --git a/electron/extensions/extensionIpc.ts b/electron/extensions/extensionIpc.ts
new file mode 100644
index 00000000..737a17a5
--- /dev/null
+++ b/electron/extensions/extensionIpc.ts
@@ -0,0 +1,163 @@
+/**
+ * Extension IPC Handlers — Main Process
+ *
+ * Registers IPC handlers for extension management (discover, install,
+ * uninstall, enable/disable) and exposes them to the renderer via preload.
+ */
+
+import { BrowserWindow, ipcMain, dialog, shell } from 'electron';
+import {
+ discoverExtensions,
+ getRegisteredExtensions,
+ getExtension,
+ setExtensionStatus,
+ installExtensionFromPath,
+ uninstallExtension,
+ getExtensionsDirectory,
+} from './extensionLoader';
+import {
+ searchMarketplace,
+ getMarketplaceExtension,
+ downloadAndInstallExtension,
+ fetchPendingReviews,
+ updateReviewStatus,
+ submitExtensionForReview,
+} from './extensionMarketplace';
+import type { ExtensionInfo, MarketplaceReviewStatus } from './extensionTypes';
+
+/**
+ * Serialize extension info for IPC transfer (strip non-serializable fields).
+ */
+function serializeExtensionInfo(info: ExtensionInfo) {
+ return {
+ manifest: info.manifest,
+ status: info.status,
+ path: info.path,
+ error: info.error,
+ builtin: info.builtin ?? false,
+ };
+}
+
+/**
+ * Register all extension-related IPC handlers.
+ * Call this once during app initialization (in main.ts).
+ */
+export function registerExtensionIpcHandlers(): void {
+ // Discover all extensions (builtin + user-installed)
+ ipcMain.handle('extensions:discover', async () => {
+ const extensions = await discoverExtensions();
+ return extensions.map(serializeExtensionInfo);
+ });
+
+ // List currently registered extensions
+ ipcMain.handle('extensions:list', () => {
+ return getRegisteredExtensions().map(serializeExtensionInfo);
+ });
+
+ // Get a specific extension by ID
+ ipcMain.handle('extensions:get', (_event, id: string) => {
+ const ext = getExtension(id);
+ return ext ? serializeExtensionInfo(ext) : null;
+ });
+
+ // Enable an extension
+ ipcMain.handle('extensions:enable', async (_event, id: string) => {
+ return setExtensionStatus(id, 'active');
+ });
+
+ // Disable an extension
+ ipcMain.handle('extensions:disable', async (_event, id: string) => {
+ return setExtensionStatus(id, 'disabled');
+ });
+
+ // Install an extension from a folder picker
+ ipcMain.handle('extensions:install-from-folder', async (event) => {
+ const window = BrowserWindow.fromWebContents(event.sender);
+ const result = await dialog.showOpenDialog(window!, {
+ title: 'Select Extension Folder',
+ properties: ['openDirectory'],
+ message: 'Select a folder containing a recordly-extension.json manifest',
+ });
+
+ if (result.canceled || result.filePaths.length === 0) {
+ return { success: false, reason: 'cancelled' };
+ }
+
+ const info = await installExtensionFromPath(result.filePaths[0]);
+ if (!info) {
+ return { success: false, reason: 'Invalid extension: missing or invalid recordly-extension.json' };
+ }
+
+ return { success: true, extension: serializeExtensionInfo(info) };
+ });
+
+ // Uninstall an extension
+ ipcMain.handle('extensions:uninstall', async (_event, id: string) => {
+ const success = await uninstallExtension(id);
+ return { success };
+ });
+
+ // Get extensions directory path
+ ipcMain.handle('extensions:get-directory', () => {
+ return getExtensionsDirectory();
+ });
+
+ // Open extensions directory in file manager
+ ipcMain.handle('extensions:open-directory', async () => {
+ const dir = getExtensionsDirectory();
+ await shell.openPath(dir);
+ return { success: true };
+ });
+
+ // ── Marketplace ─────────────────────────────────────────────────────
+
+ // Search/browse marketplace
+ ipcMain.handle('extensions:marketplace-search', async (_event, params: {
+ query?: string;
+ tags?: string[];
+ sort?: 'popular' | 'recent' | 'rating';
+ page?: number;
+ pageSize?: number;
+ }) => {
+ try {
+ return await searchMarketplace(params);
+ } catch (err: any) {
+ return { extensions: [], total: 0, page: 1, pageSize: 20, error: err.message };
+ }
+ });
+
+ // Get a specific marketplace extension
+ ipcMain.handle('extensions:marketplace-get', async (_event, id: string) => {
+ return getMarketplaceExtension(id);
+ });
+
+ // Download and install a marketplace extension
+ ipcMain.handle('extensions:marketplace-install', async (_event, extensionId: string, downloadUrl: string) => {
+ return downloadAndInstallExtension(extensionId, downloadUrl);
+ });
+
+ // Submit an extension for marketplace review
+ ipcMain.handle('extensions:marketplace-submit', async (_event, extensionId: string) => {
+ return submitExtensionForReview(extensionId);
+ });
+
+ // ── Admin Review System ─────────────────────────────────────────────
+
+ // Fetch pending reviews (admin only)
+ ipcMain.handle('extensions:reviews-list', async (_event, params: {
+ status?: MarketplaceReviewStatus;
+ page?: number;
+ pageSize?: number;
+ }) => {
+ try {
+ return await fetchPendingReviews(params);
+ } catch (err: any) {
+ return { reviews: [], total: 0, error: err.message };
+ }
+ });
+
+ // Update review status (admin only)
+ ipcMain.handle('extensions:review-update', async (_event, reviewId: string, status: MarketplaceReviewStatus, notes?: string) => {
+ return updateReviewStatus(reviewId, status, notes);
+ });
+}
diff --git a/electron/extensions/extensionLoader.ts b/electron/extensions/extensionLoader.ts
new file mode 100644
index 00000000..f3e8d64e
--- /dev/null
+++ b/electron/extensions/extensionLoader.ts
@@ -0,0 +1,387 @@
+/**
+ * Extension Loader — Main Process
+ *
+ * Discovers, validates, and manages extensions installed in the
+ * extensions directory (~/.recordly/extensions/ or userData/extensions/).
+ *
+ * Extensions are loaded from disk by reading their manifest files.
+ * The actual extension code runs in the renderer process and uses the
+ * permission-gated host API exposed by the renderer.
+ */
+
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { app } from "electron";
+import type { ExtensionInfo, ExtensionManifest, ExtensionStatus } from "./extensionTypes";
+
+const EXTENSIONS_DIR_NAME = "extensions";
+const MANIFEST_FILE_NAME = "recordly-extension.json";
+const BUILTIN_EXTENSIONS_DIR = "builtin-extensions";
+const EXTENSION_STATE_FILE_NAME = "extension-state.json";
+
+/** In-memory registry of loaded extensions */
+const extensionRegistry = new Map<string, ExtensionInfo>();
+
+type PersistedExtensionStatus = Extract<ExtensionStatus, "active" | "disabled" | "installed">;
+
+/**
+ * Returns the directory where user-installed extensions live.
+ */
+export function getExtensionsDirectory(): string {
+ return path.join(app.getPath("userData"), EXTENSIONS_DIR_NAME);
+}
+
+/**
+ * Returns the built-in extensions directory (shipped with the app).
+ */
+function getBuiltinExtensionsDirectory(): string {
+ if (app.isPackaged) {
+ return path.join(process.resourcesPath, BUILTIN_EXTENSIONS_DIR);
+ }
+ return path.join(app.getAppPath(), "public", BUILTIN_EXTENSIONS_DIR);
+}
+
+function getExtensionStateFilePath(): string {
+ return path.join(app.getPath("userData"), EXTENSION_STATE_FILE_NAME);
+}
+
+function isPersistedExtensionStatus(value: unknown): value is PersistedExtensionStatus {
+ return value === "active" || value === "disabled" || value === "installed";
+}
+
+async function readPersistedExtensionStatuses(): Promise<Record<string, PersistedExtensionStatus>> {
+ const stateFile = getExtensionStateFilePath();
+ if (!existsSync(stateFile)) {
+ return {};
+ }
+
+ try {
+ const raw = await fs.readFile(stateFile, "utf-8");
+ const parsed = JSON.parse(raw);
+
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+ return {};
+ }
+
+ const entries = Object.entries(parsed).filter(
+ ([key, value]) => typeof key === "string" && isPersistedExtensionStatus(value),
+ );
+
+ return Object.fromEntries(entries) as Record<string, PersistedExtensionStatus>;
+ } catch {
+ return {};
+ }
+}
+
+async function writePersistedExtensionStatuses(
+ statuses: Record<string, PersistedExtensionStatus>,
+): Promise<void> {
+ const stateFile = getExtensionStateFilePath();
+ await fs.mkdir(path.dirname(stateFile), { recursive: true });
+ await fs.writeFile(stateFile, JSON.stringify(statuses, null, 2), "utf-8");
+}
+
+async function updatePersistedExtensionStatus(
+ id: string,
+ status: PersistedExtensionStatus | null,
+): Promise<void> {
+ const statuses = await readPersistedExtensionStatuses();
+
+ if (status) {
+ statuses[id] = status;
+ } else {
+ delete statuses[id];
+ }
+
+ await writePersistedExtensionStatuses(statuses);
+}
+
+/**
+ * Ensure the extensions directory exists.
+ */
+async function ensureExtensionsDirectory(): Promise<void> {
+ const dir = getExtensionsDirectory();
+ await fs.mkdir(dir, { recursive: true });
+}
+
+/**
+ * Validate an extension manifest for required fields and safe values.
+ */
+function validateManifest(manifest: unknown, extensionPath: string): ExtensionManifest | null {
+ if (!manifest || typeof manifest !== "object") {
+ return null;
+ }
+
+ const m = manifest as Record<string, unknown>;
+
+ // Required fields
+ if (typeof m.id !== "string" || m.id.length === 0) return null;
+ // Only allow safe characters in extension IDs
+ if (!/^[a-z0-9][a-z0-9._-]*$/i.test(m.id)) return null;
+ if (typeof m.name !== "string" || m.name.length === 0) return null;
+ if (typeof m.version !== "string") return null;
+ if (typeof m.main !== "string" || m.main.length === 0) return null;
+
+ // Validate main entry doesn't escape extension directory
+ const resolvedMain = path.resolve(extensionPath, m.main);
+ const relativeMain = path.relative(extensionPath, resolvedMain);
+ if (relativeMain.startsWith("..") || path.isAbsolute(relativeMain)) {
+ console.warn(`[extensions] Extension ${m.id}: main entry escapes extension directory`);
+ return null;
+ }
+
+ // Validate permissions array
+ const validPermissions = new Set([
+ "render",
+ "cursor",
+ "audio",
+ "timeline",
+ "ui",
+ "assets",
+ "export",
+ ]);
+ const permissions = Array.isArray(m.permissions) ? m.permissions : [];
+ const safePermissions = permissions.filter(
+ (p): p is string => typeof p === "string" && validPermissions.has(p),
+ );
+
+ return {
+ id: m.id as string,
+ name: m.name as string,
+ version: m.version as string,
+ description: typeof m.description === "string" ? m.description : "",
+ author: typeof m.author === "string" ? m.author : undefined,
+ homepage: typeof m.homepage === "string" ? m.homepage : undefined,
+ license: typeof m.license === "string" ? m.license : undefined,
+ engine: typeof m.engine === "string" ? m.engine : undefined,
+ icon: typeof m.icon === "string" ? m.icon : undefined,
+ main: m.main as string,
+ permissions: safePermissions as ExtensionManifest["permissions"],
+ contributes:
+ typeof m.contributes === "object" && m.contributes !== null
+ ? (m.contributes as ExtensionManifest["contributes"])
+ : undefined,
+ };
+}
+
+/**
+ * Scan a directory for extensions (each subdirectory with a manifest).
+ */
+async function scanExtensionsIn(directory: string, builtin: boolean): Promise<ExtensionInfo[]> {
+ const results: ExtensionInfo[] = [];
+
+ if (!existsSync(directory)) {
+ return results;
+ }
+
+ let entries: string[];
+ try {
+ entries = await fs.readdir(directory);
+ } catch {
+ return results;
+ }
+
+ for (const entry of entries) {
+ const extDir = path.join(directory, entry);
+
+ // Skip non-directories (lstat — don't follow symlinks)
+ let stat;
+ try {
+ stat = await fs.lstat(extDir);
+ } catch {
+ continue;
+ }
+ if (!stat.isDirectory()) continue;
+
+ const manifestPath = path.join(extDir, MANIFEST_FILE_NAME);
+ if (!existsSync(manifestPath)) continue;
+
+ try {
+ const raw = await fs.readFile(manifestPath, "utf-8");
+ const parsed = JSON.parse(raw);
+ const manifest = validateManifest(parsed, extDir);
+
+ if (!manifest) {
+ results.push({
+ manifest: {
+ id: entry,
+ name: entry,
+ version: "0.0.0",
+ main: "",
+ permissions: [],
+ description: "Invalid manifest",
+ },
+ status: "error",
+ path: extDir,
+ error: "Invalid or incomplete manifest",
+ builtin,
+ });
+ continue;
+ }
+
+ // Check that the entry file exists
+ const entryPath = path.join(extDir, manifest.main);
+ if (!existsSync(entryPath)) {
+ results.push({
+ manifest,
+ status: "error",
+ path: extDir,
+ error: `Entry file not found: ${manifest.main}`,
+ builtin,
+ });
+ continue;
+ }
+
+ results.push({
+ manifest,
+ status: "installed",
+ path: extDir,
+ builtin,
+ });
+ } catch (err) {
+ results.push({
+ manifest: {
+ id: entry,
+ name: entry,
+ version: "0.0.0",
+ main: "",
+ permissions: [],
+ description: "Failed to load",
+ },
+ status: "error",
+ path: extDir,
+ error: String(err),
+ builtin,
+ });
+ }
+ }
+
+ return results;
+}
+
+/**
+ * Discover and register all available extensions (builtin + user-installed).
+ */
+export async function discoverExtensions(): Promise<ExtensionInfo[]> {
+ await ensureExtensionsDirectory();
+
+ const builtinDir = getBuiltinExtensionsDirectory();
+ const userDir = getExtensionsDirectory();
+
+ const [builtinExts, userExts] = await Promise.all([
+ scanExtensionsIn(builtinDir, true),
+ scanExtensionsIn(userDir, false),
+ ]);
+
+ const persistedStatuses = await readPersistedExtensionStatuses();
+ const applyPersistedStatus = (ext: ExtensionInfo): ExtensionInfo => {
+ if (ext.status === "error") {
+ return ext;
+ }
+
+ return {
+ ...ext,
+ status: persistedStatuses[ext.manifest.id] ?? (ext.builtin ? "active" : "installed"),
+ };
+ };
+
+ const normalizedBuiltinExts = builtinExts.map(applyPersistedStatus);
+ const normalizedUserExts = userExts.map(applyPersistedStatus);
+
+ // User extensions override builtin ones with the same ID
+ extensionRegistry.clear();
+ for (const ext of normalizedBuiltinExts) {
+ extensionRegistry.set(ext.manifest.id, ext);
+ }
+ for (const ext of normalizedUserExts) {
+ extensionRegistry.set(ext.manifest.id, ext);
+ }
+
+ return Array.from(extensionRegistry.values());
+}
+
+/**
+ * Get all registered extensions.
+ */
+export function getRegisteredExtensions(): ExtensionInfo[] {
+ return Array.from(extensionRegistry.values());
+}
+
+/**
+ * Get a specific extension by ID.
+ */
+export function getExtension(id: string): ExtensionInfo | undefined {
+ return extensionRegistry.get(id);
+}
+
+/**
+ * Enable or disable an extension.
+ */
+export async function setExtensionStatus(id: string, status: ExtensionStatus): Promise<boolean> {
+ const ext = extensionRegistry.get(id);
+ if (!ext) return false;
+ ext.status = status;
+
+ if (status === "active" || status === "disabled" || status === "installed") {
+ await updatePersistedExtensionStatus(id, status);
+ }
+
+ return true;
+}
+
+/**
+ * Install an extension from a directory (copy to extensions dir).
+ */
+export async function installExtensionFromPath(sourcePath: string): Promise<ExtensionInfo | null> {
+ const manifestPath = path.join(sourcePath, MANIFEST_FILE_NAME);
+ if (!existsSync(manifestPath)) {
+ return null;
+ }
+
+ let manifest: ExtensionManifest | null;
+ try {
+ const raw = await fs.readFile(manifestPath, "utf-8");
+ manifest = validateManifest(JSON.parse(raw), sourcePath);
+ } catch {
+ return null;
+ }
+
+ if (!manifest) return null;
+
+ const targetDir = path.join(getExtensionsDirectory(), manifest.id);
+
+ // Remove existing version if present
+ if (existsSync(targetDir)) {
+ await fs.rm(targetDir, { recursive: true, force: true });
+ }
+
+ await fs.cp(sourcePath, targetDir, { recursive: true });
+
+ const info: ExtensionInfo = {
+ manifest,
+ status: "installed",
+ path: targetDir,
+ };
+
+ extensionRegistry.set(manifest.id, info);
+ await updatePersistedExtensionStatus(manifest.id, "installed");
+ return info;
+}
+
+/**
+ * Uninstall a user extension (cannot uninstall builtin).
+ */
+export async function uninstallExtension(id: string): Promise<boolean> {
+ const ext = extensionRegistry.get(id);
+ if (!ext || ext.builtin) return false;
+
+ try {
+ await fs.rm(ext.path, { recursive: true, force: true });
+ extensionRegistry.delete(id);
+ await updatePersistedExtensionStatus(id, null);
+ return true;
+ } catch {
+ return false;
+ }
+}
diff --git a/electron/extensions/extensionMarketplace.ts b/electron/extensions/extensionMarketplace.ts
new file mode 100644
index 00000000..3bff07f6
--- /dev/null
+++ b/electron/extensions/extensionMarketplace.ts
@@ -0,0 +1,328 @@
+/**
+ * Extension Marketplace — Main Process
+ *
+ * Handles fetching, downloading, and installing extensions from the
+ * Recordly marketplace API. Also provides admin review endpoints.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { createWriteStream, existsSync } from 'node:fs';
+import { app } from 'electron';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { installExtensionFromPath, getRegisteredExtensions } from './extensionLoader';
+import type {
+ MarketplaceExtension,
+ MarketplaceSearchResult,
+ MarketplaceReviewStatus,
+ ExtensionReview,
+} from './extensionTypes';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const MARKETPLACE_API_BASE = 'https://marketplace.recordly.dev/extensions/api/v1';
+const REQUEST_TIMEOUT_MS = 15_000;
+
+// ---------------------------------------------------------------------------
+// Zip-slip protection: recursively verify all extracted files stay within the
+// expected directory. Rejects symlinks that point outside and any entry whose
+// real path escapes the root.
+// ---------------------------------------------------------------------------
+
+async function assertNoEscapedFiles(dir: string, root: string): Promise<void> {
+ const entries = await fs.readdir(dir, { withFileTypes: true });
+ for (const entry of entries) {
+ const entryPath = path.join(dir, entry.name);
+ const real = await fs.realpath(entryPath);
+ if (!real.startsWith(root + path.sep) && real !== root) {
+ // Nuke the escaped file/symlink and throw
+ await fs.rm(entryPath, { recursive: true, force: true }).catch(() => {});
+ throw new Error(`Zip-slip detected: ${entry.name} resolves outside extraction directory`);
+ }
+ if (entry.isDirectory()) {
+ await assertNoEscapedFiles(entryPath, root);
+ }
+ }
+}
+
+function getMarketplaceUrl(): string {
+ // Allow explicit override for local marketplace development.
+ if (process.env.RECORDLY_MARKETPLACE_URL) return process.env.RECORDLY_MARKETPLACE_URL;
+ return MARKETPLACE_API_BASE;
+}
+
+function getAdminKey(): string | undefined {
+ return process.env.RECORDLY_ADMIN_KEY;
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+async function marketplaceFetch<T>(
+ endpoint: string,
+ options: { method?: string; body?: unknown; timeout?: number; admin?: boolean } = {},
+): Promise<T> {
+ const url = `${getMarketplaceUrl()}${endpoint}`;
+ const controller = new AbortController();
+ const timeoutId = setTimeout(() => controller.abort(), options.timeout ?? REQUEST_TIMEOUT_MS);
+
+ try {
+ const headers: Record<string, string> = {
+ 'Content-Type': 'application/json',
+ 'X-Recordly-Version': app.getVersion(),
+ 'X-Recordly-Platform': process.platform,
+ };
+
+ // Attach admin key for privileged endpoints
+ if (options.admin) {
+ const key = getAdminKey();
+ if (!key) throw new Error('Admin key not configured (set RECORDLY_ADMIN_KEY env var)');
+ headers['X-Admin-Key'] = key;
+ }
+
+ const response = await fetch(url, {
+ method: options.method ?? 'GET',
+ headers,
+ body: options.body ? JSON.stringify(options.body) : undefined,
+ signal: controller.signal,
+ });
+
+ if (!response.ok) {
+ const text = await response.text().catch(() => '');
+ throw new Error(`Marketplace API error ${response.status}: ${text}`);
+ }
+
+ return await response.json() as T;
+ } finally {
+ clearTimeout(timeoutId);
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Search/browse marketplace extensions.
+ */
+export async function searchMarketplace(params: {
+ query?: string;
+ tags?: string[];
+ sort?: 'popular' | 'recent' | 'rating';
+ page?: number;
+ pageSize?: number;
+}): Promise<MarketplaceSearchResult> {
+ const searchParams = new URLSearchParams();
+ if (params.query) searchParams.set('query', params.query);
+ if (params.tags?.length) searchParams.set('tags', params.tags.join(','));
+ if (params.sort) searchParams.set('sort', params.sort);
+ if (params.page) searchParams.set('page', String(params.page));
+ if (params.pageSize) searchParams.set('pageSize', String(params.pageSize));
+
+ const qs = searchParams.toString();
+ const result = await marketplaceFetch<MarketplaceSearchResult>(
+ `/extensions${qs ? `?${qs}` : ''}`,
+ );
+
+ // Mark installed extensions
+ const installed = getRegisteredExtensions();
+ const installedIds = new Set(installed.map(e => e.manifest.id));
+ for (const ext of result.extensions) {
+ ext.installed = installedIds.has(ext.id);
+ }
+
+ return result;
+}
+
+/**
+ * Get a single marketplace extension by ID.
+ */
+export async function getMarketplaceExtension(id: string): Promise<MarketplaceExtension | null> {
+ try {
+ const ext = await marketplaceFetch<MarketplaceExtension>(`/extensions/${encodeURIComponent(id)}`);
+ const installed = getRegisteredExtensions();
+ ext.installed = installed.some(e => e.manifest.id === ext.id);
+ return ext;
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Download and install a marketplace extension.
+ * Downloads the zip, extracts it to a temp dir, then installs from there.
+ */
+export async function downloadAndInstallExtension(
+ extensionId: string,
+ downloadUrl: string,
+): Promise<{ success: boolean; error?: string }> {
+ // Validate download URL against allowed marketplace origins
+ const allowedOrigins = [
+ 'https://marketplace.recordly.dev',
+ 'https://recordly.dev',
+ ...(app.isPackaged ? [] : ['http://localhost:3001']),
+ ];
+ try {
+ const url = new URL(downloadUrl);
+ if (!allowedOrigins.some(o => url.origin === o)) {
+ return { success: false, error: `Untrusted download origin: ${url.origin}` };
+ }
+ } catch {
+ return { success: false, error: 'Invalid download URL' };
+ }
+
+ const tempDir = path.join(app.getPath('temp'), `recordly-ext-${extensionId}-${Date.now()}`);
+ const zipPath = path.join(tempDir, 'extension.zip');
+
+ try {
+ // Create temp directory
+ await fs.mkdir(tempDir, { recursive: true });
+
+ // Download the archive
+ const controller = new AbortController();
+ const timeoutId = setTimeout(() => controller.abort(), 60_000);
+
+ let response: Response;
+ try {
+ response = await fetch(downloadUrl, {
+ signal: controller.signal,
+ headers: {
+ 'X-Recordly-Version': app.getVersion(),
+ },
+ });
+ } finally {
+ clearTimeout(timeoutId);
+ }
+
+ if (!response.ok) {
+ throw new Error(`Download failed with status ${response.status}`);
+ }
+
+ if (!response.body) {
+ throw new Error('Download response has no body');
+ }
+
+ // Write to disk
+ const fileStream = createWriteStream(zipPath);
+ await pipeline(Readable.fromWeb(response.body as any), fileStream);
+
+ // Extract the zip — use the built-in decompress or shell unzip
+ const extractDir = path.join(tempDir, 'extracted');
+ await fs.mkdir(extractDir, { recursive: true });
+
+ // Use Node's built-in unzip capability via child_process (execFile — no shell)
+ const { execFile } = await import('node:child_process');
+ await new Promise<void>((resolve, reject) => {
+ if (process.platform === 'win32') {
+ // Use -LiteralPath to avoid PowerShell injection via single-quote in paths
+ execFile('powershell', [
+ '-NoProfile',
+ '-NonInteractive',
+ '-command',
+ 'Expand-Archive',
+ '-LiteralPath', zipPath,
+ '-DestinationPath', extractDir,
+ '-Force',
+ ], (error) => {
+ if (error) reject(error);
+ else resolve();
+ });
+ } else {
+ execFile('unzip', ['-o', zipPath, '-d', extractDir], (error) => {
+ if (error) reject(error);
+ else resolve();
+ });
+ }
+ });
+
+ // Security: verify no extracted file escaped the extraction directory
+ // (protects against zip-slip / path traversal entries in malicious archives)
+ const resolvedExtractDir = path.resolve(extractDir);
+ await assertNoEscapedFiles(resolvedExtractDir, resolvedExtractDir);
+
+ // Find the manifest — it might be in a subfolder
+ const entries = await fs.readdir(extractDir, { withFileTypes: true });
+ let manifestDir = extractDir;
+
+ // If there's a single directory, look inside it
+ const dirs = entries.filter(e => e.isDirectory());
+ if (dirs.length === 1 && !existsSync(path.join(extractDir, 'recordly-extension.json'))) {
+ manifestDir = path.join(extractDir, dirs[0].name);
+ }
+
+ // Verify manifest exists
+ if (!existsSync(path.join(manifestDir, 'recordly-extension.json'))) {
+ throw new Error('Downloaded extension does not contain a recordly-extension.json manifest');
+ }
+
+ // Install from the extracted directory
+ const info = await installExtensionFromPath(manifestDir);
+ if (!info) {
+ throw new Error('Extension validation failed after download');
+ }
+
+ return { success: true };
+ } catch (err: any) {
+ return { success: false, error: err.message ?? String(err) };
+ } finally {
+ // Clean up temp directory
+ await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Review System (Admin)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch extensions pending review (admin only).
+ */
+export async function fetchPendingReviews(params: {
+ status?: MarketplaceReviewStatus;
+ page?: number;
+ pageSize?: number;
+}): Promise<{ reviews: ExtensionReview[]; total: number }> {
+ const searchParams = new URLSearchParams();
+ if (params.status) searchParams.set('status', params.status);
+ if (params.page) searchParams.set('page', String(params.page));
+ if (params.pageSize) searchParams.set('pageSize', String(params.pageSize));
+
+ const qs = searchParams.toString();
+ return marketplaceFetch<{ reviews: ExtensionReview[]; total: number }>(
+ `/admin/reviews${qs ? `?${qs}` : ''}`,
+ { admin: true },
+ );
+}
+
+/**
+ * Update the review status of a submitted extension (admin only).
+ */
+export async function updateReviewStatus(
+ reviewId: string,
+ status: MarketplaceReviewStatus,
+ notes?: string,
+): Promise<{ success: boolean }> {
+ return marketplaceFetch<{ success: boolean }>(`/admin/reviews/${encodeURIComponent(reviewId)}`, {
+ method: 'PATCH',
+ body: { status, notes },
+ admin: true,
+ });
+}
+
+/**
+ * Submit an extension for marketplace review.
+ */
+export async function submitExtensionForReview(extensionId: string): Promise<{ success: boolean; reviewId?: string; error?: string }> {
+ try {
+ return await marketplaceFetch<{ success: boolean; reviewId?: string }>(
+ `/extensions/${encodeURIComponent(extensionId)}/submit`,
+ { method: 'POST' },
+ );
+ } catch (err: any) {
+ return { success: false, error: err.message ?? String(err) };
+ }
+}
diff --git a/electron/extensions/extensionTypes.ts b/electron/extensions/extensionTypes.ts
new file mode 100644
index 00000000..8f21218e
--- /dev/null
+++ b/electron/extensions/extensionTypes.ts
@@ -0,0 +1,99 @@
+/**
+ * Re-export of extension types for use in the main process.
+ * The canonical types live in src/lib/extensions/types.ts.
+ * This file mirrors the subset needed by the electron layer.
+ */
+
+export type ExtensionPermission =
+ | "render"
+ | "cursor"
+ | "audio"
+ | "timeline"
+ | "ui"
+ | "assets"
+ | "export";
+
+export interface ExtensionManifest {
+ id: string;
+ name: string;
+ version: string;
+ description: string;
+ author?: string;
+ homepage?: string;
+ license?: string;
+ engine?: string;
+ icon?: string;
+ main: string;
+ permissions: ExtensionPermission[];
+ contributes?: ExtensionContributions;
+}
+
+export interface ExtensionContributions {
+ /** Informational manifest metadata only; runtime registration still happens from activate(). */
+ cursorStyles?: {
+ id: string;
+ label: string;
+ defaultImage: string;
+ clickImage?: string;
+ hotspot?: { x: number; y: number };
+ }[];
+ sounds?: { id: string; label: string; category: string; file: string; durationMs?: number }[];
+ wallpapers?: { id: string; label: string; file: string; thumbnail?: string; isVideo?: boolean }[];
+ webcamFrames?: { id: string; label: string; file: string; thumbnail?: string }[];
+}
+
+export type ExtensionStatus = "installed" | "active" | "disabled" | "error";
+
+export interface ExtensionInfo {
+ manifest: ExtensionManifest;
+ status: ExtensionStatus;
+ path: string;
+ error?: string;
+ builtin?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Marketplace Types
+// ---------------------------------------------------------------------------
+
+export type MarketplaceReviewStatus = "pending" | "approved" | "rejected" | "flagged";
+
+export interface MarketplaceExtension {
+ id: string;
+ name: string;
+ version: string;
+ description: string;
+ author: string;
+ downloadUrl: string;
+ iconUrl?: string;
+ screenshots?: string[];
+ downloads: number;
+ rating: number;
+ ratingCount: number;
+ tags: string[];
+ permissions: ExtensionPermission[];
+ reviewStatus: MarketplaceReviewStatus;
+ publishedAt: string;
+ updatedAt: string;
+ installed?: boolean;
+}
+
+export interface MarketplaceSearchResult {
+ extensions: MarketplaceExtension[];
+ total: number;
+ page: number;
+ pageSize: number;
+}
+
+export interface ExtensionReview {
+ id: string;
+ extensionId: string;
+ extensionName: string;
+ version: string;
+ author: string;
+ submittedAt: string;
+ status: MarketplaceReviewStatus;
+ reviewNotes?: string;
+ manifest: ExtensionManifest;
+ downloadUrl: string;
+}
diff --git a/electron/main.ts b/electron/main.ts
index 4bd94d8c..6cd19bbd 100644
--- a/electron/main.ts
+++ b/electron/main.ts
@@ -22,6 +22,7 @@ import {
killWindowsCaptureProcess,
registerIpcHandlers,
} from "./ipc/handlers";
+import { registerExtensionIpcHandlers } from "./extensions/extensionIpc";
import { ensurePackagedRendererServer } from "./rendererServer";
import type { UpdateToastPayload } from "./updater";
import {
@@ -51,18 +52,18 @@ import {
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const IS_SMOKE_EXPORT = process.env.RECORDLY_SMOKE_EXPORT === "1";
+app.commandLine.appendSwitch("ignore-gpu-blocklist");
+app.commandLine.appendSwitch("enable-unsafe-webgpu");
+app.commandLine.appendSwitch("enable-gpu-rasterization");
+
function configureGpuAccelerationSwitches() {
if (process.platform === "darwin") {
- app.commandLine.appendSwitch("ignore-gpu-blocklist");
- app.commandLine.appendSwitch("enable-gpu-rasterization");
app.commandLine.appendSwitch("use-angle", "metal");
app.commandLine.appendSwitch("disable-features", "MacCatapLoopbackAudioForScreenShare");
return;
}
if (process.platform === "win32") {
- app.commandLine.appendSwitch("ignore-gpu-blocklist");
- app.commandLine.appendSwitch("enable-gpu-rasterization");
app.commandLine.appendSwitch("use-angle", "d3d11");
return;
}
@@ -847,6 +848,8 @@ app.whenReady().then(async () => {
},
);
+ registerExtensionIpcHandlers();
+
if (IS_SMOKE_EXPORT) {
await logSmokeExportGpuDiagnostics();
console.log(
diff --git a/electron/preload.ts b/electron/preload.ts
index 6cd715c0..d477fa82 100644
--- a/electron/preload.ts
+++ b/electron/preload.ts
@@ -518,4 +518,35 @@ contextBridge.exposeInMainWorld("electronAPI", {
ipcRenderer.on("countdown-tick", listener);
return () => ipcRenderer.removeListener("countdown-tick", listener);
},
+
+ // ── Extensions ──────────────────────────────────────────────────────
+ extensionsDiscover: () => ipcRenderer.invoke("extensions:discover"),
+ extensionsList: () => ipcRenderer.invoke("extensions:list"),
+ extensionsGet: (id: string) => ipcRenderer.invoke("extensions:get", id),
+ extensionsEnable: (id: string) => ipcRenderer.invoke("extensions:enable", id),
+ extensionsDisable: (id: string) => ipcRenderer.invoke("extensions:disable", id),
+ extensionsInstallFromFolder: () => ipcRenderer.invoke("extensions:install-from-folder"),
+ extensionsUninstall: (id: string) => ipcRenderer.invoke("extensions:uninstall", id),
+ extensionsGetDirectory: () => ipcRenderer.invoke("extensions:get-directory"),
+ extensionsOpenDirectory: () => ipcRenderer.invoke("extensions:open-directory"),
+
+ // ── Extensions — Marketplace ────────────────────────────────────────
+ extensionsMarketplaceSearch: (params: {
+ query?: string;
+ tags?: string[];
+ sort?: string;
+ page?: number;
+ pageSize?: number;
+ }) => ipcRenderer.invoke("extensions:marketplace-search", params),
+ extensionsMarketplaceGet: (id: string) => ipcRenderer.invoke("extensions:marketplace-get", id),
+ extensionsMarketplaceInstall: (extensionId: string, downloadUrl: string) =>
+ ipcRenderer.invoke("extensions:marketplace-install", extensionId, downloadUrl),
+ extensionsMarketplaceSubmit: (extensionId: string) =>
+ ipcRenderer.invoke("extensions:marketplace-submit", extensionId),
+
+ // ── Extensions — Admin Review ───────────────────────────────────────
+ extensionsReviewsList: (params: { status?: string; page?: number; pageSize?: number }) =>
+ ipcRenderer.invoke("extensions:reviews-list", params),
+ extensionsReviewUpdate: (reviewId: string, status: string, notes?: string) =>
+ ipcRenderer.invoke("extensions:review-update", reviewId, status, notes),
});
diff --git a/src/components/video-editor/ExtensionIcon.tsx b/src/components/video-editor/ExtensionIcon.tsx
new file mode 100644
index 00000000..6a0d8e47
--- /dev/null
+++ b/src/components/video-editor/ExtensionIcon.tsx
@@ -0,0 +1,87 @@
+import { icons, Puzzle } from "lucide-react";
+import type { LucideProps } from "lucide-react";
+
+const WINDOWS_ABSOLUTE_PATH = /^[a-zA-Z]:[\\/]/;
+
+function isImagePath(value: string): boolean {
+ return (
+ value.startsWith("data:") ||
+ value.startsWith("file://") ||
+ value.startsWith("http://") ||
+ value.startsWith("https://") ||
+ value.includes("/") ||
+ /\.(png|svg|jpg|jpeg|webp|gif)$/i.test(value)
+ );
+}
+
+function toFileHref(filePath: string): string {
+ const normalized = filePath.replace(/\\/g, "/");
+
+ if (normalized.startsWith("file://")) {
+ return normalized;
+ }
+
+ if (normalized.startsWith("/")) {
+ return `file://${normalized}`;
+ }
+
+ if (WINDOWS_ABSOLUTE_PATH.test(normalized)) {
+ return `file:///${normalized}`;
+ }
+
+ return normalized;
+}
+
+function resolveIconSrc(icon: string, extensionPath?: string | null): string | null {
+ if (!isImagePath(icon)) {
+ return null;
+ }
+
+ if (
+ icon.startsWith("data:") ||
+ icon.startsWith("file://") ||
+ icon.startsWith("http://") ||
+ icon.startsWith("https://")
+ ) {
+ return icon;
+ }
+
+ if (icon.startsWith("/") || WINDOWS_ABSOLUTE_PATH.test(icon)) {
+ return toFileHref(icon);
+ }
+
+ if (!extensionPath) {
+ return icon;
+ }
+
+ const baseHref = toFileHref(extensionPath.endsWith("/") ? extensionPath : `${extensionPath}/`);
+ return new URL(icon, baseHref).toString();
+}
+
+/**
+ * Renders either a Lucide icon (by PascalCase name) or an image (by path/URL).
+ * Falls back to the Puzzle icon if nothing matches.
+ */
+export function ExtensionIcon({
+ icon,
+ extensionPath,
+ className = "w-4 h-4",
+ ...rest
+}: { icon?: string | null; extensionPath?: string | null; className?: string } & Omit<LucideProps, "ref">) {
+ if (!icon) {
+ return <Puzzle className={className} {...rest} />;
+ }
+
+ const iconSrc = resolveIconSrc(icon, extensionPath);
+ if (iconSrc) {
+ return <img src={iconSrc} alt="" className={className} style={{ objectFit: "contain" }} />;
+ }
+
+ // Try Lucide icon name (PascalCase)
+ const LucideIcon = (icons as Record<string, typeof Puzzle>)[icon];
+ if (LucideIcon) {
+ return <LucideIcon className={className} {...rest} />;
+ }
+
+ return <Puzzle className={className} {...rest} />;
+}
diff --git a/src/components/video-editor/ExtensionManager.tsx b/src/components/video-editor/ExtensionManager.tsx
new file mode 100644
index 00000000..ffc04b54
--- /dev/null
+++ b/src/components/video-editor/ExtensionManager.tsx
@@ -0,0 +1,949 @@
+/**
+ * ExtensionManager — Sidebar panel for browsing, installing, and managing extensions.
+ *
+ * Matches the SettingsPanel sidebar styling with tabs:
+ * - Browse: Marketplace search and download
+ * - Installed: Local extensions with toggle switches
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import { AnimatePresence, LayoutGroup, motion } from "motion/react";
+import { Button } from "@/components/ui/button";
+import { Switch } from "@/components/ui/switch";
+import {
+ Dialog,
+ DialogContent,
+} from "@/components/ui/dialog";
+import {
+ Puzzle,
+ FolderOpen,
+ Plus,
+ Trash2,
+ RefreshCw,
+ Download,
+ Search,
+ ShieldAlert,
+ Loader2,
+ Check,
+ BookOpen,
+ Tag,
+ ExternalLink,
+} from "lucide-react";
+import { toast } from "sonner";
+import { cn } from "@/lib/utils";
+import { useExtensions } from "@/hooks/useExtensions";
+import { ExtensionIcon } from "./ExtensionIcon";
+import type { ExtensionInfo, MarketplaceExtension } from "@/lib/extensions";
+
+type ExtensionTab = "installed" | "browse";
+
+const TAB_OPTIONS: { value: ExtensionTab; label: string }[] = [
+ { value: "browse", label: "Browse" },
+ { value: "installed", label: "Installed" },
+];
+
+const EXTENSIONS_DOCS_URL = "https://marketplace.recordly.dev/extensions";
+
+// ---------------------------------------------------------------------------
+// Installed Extension Card
+// ---------------------------------------------------------------------------
+
+function InstalledExtensionCard({
+ extension,
+ isActive,
+ onToggle,
+ onUninstall,
+ onClick,
+}: {
+ extension: ExtensionInfo;
+ isActive: boolean;
+ onToggle: () => void;
+ onUninstall?: () => void;
+ onClick?: () => void;
+}) {
+ const isError = extension.status === "error";
+ const isBuiltin = extension.builtin;
+
+ return (
+ <div
+ className={cn(
+ "flex items-start gap-3 p-3 rounded-xl border transition-colors cursor-pointer",
+ isError
+ ? "border-red-500/30 bg-red-500/5"
+ : isActive
+ ? "border-[#2563EB]/20 bg-[#2563EB]/5"
+ : "border-white/[0.06] bg-white/[0.02] hover:bg-white/[0.04]",
+ )}
+ onClick={onClick}
+ >
+ <div className="flex-shrink-0 w-8 h-8 rounded-lg bg-white/5 border border-white/10 flex items-center justify-center">
+ <ExtensionIcon icon={extension.manifest.icon} extensionPath={extension.path} className="w-3.5 h-3.5 text-slate-400" />
+ </div>
+
+ <div className="flex-1 min-w-0">
+ <div className="flex items-center gap-1.5">
+ <span className="text-[13px] font-medium text-slate-200 truncate">
+ {extension.manifest.name}
+ </span>
+ </div>
+
+ {extension.manifest.author && (
+ <p className="text-[10px] text-slate-500 mt-0.5">
+ {extension.manifest.homepage ? (
+ <a
+ href={extension.manifest.homepage}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="hover:text-slate-300 transition-colors"
+ onClick={(e) => e.stopPropagation()}
+ >
+ By {extension.manifest.author}
+ </a>
+ ) : (
+ <>By {extension.manifest.author}</>
+ )}
+ </p>
+ )}
+
+ <p className="text-[11px] text-slate-500 mt-0.5 line-clamp-1">
+ {extension.manifest.description || "No description"}
+ </p>
+
+ {isError && extension.error && (
+ <p className="text-[10px] text-red-400 mt-1">Error: {extension.error}</p>
+ )}
+
+ {extension.manifest.permissions.length > 0 && (
+ <div className="flex gap-1 mt-1.5 flex-wrap">
+ {extension.manifest.permissions.map((perm) => (
+ <span
+ key={perm}
+ className="text-[8px] px-1 py-[1px] rounded bg-white/5 text-slate-600 font-mono"
+ >
+ {perm}
+ </span>
+ ))}
+ </div>
+ )}
+ </div>
+
+ <div className="flex items-center gap-1.5 flex-shrink-0">
+ {!isBuiltin && onUninstall && (
+ <Button
+ variant="ghost"
+ size="icon"
+ className="h-6 w-6 text-slate-600 hover:text-red-400 hover:bg-red-500/10"
+ onClick={(e) => { e.stopPropagation(); onUninstall(); }}
+ title="Uninstall"
+ >
+ <Trash2 className="w-3 h-3" />
+ </Button>
+ )}
+ <div onClick={(e) => e.stopPropagation()}>
+ <Switch checked={isActive} onCheckedChange={onToggle} disabled={isError} />
+ </div>
+ </div>
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Marketplace Extension Card
+// ---------------------------------------------------------------------------
+
+function MarketplaceCard({
+ extension,
+ isInstalling,
+ onInstall,
+ onClick,
+}: {
+ extension: MarketplaceExtension;
+ isInstalling: boolean;
+ onInstall: () => void;
+ onClick?: () => void;
+}) {
+ return (
+ <div className="flex items-start gap-3 p-3 rounded-xl border border-white/[0.06] bg-white/[0.02] hover:bg-white/[0.04] transition-colors cursor-pointer" onClick={onClick}>
+ <div className="flex-shrink-0 w-8 h-8 rounded-lg bg-gradient-to-br from-white/10 to-white/5 border border-white/10 flex items-center justify-center">
+ {extension.iconUrl ? (
+ <img src={extension.iconUrl} alt="" className="w-5 h-5 rounded" />
+ ) : (
+ <ExtensionIcon icon={undefined} className="w-3.5 h-3.5 text-slate-400" />
+ )}
+ </div>
+
+ <div className="flex-1 min-w-0">
+ <div className="flex items-center gap-1.5">
+ <span className="text-[13px] font-medium text-slate-200 truncate">
+ {extension.name}
+ </span>
+ </div>
+
+ <p className="text-[10px] text-slate-500 mt-0.5">
+ {extension.homepage ? (
+ <a
+ href={extension.homepage}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="hover:text-slate-300 transition-colors"
+ onClick={(e) => e.stopPropagation()}
+ >
+ By {extension.author}
+ </a>
+ ) : (
+ <>By {extension.author}</>
+ )}
+ </p>
+
+ <p className="text-[11px] text-slate-500 mt-0.5 line-clamp-2">
+ {extension.description}
+ </p>
+
+ <div className="flex items-center gap-3 mt-1.5">
+ <span className="flex items-center gap-0.5 text-[10px] text-slate-600">
+ <Download className="w-2.5 h-2.5" />
+ {extension.downloads.toLocaleString()}
+ </span>
+ </div>
+
+ {extension.tags.length > 0 && (
+ <div className="flex gap-1 mt-1.5 flex-wrap">
+ {extension.tags.slice(0, 3).map((tag) => (
+ <span
+ key={tag}
+ className="text-[8px] px-1 py-[1px] rounded bg-[#2563EB]/10 text-[#2563EB]/70 font-medium"
+ >
+ {tag}
+ </span>
+ ))}
+ </div>
+ )}
+ </div>
+
+ <div className="flex-shrink-0">
+ {extension.installed ? (
+ <span className="flex items-center gap-1 text-[10px] text-emerald-500 font-medium">
+ <Check className="w-3 h-3" />
+ Installed
+ </span>
+ ) : (
+ <Button
+ variant="ghost"
+ size="sm"
+ className="h-7 px-2.5 text-[11px] text-[#2563EB] hover:text-[#2563EB] hover:bg-[#2563EB]/10 font-medium gap-1"
+ onClick={(e) => { e.stopPropagation(); onInstall(); }}
+ disabled={isInstalling}
+ >
+ {isInstalling ? (
+ <Loader2 className="w-3 h-3 animate-spin" />
+ ) : (
+ <Download className="w-3 h-3" />
+ )}
+ {isInstalling ? "Installing" : "Install"}
+ </Button>
+ )}
+ </div>
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Extension Detail (unified type for installed + marketplace)
+// ---------------------------------------------------------------------------
+
+type ExtensionDetailData =
+ | { source: 'installed'; ext: ExtensionInfo; isActive: boolean }
+ | { source: 'marketplace'; ext: MarketplaceExtension };
+
+function ExtensionDetailModal({
+ detail,
+ onClose,
+ onToggle,
+ onInstall,
+ isInstalling,
+}: {
+ detail: ExtensionDetailData;
+ onClose: () => void;
+ onToggle?: () => void;
+ onInstall?: () => void;
+ isInstalling?: boolean;
+}) {
+ const isInstalled = detail.source === 'installed';
+ const name = isInstalled ? detail.ext.manifest.name : detail.ext.name;
+ const description = isInstalled
+ ? detail.ext.manifest.description || 'No description'
+ : detail.ext.description || 'No description';
+ const author = isInstalled ? detail.ext.manifest.author : detail.ext.author;
+ const permissions = isInstalled ? detail.ext.manifest.permissions : detail.ext.permissions;
+ const homepage = isInstalled ? detail.ext.manifest.homepage : detail.ext.homepage;
+ const isError = isInstalled ? detail.ext.status === 'error' : false;
+
+ return (
+ <Dialog open onOpenChange={(open) => { if (!open) onClose(); }}>
+ <DialogContent className="max-w-md bg-[#161619] border-white/10 text-slate-200 p-0 gap-0 overflow-hidden">
+ {/* Header */}
+ <div className="p-5 pb-4">
+ <div className="flex items-start gap-3.5">
+ <div className="flex-shrink-0 w-12 h-12 rounded-xl bg-gradient-to-br from-[#2563EB]/20 to-[#2563EB]/5 border border-white/10 flex items-center justify-center">
+ {detail.source === 'marketplace' && detail.ext.iconUrl ? (
+ <img src={detail.ext.iconUrl} alt="" className="w-7 h-7 rounded-lg" />
+ ) : (
+ <ExtensionIcon
+ icon={isInstalled ? detail.ext.manifest.icon : undefined}
+ extensionPath={isInstalled ? detail.ext.path : undefined}
+ className="w-5 h-5 text-[#2563EB]/60"
+ />
+ )}
+ </div>
+ <div className="flex-1 min-w-0">
+ <div className="flex items-center gap-1.5">
+ <h2 className="text-[15px] font-semibold text-white truncate">{name}</h2>
+ </div>
+ <p className="text-[11px] text-slate-500 mt-0.5">
+ {author ? (
+ homepage ? (
+ <a
+ href={homepage}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="hover:text-slate-300 transition-colors inline-flex items-center gap-1"
+ >
+ By {author}
+ <ExternalLink className="w-2.5 h-2.5" />
+ </a>
+ ) : (
+ <>By {author}</>
+ )
+ ) : 'Unknown author'}
+ </p>
+ </div>
+ </div>
+
+ {/* Stats for marketplace extensions */}
+ {detail.source === 'marketplace' && (
+ <div className="flex items-center gap-3 mt-3">
+ <span className="flex items-center gap-1 text-[11px] text-slate-500">
+ <Download className="w-3 h-3" />
+ {detail.ext.downloads.toLocaleString()} downloads
+ </span>
+ </div>
+ )}
+ </div>
+
+ {/* Body */}
+ <div className="px-5 pb-5 space-y-4 max-h-[50vh] overflow-y-auto custom-scrollbar">
+ {/* Description */}
+ <div>
+ <p className="text-[10px] font-semibold uppercase tracking-widest text-slate-500 mb-1.5">
+ Description
+ </p>
+ <p className="text-[12px] text-slate-400 leading-relaxed whitespace-pre-wrap">
+ {description}
+ </p>
+ </div>
+
+ {/* Tags */}
+ {detail.source === 'marketplace' && detail.ext.tags.length > 0 && (
+ <div>
+ <p className="text-[10px] font-semibold uppercase tracking-widest text-slate-500 mb-1.5">
+ Tags
+ </p>
+ <div className="flex flex-wrap gap-1.5">
+ {detail.ext.tags.map((tag) => (
+ <span
+ key={tag}
+ className="inline-flex items-center gap-1 text-[10px] px-2 py-0.5 rounded-full bg-[#2563EB]/10 text-[#2563EB]/70 font-medium"
+ >
+ <Tag className="w-2.5 h-2.5" />
+ {tag}
+ </span>
+ ))}
+ </div>
+ </div>
+ )}
+
+ {/* Permissions */}
+ {permissions.length > 0 && (
+ <div>
+ <p className="text-[10px] font-semibold uppercase tracking-widest text-slate-500 mb-1.5">
+ Permissions
+ </p>
+ <div className="flex flex-wrap gap-1.5">
+ {permissions.map((perm) => (
+ <span
+ key={perm}
+ className="text-[10px] px-2 py-0.5 rounded bg-white/5 text-slate-400 font-mono"
+ >
+ {perm}
+ </span>
+ ))}
+ </div>
+ </div>
+ )}
+
+ {/* Path (installed extensions) */}
+ {isInstalled && (
+ <div>
+ <p className="text-[10px] font-semibold uppercase tracking-widest text-slate-500 mb-1.5">
+ Location
+ </p>
+ <p className="text-[10px] text-slate-500 font-mono break-all">
+ {detail.ext.path}
+ </p>
+ </div>
+ )}
+
+ {/* Error */}
+ {isError && isInstalled && detail.ext.error && (
+ <div className="p-2.5 rounded-lg bg-red-500/10 border border-red-500/20">
+ <p className="text-[11px] text-red-400">{detail.ext.error}</p>
+ </div>
+ )}
+ </div>
+
+ {/* Footer actions */}
+ <div className="flex items-center gap-2 px-5 py-3 border-t border-white/[0.06] bg-white/[0.02]">
+ {isInstalled && onToggle && (
+ <div className="flex items-center gap-2">
+ <Switch
+ checked={detail.isActive}
+ onCheckedChange={onToggle}
+ disabled={isError}
+ />
+ <span className="text-[11px] text-slate-400">
+ {detail.isActive ? 'Enabled' : 'Disabled'}
+ </span>
+ </div>
+ )}
+ {detail.source === 'marketplace' && !detail.ext.installed && onInstall && (
+ <Button
+ size="sm"
+ className="h-8 px-3 text-[12px] bg-[#2563EB] hover:bg-[#2563EB]/90 text-white gap-1.5"
+ onClick={onInstall}
+ disabled={isInstalling}
+ >
+ {isInstalling ? (
+ <Loader2 className="w-3.5 h-3.5 animate-spin" />
+ ) : (
+ <Download className="w-3.5 h-3.5" />
+ )}
+ {isInstalling ? 'Installing...' : 'Install'}
+ </Button>
+ )}
+ {detail.source === 'marketplace' && detail.ext.installed && (
+ <span className="flex items-center gap-1 text-[11px] text-emerald-500 font-medium">
+ <Check className="w-3.5 h-3.5" />
+ Installed
+ </span>
+ )}
+ <div className="flex-1" />
+ <Button
+ variant="ghost"
+ size="sm"
+ className="h-8 px-3 text-[12px] text-slate-400 hover:text-slate-200 hover:bg-white/10"
+ onClick={onClose}
+ >
+ Close
+ </Button>
+ </div>
+ </DialogContent>
+ </Dialog>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Tab Switcher (LayoutGroup pill animation — matches SettingsPanel pattern)
+// ---------------------------------------------------------------------------
+
+function TabSwitcher({
+ activeTab,
+ onTabChange,
+ extensionCount,
+}: {
+ activeTab: ExtensionTab;
+ onTabChange: (tab: ExtensionTab) => void;
+ extensionCount: number;
+}) {
+ return (
+ <LayoutGroup id="extension-tab-switcher">
+ <div className="grid h-8 w-full grid-cols-2 rounded-xl border border-white/10 bg-white/[0.04] p-1">
+ {TAB_OPTIONS.map((option) => {
+ const isActive = activeTab === option.value;
+ const count = option.value === "installed" ? extensionCount : undefined;
+ return (
+ <button
+ key={option.value}
+ type="button"
+ onClick={() => onTabChange(option.value)}
+ className="relative rounded-lg text-[10px] font-semibold tracking-wide transition-colors"
+ >
+ {isActive ? (
+ <motion.span
+ layoutId="extension-tab-pill"
+ className="absolute inset-0 rounded-lg bg-[#2563EB]"
+ transition={{ type: "spring", stiffness: 420, damping: 34 }}
+ />
+ ) : null}
+ <span
+ className={cn(
+ "relative z-10 flex items-center justify-center gap-1",
+ isActive ? "text-white" : "text-slate-400 hover:text-slate-200",
+ )}
+ >
+ {option.label}
+ {count !== undefined && count > 0 && (
+ <span
+ className={cn(
+ "text-[8px] px-1 rounded-full font-semibold min-w-[14px] text-center leading-[14px]",
+ isActive ? "bg-white/20 text-white" : "bg-white/5 text-slate-600",
+ )}
+ >
+ {count}
+ </span>
+ )}
+ </span>
+ </button>
+ );
+ })}
+ </div>
+ </LayoutGroup>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Main Component
+// ---------------------------------------------------------------------------
+
+export default function ExtensionManager() {
+ const {
+ extensions,
+ activeIds,
+ ready,
+ refresh,
+ toggleExtension,
+ installFromFolder,
+ uninstall,
+ openDirectory,
+ marketplaceSearch,
+ marketplaceInstall,
+ } = useExtensions();
+
+ const [activeTab, setActiveTab] = useState<ExtensionTab>("browse");
+ const [isRefreshing, setIsRefreshing] = useState(false);
+
+ // Marketplace state
+ const [searchQuery, setSearchQuery] = useState("");
+ const [marketplaceResults, setMarketplaceResults] = useState<MarketplaceExtension[]>([]);
+ const [marketplaceLoading, setMarketplaceLoading] = useState(false);
+ const [marketplaceError, setMarketplaceError] = useState<string | null>(null);
+ const [installingIds, setInstallingIds] = useState<Set<string>>(new Set());
+
+ // Extension detail modal state
+ const [detailData, setDetailData] = useState<ExtensionDetailData | null>(null);
+
+ const handleInstallFromFolder = useCallback(async () => {
+ const success = await installFromFolder();
+ if (success) {
+ toast.success("Extension installed and enabled");
+ }
+ }, [installFromFolder]);
+
+ const handleUninstall = useCallback(
+ async (id: string, name: string) => {
+ const success = await uninstall(id);
+ if (success) {
+ toast.success(`Uninstalled ${name}`);
+ } else {
+ toast.error(`Failed to uninstall ${name}`);
+ }
+ },
+ [uninstall],
+ );
+
+ // Marketplace search
+ const handleSearch = useCallback(async () => {
+ setMarketplaceLoading(true);
+ setMarketplaceError(null);
+ try {
+ const result = await marketplaceSearch({
+ query: searchQuery || undefined,
+ sort: "popular",
+ pageSize: 50,
+ });
+ setMarketplaceResults(result.extensions);
+ } catch (err: any) {
+ setMarketplaceError(err.message ?? "Failed to search marketplace");
+ setMarketplaceResults([]);
+ } finally {
+ setMarketplaceLoading(false);
+ }
+ }, [searchQuery, marketplaceSearch]);
+
+ const handleRefresh = useCallback(async () => {
+ setIsRefreshing(true);
+ try {
+ await refresh();
+
+ if (activeTab === "browse") {
+ await handleSearch();
+ }
+
+ toast.success("Extensions refreshed");
+ } catch {
+ toast.error("Failed to refresh extensions");
+ } finally {
+ setIsRefreshing(false);
+ }
+ }, [activeTab, handleSearch, refresh]);
+
+ // Auto-search when switching to browse tab
+ useEffect(() => {
+ if (activeTab === "browse" && marketplaceResults.length === 0 && !marketplaceLoading) {
+ handleSearch();
+ }
+ }, [activeTab]); // eslint-disable-line react-hooks/exhaustive-deps
+
+ // Marketplace install
+ const handleMarketplaceInstall = useCallback(
+ async (ext: MarketplaceExtension) => {
+ setInstallingIds((prev) => new Set(prev).add(ext.id));
+ try {
+ const result = await marketplaceInstall(ext.id, ext.downloadUrl);
+ if (result.success) {
+ toast.success(`Installed and enabled ${ext.name}`);
+ // Update the marketplace results to show installed state
+ setMarketplaceResults((prev) =>
+ prev.map((e) => (e.id === ext.id ? { ...e, installed: true } : e)),
+ );
+ } else {
+ toast.error(`Failed to install ${ext.name}`, {
+ description: result.error,
+ });
+ }
+ } finally {
+ setInstallingIds((prev) => {
+ const next = new Set(prev);
+ next.delete(ext.id);
+ return next;
+ });
+ }
+ },
+ [marketplaceInstall],
+ );
+
+ if (!ready) {
+ return (
+ <div className="flex-[2] w-[332px] min-w-[280px] max-w-[332px] bg-[#161619] border border-white/10 rounded-2xl flex flex-col shadow-xl h-full overflow-hidden">
+ <div className="flex-1 flex items-center justify-center">
+ <Loader2 className="w-5 h-5 text-slate-600 animate-spin" />
+ </div>
+ </div>
+ );
+ }
+
+ return (
+ <div className="flex-[2] w-[332px] min-w-[280px] max-w-[332px] bg-[#161619] border border-white/10 rounded-2xl flex flex-col shadow-xl h-full overflow-hidden">
+ {/* Header */}
+ <div className="flex-shrink-0 p-4 pb-3">
+ <div className="flex items-center justify-between mb-3">
+ <div className="flex items-center gap-2">
+ <Puzzle className="w-4 h-4 text-[#2563EB]" />
+ <h3 className="text-[13px] font-semibold text-slate-200">Extensions</h3>
+ </div>
+ <div className="flex items-center gap-0.5">
+ <Button
+ variant="ghost"
+ size="icon"
+ className="h-6 w-6 text-slate-500 hover:text-slate-300 hover:bg-white/10"
+ onClick={() => (window as any).electronAPI?.openExternalUrl(EXTENSIONS_DOCS_URL)}
+ title="Extension docs"
+ >
+ <BookOpen className="w-3 h-3" />
+ </Button>
+ <Button
+ variant="ghost"
+ size="icon"
+ className="h-6 w-6 text-slate-500 hover:text-slate-300 hover:bg-white/10"
+ onClick={handleRefresh}
+ disabled={isRefreshing}
+ title="Refresh"
+ >
+ <RefreshCw className={cn("w-3 h-3", isRefreshing && "animate-spin")} />
+ </Button>
+ <Button
+ variant="ghost"
+ size="icon"
+ className="h-6 w-6 text-slate-500 hover:text-slate-300 hover:bg-white/10"
+ onClick={openDirectory}
+ title="Open extensions folder"
+ >
+ <FolderOpen className="w-3 h-3" />
+ </Button>
+ </div>
+ </div>
+
+ <TabSwitcher
+ activeTab={activeTab}
+ onTabChange={setActiveTab}
+ extensionCount={extensions.length}
+ />
+ </div>
+
+ {/* Content */}
+ <div className="flex-1 min-h-0 overflow-y-auto custom-scrollbar p-4 pb-0 pt-0" style={{ scrollbarGutter: "stable" }}>
+ <AnimatePresence mode="wait" initial={false}>
+ <motion.div
+ key={activeTab}
+ initial={{ opacity: 0, y: 8 }}
+ animate={{ opacity: 1, y: 0 }}
+ exit={{ opacity: 0, y: -8 }}
+ transition={{ duration: 0.18, ease: "easeOut" }}
+ >
+ {activeTab === "installed" && (
+ <InstalledTab
+ extensions={extensions}
+ activeIds={activeIds}
+ onToggle={toggleExtension}
+ onUninstall={handleUninstall}
+ onInstallFromFolder={handleInstallFromFolder}
+ onOpenDirectory={openDirectory}
+ onViewDetail={(ext) =>
+ setDetailData({ source: 'installed', ext, isActive: activeIds.has(ext.manifest.id) })
+ }
+ />
+ )}
+
+ {activeTab === "browse" && (
+ <BrowseTab
+ searchQuery={searchQuery}
+ onSearchQueryChange={setSearchQuery}
+ onSearch={handleSearch}
+ results={marketplaceResults}
+ loading={marketplaceLoading}
+ error={marketplaceError}
+ installingIds={installingIds}
+ onInstall={handleMarketplaceInstall}
+ onViewDetail={(ext) => setDetailData({ source: 'marketplace', ext })}
+ />
+ )}
+ </motion.div>
+ </AnimatePresence>
+ </div>
+
+ {/* Extension Detail Modal */}
+ {detailData && (
+ <ExtensionDetailModal
+ detail={detailData}
+ onClose={() => setDetailData(null)}
+ onToggle={
+ detailData.source === 'installed'
+ ? () => {
+ toggleExtension(detailData.ext.manifest.id);
+ setDetailData((prev) =>
+ prev?.source === 'installed'
+ ? { ...prev, isActive: !prev.isActive }
+ : prev,
+ );
+ }
+ : undefined
+ }
+ onInstall={
+ detailData.source === 'marketplace' && !detailData.ext.installed
+ ? () => handleMarketplaceInstall(detailData.ext as MarketplaceExtension)
+ : undefined
+ }
+ isInstalling={
+ detailData.source === 'marketplace'
+ ? installingIds.has(detailData.ext.id)
+ : false
+ }
+ />
+ )}
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Installed Tab
+// ---------------------------------------------------------------------------
+
+function InstalledTab({
+ extensions,
+ activeIds,
+ onToggle,
+ onUninstall,
+ onInstallFromFolder,
+ onOpenDirectory,
+ onViewDetail,
+}: {
+ extensions: ExtensionInfo[];
+ activeIds: Set<string>;
+ onToggle: (id: string) => Promise<void>;
+ onUninstall: (id: string, name: string) => void;
+ onInstallFromFolder: () => void;
+ onOpenDirectory: () => void;
+ onViewDetail: (ext: ExtensionInfo) => void;
+}) {
+ if (extensions.length === 0) {
+ return (
+ <div className="flex flex-col items-center justify-center gap-3 py-10">
+ <div className="w-11 h-11 rounded-full bg-white/[0.04] flex items-center justify-center">
+ <Puzzle className="w-5 h-5 text-slate-600" />
+ </div>
+ <div className="text-center">
+ <p className="text-[13px] font-medium text-slate-400">No Extensions</p>
+ <p className="text-[11px] text-slate-600 mt-1 leading-relaxed max-w-[200px]">
+ Install extensions to add frames, cursor effects, and editor tools.
+ </p>
+ </div>
+ <div className="flex gap-2 mt-2">
+ <Button
+ variant="ghost"
+ size="sm"
+ className="h-7 px-2.5 text-[11px] text-slate-400 hover:text-slate-200 hover:bg-white/10 gap-1"
+ onClick={onInstallFromFolder}
+ >
+ <Plus className="w-3 h-3" />
+ Install
+ </Button>
+ <Button
+ variant="ghost"
+ size="sm"
+ className="h-7 px-2.5 text-[11px] text-slate-400 hover:text-slate-200 hover:bg-white/10 gap-1"
+ onClick={onOpenDirectory}
+ >
+ <FolderOpen className="w-3 h-3" />
+ Folder
+ </Button>
+ </div>
+ </div>
+ );
+ }
+
+ return (
+ <div className="flex flex-col gap-2">
+ <div className="flex items-center justify-between mb-1">
+ <p className="text-[10px] font-semibold uppercase tracking-widest text-slate-400">
+ Installed
+ </p>
+ <Button
+ variant="ghost"
+ size="sm"
+ className="h-6 px-2 text-[10px] text-slate-500 hover:text-slate-300 hover:bg-white/10 gap-1"
+ onClick={onInstallFromFolder}
+ >
+ <Plus className="w-2.5 h-2.5" />
+ Add
+ </Button>
+ </div>
+ {extensions.map((ext) => (
+ <InstalledExtensionCard
+ key={ext.manifest.id}
+ extension={ext}
+ isActive={activeIds.has(ext.manifest.id)}
+ onToggle={() => onToggle(ext.manifest.id)}
+ onUninstall={
+ ext.builtin
+ ? undefined
+ : () => onUninstall(ext.manifest.id, ext.manifest.name)
+ }
+ onClick={() => onViewDetail(ext)}
+ />
+ ))}
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Browse Tab
+// ---------------------------------------------------------------------------
+
+function BrowseTab({
+ searchQuery,
+ onSearchQueryChange,
+ onSearch,
+ results,
+ loading,
+ error,
+ installingIds,
+ onInstall,
+ onViewDetail,
+}: {
+ searchQuery: string;
+ onSearchQueryChange: (q: string) => void;
+ onSearch: () => void;
+ results: MarketplaceExtension[];
+ loading: boolean;
+ error: string | null;
+ installingIds: Set<string>;
+ onInstall: (ext: MarketplaceExtension) => void;
+ onViewDetail: (ext: MarketplaceExtension) => void;
+}) {
+ return (
+ <div className="flex flex-col gap-3">
+ {/* Search */}
+ <div className="relative">
+ <Search className="absolute left-2.5 top-1/2 -translate-y-1/2 w-3.5 h-3.5 text-slate-500 pointer-events-none" />
+ <input
+ type="text"
+ placeholder="Search extensions..."
+ value={searchQuery}
+ onChange={(e) => onSearchQueryChange(e.target.value)}
+ onKeyDown={(e) => {
+ e.stopPropagation();
+ if (e.key === "Enter") onSearch();
+ }}
+ className="w-full h-8 pl-8 pr-3 rounded-lg bg-white/[0.04] border border-white/[0.08] text-[12px] text-slate-200 placeholder:text-slate-600 focus:outline-none focus:ring-1 focus:ring-[#2563EB]/50 focus:border-[#2563EB]/30 transition-colors"
+ />
+ </div>
+
+ {/* Results */}
+ {loading && (
+ <div className="flex items-center justify-center py-10">
+ <Loader2 className="w-5 h-5 text-slate-600 animate-spin" />
+ </div>
+ )}
+
+ {error && (
+ <div className="flex flex-col items-center gap-2 py-8">
+ <ShieldAlert className="w-5 h-5 text-red-400/60" />
+ <p className="text-[11px] text-red-400/80 text-center max-w-[200px]">{error}</p>
+ <Button
+ variant="ghost"
+ size="sm"
+ className="h-7 px-2.5 text-[11px] text-slate-400 hover:text-slate-200 hover:bg-white/10"
+ onClick={onSearch}
+ >
+ Retry
+ </Button>
+ </div>
+ )}
+
+ {!loading && !error && results.length === 0 && (
+ <div className="flex flex-col items-center gap-2 py-10">
+ <Search className="w-5 h-5 text-slate-600" />
+ <p className="text-[11px] text-slate-600 text-center">
+ {searchQuery ? "No extensions found" : "No marketplace extensions available yet"}
+ </p>
+ </div>
+ )}
+
+ {!loading && !error && results.length > 0 && (
+ <div className="flex flex-col gap-2">
+ <p className="text-[10px] font-semibold uppercase tracking-widest text-slate-400">
+ {results.length} extension{results.length !== 1 ? "s" : ""}
+ </p>
+ {results.map((ext) => (
+ <MarketplaceCard
+ key={ext.id}
+ extension={ext}
+ isInstalling={installingIds.has(ext.id)}
+ onInstall={() => onInstall(ext)}
+ onClick={() => onViewDetail(ext)}
+ />
+ ))}
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/src/hooks/useExtensions.ts b/src/hooks/useExtensions.ts
new file mode 100644
index 00000000..7f84f9d1
--- /dev/null
+++ b/src/hooks/useExtensions.ts
@@ -0,0 +1,247 @@
+/**
+ * useExtensions — React hook for managing extensions in the editor.
+ *
+ * Handles discovery, activation/deactivation, marketplace browsing,
+ * downloading, and provides the extension host instance to components
+ * that need render hooks.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { extensionHost } from '@/lib/extensions';
+import type { ExtensionInfo, MarketplaceSearchResult, ExtensionReview, MarketplaceReviewStatus } from '@/lib/extensions';
+import { createExtensionModuleUrl } from '@/lib/extensions/fileUrls';
+
+const electronAPI = (window as any).electronAPI;
+
+export interface UseExtensionsResult {
+ /** All discovered extensions */
+ extensions: ExtensionInfo[];
+ /** Currently active extension IDs */
+ activeIds: Set<string>;
+ /** Whether initial discovery is complete */
+ ready: boolean;
+ /** Discover/refresh extensions from disk */
+ refresh: () => Promise<void>;
+ /** Toggle an extension on/off */
+ toggleExtension: (id: string) => Promise<void>;
+ /** Install an extension from a folder */
+ installFromFolder: () => Promise<boolean>;
+ /** Uninstall an extension */
+ uninstall: (id: string) => Promise<boolean>;
+ /** Open the extensions directory in Finder/Explorer */
+ openDirectory: () => Promise<void>;
+ /** Search the marketplace */
+ marketplaceSearch: (params: {
+ query?: string;
+ tags?: string[];
+ sort?: 'popular' | 'recent' | 'rating';
+ page?: number;
+ pageSize?: number;
+ }) => Promise<MarketplaceSearchResult>;
+ /** Download and install from marketplace */
+ marketplaceInstall: (extensionId: string, downloadUrl: string) => Promise<{ success: boolean; error?: string }>;
+ /** Submit extension for review */
+ marketplaceSubmit: (extensionId: string) => Promise<{ success: boolean; error?: string }>;
+ /** Fetch pending reviews (admin) */
+ fetchReviews: (params: {
+ status?: MarketplaceReviewStatus;
+ page?: number;
+ pageSize?: number;
+ }) => Promise<{ reviews: ExtensionReview[]; total: number }>;
+ /** Update review status (admin) */
+ updateReview: (reviewId: string, status: MarketplaceReviewStatus, notes?: string) => Promise<{ success: boolean }>;
+}
+
+export function useExtensions(): UseExtensionsResult {
+ const [extensions, setExtensions] = useState<ExtensionInfo[]>([]);
+ const [activeIds, setActiveIds] = useState<Set<string>>(new Set());
+ const [ready, setReady] = useState(false);
+ const activatingRef = useRef(new Set<string>());
+
+ const discoverAndSync = useCallback(async (): Promise<ExtensionInfo[]> => {
+ if (!electronAPI?.extensionsDiscover) return [];
+
+ const discovered: ExtensionInfo[] = await electronAPI.extensionsDiscover();
+ setExtensions(discovered);
+ setReady(true);
+ await extensionHost.syncConfiguredExtensions(discovered);
+
+ return discovered;
+ }, []);
+
+ const refresh = useCallback(async () => {
+ await discoverAndSync();
+ }, [discoverAndSync]);
+
+ // Auto-discover on mount and restore extensions marked active.
+ useEffect(() => {
+ void discoverAndSync();
+ }, [discoverAndSync]);
+
+ // Sync activeIds with extension host (immediate + future changes)
+ useEffect(() => {
+ const sync = () => {
+ const active = extensionHost.getActiveExtensions();
+ setActiveIds(new Set(active.map(e => e.manifest.id)));
+ };
+ // Immediately sync with any already-active extensions
+ sync();
+ return extensionHost.onChange(sync);
+ }, []);
+
+ const toggleExtension = useCallback(async (id: string) => {
+ if (activatingRef.current.has(id)) return;
+ activatingRef.current.add(id);
+
+ try {
+ if (activeIds.has(id)) {
+ await extensionHost.deactivateExtension(id);
+ await electronAPI?.extensionsDisable(id);
+ setExtensions((prev) =>
+ prev.map((ext) => (ext.manifest.id === id ? { ...ext, status: 'disabled' } : ext)),
+ );
+ } else {
+ const ext = extensions.find(e => e.manifest.id === id);
+ if (!ext || ext.status === 'error') return;
+
+ try {
+ await electronAPI?.extensionsEnable(id);
+
+ const moduleUrl = createExtensionModuleUrl(ext.path, ext.manifest.main);
+ await extensionHost.activateExtension(ext, moduleUrl);
+ setExtensions((prev) =>
+ prev.map((candidate) => (candidate.manifest.id === id ? { ...candidate, status: 'active' } : candidate)),
+ );
+ } catch (err) {
+ await electronAPI?.extensionsDisable(id);
+ setExtensions((prev) =>
+ prev.map((candidate) => (candidate.manifest.id === id ? { ...candidate, status: 'disabled' } : candidate)),
+ );
+ throw err;
+ }
+ }
+ } catch (err) {
+ console.error(`[extensions] Failed to toggle ${id}:`, err);
+ } finally {
+ activatingRef.current.delete(id);
+ }
+ }, [activeIds, extensions]);
+
+ const installFromFolder = useCallback(async (): Promise<boolean> => {
+ if (!electronAPI?.extensionsInstallFromFolder) return false;
+ const result = await electronAPI.extensionsInstallFromFolder();
+ if (result?.success) {
+ const extensionId = result.extension?.manifest?.id;
+ if (typeof extensionId === 'string') {
+ await electronAPI?.extensionsEnable(extensionId);
+ }
+ await discoverAndSync();
+ return true;
+ }
+ return false;
+ }, [discoverAndSync]);
+
+ const uninstall = useCallback(async (id: string): Promise<boolean> => {
+ // Deactivate first if active
+ if (activeIds.has(id)) {
+ await extensionHost.deactivateExtension(id);
+ }
+ if (!electronAPI?.extensionsUninstall) return false;
+ const result = await electronAPI.extensionsUninstall(id);
+ if (result?.success) {
+ await discoverAndSync();
+ return true;
+ }
+ return false;
+ }, [activeIds, discoverAndSync]);
+
+ const openDirectory = useCallback(async () => {
+ await electronAPI?.extensionsOpenDirectory();
+ }, []);
+
+ const marketplaceSearch = useCallback(async (params: {
+ query?: string;
+ tags?: string[];
+ sort?: 'popular' | 'recent' | 'rating';
+ page?: number;
+ pageSize?: number;
+ }): Promise<MarketplaceSearchResult> => {
+ if (!electronAPI?.extensionsMarketplaceSearch) {
+ return { extensions: [], total: 0, page: 1, pageSize: 20 };
+ }
+
+ const result = await electronAPI.extensionsMarketplaceSearch(params) as MarketplaceSearchResult & {
+ error?: string;
+ };
+
+ if (result?.error) {
+ throw new Error(result.error);
+ }
+
+ return result;
+ }, []);
+
+ const marketplaceInstall = useCallback(async (extensionId: string, downloadUrl: string) => {
+ if (!electronAPI?.extensionsMarketplaceInstall) {
+ return { success: false, error: 'Not available' };
+ }
+ const result = await electronAPI.extensionsMarketplaceInstall(extensionId, downloadUrl);
+ if (result.success) {
+ await electronAPI?.extensionsEnable(extensionId);
+ await discoverAndSync();
+ }
+ return result;
+ }, [discoverAndSync]);
+
+ const marketplaceSubmit = useCallback(async (extensionId: string) => {
+ if (!electronAPI?.extensionsMarketplaceSubmit) {
+ return { success: false, error: 'Not available' };
+ }
+ return electronAPI.extensionsMarketplaceSubmit(extensionId);
+ }, []);
+
+ const fetchReviews = useCallback(async (params: {
+ status?: MarketplaceReviewStatus;
+ page?: number;
+ pageSize?: number;
+ }) => {
+ if (!electronAPI?.extensionsReviewsList) {
+ return { reviews: [] as ExtensionReview[], total: 0 };
+ }
+
+ const result = await electronAPI.extensionsReviewsList(params) as {
+ reviews: ExtensionReview[];
+ total: number;
+ error?: string;
+ };
+
+ if (result?.error) {
+ throw new Error(result.error);
+ }
+
+ return result;
+ }, []);
+
+ const updateReview = useCallback(async (reviewId: string, status: MarketplaceReviewStatus, notes?: string) => {
+ if (!electronAPI?.extensionsReviewUpdate) {
+ return { success: false };
+ }
+ return electronAPI.extensionsReviewUpdate(reviewId, status, notes);
+ }, []);
+
+ return {
+ extensions,
+ activeIds,
+ ready,
+ refresh,
+ toggleExtension,
+ installFromFolder,
+ uninstall,
+ openDirectory,
+ marketplaceSearch,
+ marketplaceInstall,
+ marketplaceSubmit,
+ fetchReviews,
+ updateReview,
+ };
+}
diff --git a/src/lib/extensions/cursorCoordinates.ts b/src/lib/extensions/cursorCoordinates.ts
new file mode 100644
index 00000000..ffc62694
--- /dev/null
+++ b/src/lib/extensions/cursorCoordinates.ts
@@ -0,0 +1,92 @@
+interface CursorLike {
+ cx: number;
+ cy: number;
+ interactionType?: string;
+}
+
+export interface SmoothedCursorSnapshot {
+ cx: number;
+ cy: number;
+ trail: Array<{ cx: number; cy: number }>;
+}
+
+interface MaskRectLike {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+}
+
+function clamp01(value: number): number {
+ if (!Number.isFinite(value)) {
+ return 0.5;
+ }
+
+ return Math.min(1, Math.max(0, value));
+}
+
+export function mapCursorToCanvasNormalized<T extends CursorLike>(
+ cursor: T | null,
+ params: {
+ maskRect?: MaskRectLike | null;
+ canvasWidth: number;
+ canvasHeight: number;
+ },
+): T | null {
+ if (!cursor) {
+ return null;
+ }
+
+ const { maskRect, canvasWidth, canvasHeight } = params;
+ if (
+ !maskRect ||
+ maskRect.width <= 0 ||
+ maskRect.height <= 0 ||
+ canvasWidth <= 0 ||
+ canvasHeight <= 0
+ ) {
+ return {
+ ...cursor,
+ cx: clamp01(cursor.cx),
+ cy: clamp01(cursor.cy),
+ };
+ }
+
+ const pixelX = maskRect.x + clamp01(cursor.cx) * maskRect.width;
+ const pixelY = maskRect.y + clamp01(cursor.cy) * maskRect.height;
+
+ return {
+ ...cursor,
+ cx: clamp01(pixelX / canvasWidth),
+ cy: clamp01(pixelY / canvasHeight),
+ };
+}
+
+export function mapSmoothedCursorToCanvasNormalized(
+ cursor: SmoothedCursorSnapshot | null,
+ params: {
+ maskRect?: MaskRectLike | null;
+ canvasWidth: number;
+ canvasHeight: number;
+ },
+): SmoothedCursorSnapshot | null {
+ if (!cursor) {
+ return null;
+ }
+
+ const mappedCursor = mapCursorToCanvasNormalized(
+ { cx: cursor.cx, cy: cursor.cy },
+ params,
+ );
+ if (!mappedCursor) {
+ return null;
+ }
+
+ return {
+ cx: mappedCursor.cx,
+ cy: mappedCursor.cy,
+ trail: cursor.trail
+ .map((point) => mapCursorToCanvasNormalized(point, params))
+ .filter((point): point is { cx: number; cy: number } => point !== null),
+ };
+}
\ No newline at end of file
diff --git a/src/lib/extensions/extensionHost.ts b/src/lib/extensions/extensionHost.ts
new file mode 100644
index 00000000..6443e393
--- /dev/null
+++ b/src/lib/extensions/extensionHost.ts
@@ -0,0 +1,893 @@
+/**
+ * Extension Host — Renderer Process
+ *
+ * Manages the lifecycle of extensions in the renderer. Loads extension
+ * modules, provides the permission-gated host API, and coordinates render hooks.
+ */
+
+import type {
+ ContributedFrame,
+ CursorEffectContext,
+ CursorEffectFn,
+ ExtensionEvent,
+ ExtensionEventHandler,
+ ExtensionEventType,
+ ExtensionInfo,
+ ExtensionSettingsPanel,
+ FrameInstance,
+ RecordlyExtensionAPI,
+ RecordlyExtensionModule,
+ RenderHookContext,
+ RenderHookFn,
+ RenderHookPhase,
+} from "./types";
+import { createExtensionModuleUrl, resolveExtensionRelativeFileUrl } from "./fileUrls";
+
+const EXTENSION_SETTINGS_STORAGE_KEY = "recordly.extension-settings.v1";
+
+// ---------------------------------------------------------------------------
+// Security: Hide electronAPI from extension code
+// ---------------------------------------------------------------------------
+// Extensions run via dynamic import() in the renderer's main world. Since
+// contextBridge.exposeInMainWorld puts electronAPI on window in the same
+// world, extensions could abuse it to read arbitrary files, open URLs, etc.
+// We replace the global with a Proxy that blocks access while extension code
+// is executing (import + activate). The reference is stashed so that only
+// app code (which runs outside of extension activation) can reach it.
+// ---------------------------------------------------------------------------
+
+let _extensionActivationDepth = 0;
+let _realElectronAPI: typeof window.electronAPI | undefined;
+
+function installElectronAPIGuard(): void {
+ if (typeof window === "undefined" || _realElectronAPI !== undefined) return;
+
+ const real = window.electronAPI;
+ if (!real) return;
+
+ _realElectronAPI = real;
+
+ const proxy = new Proxy(real, {
+ get(target, prop, receiver) {
+ if (_extensionActivationDepth > 0) {
+ console.warn(
+ `[extensions] Blocked extension access to electronAPI.${String(prop)}`,
+ );
+ return undefined;
+ }
+ return Reflect.get(target, prop, receiver);
+ },
+ });
+
+ Object.defineProperty(window, "electronAPI", {
+ value: proxy,
+ writable: false,
+ configurable: false,
+ });
+}
+
+installElectronAPIGuard();
+
+interface RegisteredRenderHook {
+ extensionId: string;
+ phase: RenderHookPhase;
+ hook: RenderHookFn;
+}
+
+interface RegisteredCursorEffect {
+ extensionId: string;
+ effect: CursorEffectFn;
+}
+
+interface RegisteredSettingsPanel {
+ extensionId: string;
+ panel: ExtensionSettingsPanel;
+}
+
+interface ActiveExtension {
+ info: ExtensionInfo;
+ module: RecordlyExtensionModule;
+ disposables: (() => void)[];
+}
+
+/**
+ * The Extension Host manages all loaded extensions and provides
+ * access to their registered hooks, effects, and settings.
+ */
+export class ExtensionHost {
+ private activeExtensions = new Map<string, ActiveExtension>();
+ private renderHooks: RegisteredRenderHook[] = [];
+ private cursorEffects: RegisteredCursorEffect[] = [];
+ private frames: FrameInstance[] = [];
+ private eventHandlers = new Map<
+ ExtensionEventType,
+ { extensionId: string; handler: ExtensionEventHandler }[]
+ >();
+ private settingsPanels: RegisteredSettingsPanel[] = [];
+ private extensionSettings = new Map<string, Record<string, unknown>>();
+ private settingChangeCallbacks = new Map<
+ string,
+ Set<(settingId: string, value: unknown) => void>
+ >();
+ private listeners = new Set<() => void>();
+
+ // Shared playback/project state — set by the app, queried by extensions
+ private _videoInfo: { width: number; height: number; durationMs: number; fps: number } | null =
+ null;
+ private _videoLayout: {
+ maskRect: { x: number; y: number; width: number; height: number };
+ canvasWidth: number;
+ canvasHeight: number;
+ borderRadius: number;
+ padding: number;
+ } | null = null;
+ private _zoomState: { scale: number; focusX: number; focusY: number; progress: number } | null =
+ null;
+ private _shadowConfig: { enabled: boolean; intensity: number } = { enabled: false, intensity: 0 };
+ private _cursorTelemetry: Array<{
+ timeMs: number;
+ cx: number;
+ cy: number;
+ interactionType?: string;
+ pressure?: number;
+ }> = [];
+ private _smoothedCursor: {
+ timeMs: number;
+ cx: number;
+ cy: number;
+ trail: Array<{ cx: number; cy: number }>;
+ } | null = null;
+ private _keystrokeEvents: Array<{ timeMs: number; key: string; modifiers: string[] }> = [];
+ private _activeFrame: string | null = null;
+ private _playbackState: { currentTimeMs: number; durationMs: number; isPlaying: boolean } | null =
+ null;
+
+ /**
+ * Activate an extension given its info and resolved module URL.
+ */
+ async activateExtension(info: ExtensionInfo, moduleUrl: string): Promise<void> {
+ if (this.activeExtensions.has(info.manifest.id)) {
+ console.warn(`[extensions] Extension ${info.manifest.id} is already active`);
+ this.notifyListeners();
+ return;
+ }
+
+ const disposables: (() => void)[] = [];
+ let mod: RecordlyExtensionModule | null = null;
+ try {
+ this.ensureExtensionSettingsLoaded(info.manifest.id);
+
+ // Block electronAPI access while extension code executes
+ _extensionActivationDepth++;
+ try {
+ const loaded: RecordlyExtensionModule = await import(/* @vite-ignore */ moduleUrl);
+ mod = loaded;
+ const api = this.createAPI(
+ info.manifest.id,
+ info.path,
+ info.manifest.permissions ?? [],
+ disposables,
+ );
+
+ await loaded.activate(api);
+ } finally {
+ _extensionActivationDepth--;
+ }
+
+ if (!mod) {
+ throw new Error("Extension module failed to load");
+ }
+
+ this.activeExtensions.set(info.manifest.id, {
+ info,
+ module: mod,
+ disposables,
+ });
+
+ this.notifyListeners();
+ console.log(`[extensions] Activated: ${info.manifest.name} v${info.manifest.version}`);
+ } catch (err) {
+ for (const dispose of disposables.reverse()) {
+ try {
+ dispose();
+ } catch {
+ /* ignore */
+ }
+ }
+
+ if (mod) {
+ try {
+ await mod.deactivate?.();
+ } catch {
+ /* ignore */
+ }
+ }
+
+ this.notifyListeners();
+ console.error(`[extensions] Failed to activate ${info.manifest.id}:`, err);
+ throw err;
+ }
+ }
+
+ /**
+ * Deactivate an extension by ID.
+ */
+ async deactivateExtension(extensionId: string): Promise<void> {
+ const active = this.activeExtensions.get(extensionId);
+ if (!active) return;
+
+ try {
+ await active.module.deactivate?.();
+ } catch (err) {
+ console.warn(`[extensions] Error during deactivate of ${extensionId}:`, err);
+ }
+
+ // Clean up all disposables (unregister hooks, effects, handlers)
+ for (const dispose of active.disposables) {
+ try {
+ dispose();
+ } catch {
+ /* ignore */
+ }
+ }
+
+ this.activeExtensions.delete(extensionId);
+ this.notifyListeners();
+ console.log(`[extensions] Deactivated: ${extensionId}`);
+ }
+
+ /**
+ * Deactivate all extensions.
+ */
+ async deactivateAll(): Promise<void> {
+ const ids = Array.from(this.activeExtensions.keys());
+ for (const id of ids) {
+ await this.deactivateExtension(id);
+ }
+ }
+
+ // ---------------------------------------------------------------------------
+ // Render Pipeline Integration
+ // ---------------------------------------------------------------------------
+
+ /**
+ * Execute all render hooks for a given phase.
+ */
+ executeRenderHooks(phase: RenderHookPhase, context: RenderHookContext): void {
+ const hooks = this.renderHooks.filter((h) => h.phase === phase);
+ for (const hook of hooks) {
+ try {
+ context.ctx.save();
+ hook.hook(context);
+ context.ctx.restore();
+ } catch (err) {
+ console.warn(`[extensions] Render hook error (${hook.extensionId}, ${phase}):`, err);
+ }
+ }
+ }
+
+ /**
+ * Execute all cursor effects. Returns true if any effect is still animating.
+ */
+ executeCursorEffects(context: CursorEffectContext): boolean {
+ let anyActive = false;
+ for (const effect of this.cursorEffects) {
+ try {
+ context.ctx.save();
+ const stillActive = effect.effect(context);
+ context.ctx.restore();
+ if (stillActive) anyActive = true;
+ } catch (err) {
+ console.warn(`[extensions] Cursor effect error (${effect.extensionId}):`, err);
+ }
+ }
+ return anyActive;
+ }
+
+ /**
+ * Emit an event to all registered handlers.
+ */
+ emitEvent(event: ExtensionEvent): void {
+ const handlers = this.eventHandlers.get(event.type);
+ if (!handlers) return;
+
+ for (const { handler } of handlers) {
+ try {
+ handler(event);
+ } catch (err) {
+ console.warn(`[extensions] Event handler error (${event.type}):`, err);
+ }
+ }
+ }
+
+ // ---------------------------------------------------------------------------
+ // Queries
+ // ---------------------------------------------------------------------------
+
+ getActiveExtensions(): ExtensionInfo[] {
+ return Array.from(this.activeExtensions.values()).map((a) => a.info);
+ }
+
+ /** Quick snapshot of video info for callers that need durationMs etc. */
+ getVideoInfoSnapshot(): {
+ width: number;
+ height: number;
+ durationMs: number;
+ fps: number;
+ } | null {
+ return this._videoInfo;
+ }
+
+ getSettingsPanels(): RegisteredSettingsPanel[] {
+ return [...this.settingsPanels];
+ }
+
+ hasRenderHooks(phase: RenderHookPhase): boolean {
+ return this.renderHooks.some((h) => h.phase === phase);
+ }
+
+ hasCursorEffects(): boolean {
+ return this.cursorEffects.length > 0;
+ }
+
+ getExtensionSetting(extensionId: string, settingId: string): unknown {
+ this.ensureExtensionSettingsLoaded(extensionId);
+ return this.extensionSettings.get(extensionId)?.[settingId];
+ }
+
+ setExtensionSetting(extensionId: string, settingId: string, value: unknown): void {
+ this.ensureExtensionSettingsLoaded(extensionId);
+ this.extensionSettings.get(extensionId)![settingId] = value;
+ this.persistExtensionSettings(extensionId);
+ // Notify per-extension setting change listeners
+ const cbs = this.settingChangeCallbacks.get(extensionId);
+ if (cbs) {
+ for (const cb of cbs) {
+ try {
+ cb(settingId, value);
+ } catch {
+ /* ignore */
+ }
+ }
+ }
+ this.notifyListeners();
+ }
+
+ /**
+ * Get all registered device frames from active extensions.
+ */
+ getFrames(): FrameInstance[] {
+ return [...this.frames];
+ }
+
+ /**
+ * Subscribe to changes in extensions (activation/deactivation).
+ */
+ onChange(listener: () => void): () => void {
+ this.listeners.add(listener);
+ return () => this.listeners.delete(listener);
+ }
+
+ // ---------------------------------------------------------------------------
+ // Shared State — set by the app, read by extensions via API
+ // ---------------------------------------------------------------------------
+
+ setVideoInfo(
+ info: { width: number; height: number; durationMs: number; fps: number } | null,
+ ): void {
+ this._videoInfo = info;
+ }
+
+ setVideoLayout(
+ layout: {
+ maskRect: { x: number; y: number; width: number; height: number };
+ canvasWidth: number;
+ canvasHeight: number;
+ borderRadius: number;
+ padding: number;
+ } | null,
+ ): void {
+ this._videoLayout = layout;
+ }
+
+ setZoomState(
+ state: { scale: number; focusX: number; focusY: number; progress: number } | null,
+ ): void {
+ this._zoomState = state;
+ }
+
+ setShadowConfig(config: { enabled: boolean; intensity: number }): void {
+ this._shadowConfig = config;
+ }
+
+ setCursorTelemetry(
+ telemetry: Array<{
+ timeMs: number;
+ cx: number;
+ cy: number;
+ interactionType?: string;
+ pressure?: number;
+ }>,
+ ): void {
+ this._cursorTelemetry = telemetry;
+ }
+
+ setSmoothedCursor(
+ cursor:
+ | {
+ timeMs: number;
+ cx: number;
+ cy: number;
+ trail: Array<{ cx: number; cy: number }>;
+ }
+ | null,
+ ): void {
+ this._smoothedCursor = cursor
+ ? {
+ timeMs: cursor.timeMs,
+ cx: cursor.cx,
+ cy: cursor.cy,
+ trail: cursor.trail.map((point) => ({ ...point })),
+ }
+ : null;
+ }
+
+ setKeystrokeEvents(events: Array<{ timeMs: number; key: string; modifiers: string[] }>): void {
+ this._keystrokeEvents = events;
+ }
+
+ setActiveFrame(frameId: string | null): void {
+ this._activeFrame = frameId;
+ }
+
+ setPlaybackState(
+ state: { currentTimeMs: number; durationMs: number; isPlaying: boolean } | null,
+ ): void {
+ this._playbackState = state;
+ }
+
+ // ---------------------------------------------------------------------------
+ // Private
+ // ---------------------------------------------------------------------------
+
+ private notifyListeners(): void {
+ for (const listener of this.listeners) {
+ try {
+ listener();
+ } catch {
+ /* ignore */
+ }
+ }
+ }
+
+ private readPersistedSettingsStore(): Record<string, Record<string, unknown>> {
+ if (typeof window === "undefined" || !window.localStorage) {
+ return {};
+ }
+
+ try {
+ const raw = window.localStorage.getItem(EXTENSION_SETTINGS_STORAGE_KEY);
+ if (!raw) {
+ return {};
+ }
+
+ const parsed = JSON.parse(raw);
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+ return {};
+ }
+
+ return parsed as Record<string, Record<string, unknown>>;
+ } catch {
+ return {};
+ }
+ }
+
+ private writePersistedSettingsStore(store: Record<string, Record<string, unknown>>): void {
+ if (typeof window === "undefined" || !window.localStorage) {
+ return;
+ }
+
+ try {
+ window.localStorage.setItem(EXTENSION_SETTINGS_STORAGE_KEY, JSON.stringify(store));
+ } catch {
+ // Ignore storage quota / privacy mode failures.
+ }
+ }
+
+ private ensureExtensionSettingsLoaded(extensionId: string): void {
+ if (this.extensionSettings.has(extensionId)) {
+ return;
+ }
+
+ const store = this.readPersistedSettingsStore();
+ const persisted = store[extensionId];
+ const normalized =
+ persisted && typeof persisted === "object" && !Array.isArray(persisted)
+ ? { ...persisted }
+ : {};
+
+ this.extensionSettings.set(extensionId, normalized);
+ }
+
+ private persistExtensionSettings(extensionId: string): void {
+ const store = this.readPersistedSettingsStore();
+ const settings = this.extensionSettings.get(extensionId) ?? {};
+
+ if (Object.keys(settings).length === 0) {
+ delete store[extensionId];
+ } else {
+ store[extensionId] = { ...settings };
+ }
+
+ this.writePersistedSettingsStore(store);
+ }
+
+ /**
+ * Create the permission-gated API object for an extension.
+ */
+ private createAPI(
+ extensionId: string,
+ extensionPath: string,
+ permissions: string[],
+ disposables: (() => void)[],
+ ): RecordlyExtensionAPI {
+ const host = this;
+ const perms = new Set(permissions);
+
+ function requirePermission(perm: string, method: string): void {
+ if (!perms.has(perm)) {
+ throw new Error(
+ `Extension '${extensionId}' lacks '${perm}' permission required for ${method}()`,
+ );
+ }
+ }
+
+ function getEventPermission(
+ event: ExtensionEventType,
+ ): "cursor" | "timeline" | "export" | null {
+ if (event.startsWith("cursor:")) {
+ return "cursor";
+ }
+
+ if (event.startsWith("playback:") || event.startsWith("timeline:")) {
+ return "timeline";
+ }
+
+ if (event.startsWith("export:")) {
+ return "export";
+ }
+
+ return null;
+ }
+
+ return {
+ registerRenderHook(phase: RenderHookPhase, hook: RenderHookFn): () => void {
+ requirePermission("render", "registerRenderHook");
+ const entry: RegisteredRenderHook = { extensionId, phase, hook };
+ host.renderHooks.push(entry);
+
+ const dispose = () => {
+ const index = host.renderHooks.indexOf(entry);
+ if (index >= 0) host.renderHooks.splice(index, 1);
+ };
+ disposables.push(dispose);
+ return dispose;
+ },
+
+ registerCursorEffect(effect: CursorEffectFn): () => void {
+ requirePermission("cursor", "registerCursorEffect");
+ const entry: RegisteredCursorEffect = { extensionId, effect };
+ host.cursorEffects.push(entry);
+
+ const dispose = () => {
+ const index = host.cursorEffects.indexOf(entry);
+ if (index >= 0) host.cursorEffects.splice(index, 1);
+ };
+ disposables.push(dispose);
+ return dispose;
+ },
+
+ registerFrame(frame: ContributedFrame): () => void {
+ requirePermission("ui", "registerFrame");
+ const resolveFramePath = (relativePath: string): string =>
+ resolveExtensionRelativeFileUrl(extensionPath, relativePath);
+
+ let filePath: string;
+ if (frame.draw) {
+ // Generate a small thumbnail for the picker UI
+ const thumbW = 192;
+ const thumbH = 108;
+ const c = document.createElement("canvas");
+ c.width = thumbW;
+ c.height = thumbH;
+ const ctx = c.getContext("2d");
+ if (ctx) frame.draw(ctx, thumbW, thumbH);
+ filePath = c.toDataURL("image/png");
+ } else if (frame.dataUrl) {
+ filePath = frame.dataUrl;
+ } else if (frame.file) {
+ filePath = resolveFramePath(frame.file);
+ } else {
+ throw new Error("Device frame must provide either draw, file, or dataUrl");
+ }
+
+ let thumbnailPath = filePath;
+ if (frame.thumbnail) {
+ thumbnailPath = resolveFramePath(frame.thumbnail);
+ }
+
+ const instance: FrameInstance = {
+ id: `${extensionId}/${frame.id}`,
+ extensionId,
+ label: frame.label,
+ category: frame.category,
+ filePath,
+ thumbnailPath,
+ screenInsets: frame.screenInsets,
+ appearance: frame.appearance,
+ draw: frame.draw,
+ };
+ host.frames.push(instance);
+ host.notifyListeners();
+
+ const dispose = () => {
+ const index = host.frames.indexOf(instance);
+ if (index >= 0) host.frames.splice(index, 1);
+ host.notifyListeners();
+ };
+ disposables.push(dispose);
+ return dispose;
+ },
+
+ on(event: ExtensionEventType, handler: ExtensionEventHandler): () => void {
+ const requiredPermission = getEventPermission(event);
+ if (requiredPermission) {
+ requirePermission(requiredPermission, `on(${event})`);
+ }
+
+ if (!host.eventHandlers.has(event)) {
+ host.eventHandlers.set(event, []);
+ }
+ const entry = { extensionId, handler };
+ host.eventHandlers.get(event)!.push(entry);
+
+ const dispose = () => {
+ const list = host.eventHandlers.get(event);
+ if (!list) return;
+ const index = list.indexOf(entry);
+ if (index >= 0) list.splice(index, 1);
+ };
+ disposables.push(dispose);
+ return dispose;
+ },
+
+ registerSettingsPanel(panel: ExtensionSettingsPanel): () => void {
+ requirePermission("ui", "registerSettingsPanel");
+ const entry: RegisteredSettingsPanel = { extensionId, panel };
+ host.settingsPanels.push(entry);
+ host.notifyListeners();
+
+ const dispose = () => {
+ const index = host.settingsPanels.indexOf(entry);
+ if (index >= 0) host.settingsPanels.splice(index, 1);
+ host.notifyListeners();
+ };
+ disposables.push(dispose);
+ return dispose;
+ },
+
+ getSetting(settingId: string): unknown {
+ host.ensureExtensionSettingsLoaded(extensionId);
+ return host.extensionSettings.get(extensionId)?.[settingId];
+ },
+
+ setSetting(settingId: string, value: unknown): void {
+ host.ensureExtensionSettingsLoaded(extensionId);
+ host.extensionSettings.get(extensionId)![settingId] = value;
+ host.persistExtensionSettings(extensionId);
+ // Notify per-extension setting change listeners
+ const cbs = host.settingChangeCallbacks.get(extensionId);
+ if (cbs) {
+ for (const cb of cbs) {
+ try {
+ cb(settingId, value);
+ } catch {
+ /* ignore */
+ }
+ }
+ }
+ host.notifyListeners();
+ },
+
+ resolveAsset(relativePath: string): string {
+ requirePermission("assets", "resolveAsset");
+ return resolveExtensionRelativeFileUrl(extensionPath, relativePath);
+ },
+
+ playSound(relativePath: string, options?: { volume?: number }): () => void {
+ requirePermission("audio", "playSound");
+ const audio = new Audio(resolveExtensionRelativeFileUrl(extensionPath, relativePath));
+ audio.volume = Math.max(0, Math.min(1, options?.volume ?? 1));
+ audio.play().catch((err) => {
+ console.warn(`[ext:${extensionId}] Failed to play sound:`, err);
+ });
+ return () => {
+ audio.pause();
+ audio.src = "";
+ };
+ },
+
+ log(message: string, ...args: unknown[]): void {
+ console.log(`[ext:${extensionId}]`, message, ...args);
+ },
+
+ // ----------------------------------------------------------------
+ // Query APIs
+ // ----------------------------------------------------------------
+
+ getVideoInfo() {
+ return host._videoInfo ? { ...host._videoInfo } : null;
+ },
+
+ getVideoLayout() {
+ if (!host._videoLayout) return null;
+ return {
+ maskRect: { ...host._videoLayout.maskRect },
+ canvasWidth: host._videoLayout.canvasWidth,
+ canvasHeight: host._videoLayout.canvasHeight,
+ borderRadius: host._videoLayout.borderRadius,
+ padding: host._videoLayout.padding,
+ };
+ },
+
+ getCursorAt(timeMs: number) {
+ const t = host._cursorTelemetry;
+ if (!t || t.length === 0) return null;
+
+ let closest = t[0];
+ let minDist = Math.abs(t[0].timeMs - timeMs);
+ for (let i = 1; i < t.length; i++) {
+ const dist = Math.abs(t[i].timeMs - timeMs);
+ if (dist < minDist) {
+ minDist = dist;
+ closest = t[i];
+ }
+ if (t[i].timeMs > timeMs) break;
+ }
+ return { ...closest };
+ },
+
+ getSmoothedCursor() {
+ if (!host._smoothedCursor) {
+ return null;
+ }
+
+ return {
+ timeMs: host._smoothedCursor.timeMs,
+ cx: host._smoothedCursor.cx,
+ cy: host._smoothedCursor.cy,
+ trail: host._smoothedCursor.trail.map((point) => ({ ...point })),
+ };
+ },
+
+ getZoomState() {
+ return host._zoomState ? { ...host._zoomState } : null;
+ },
+
+ getShadowConfig() {
+ return { ...host._shadowConfig };
+ },
+
+ getKeystrokesInRange(startMs: number, endMs: number) {
+ return host._keystrokeEvents
+ .filter((e) => e.timeMs >= startMs && e.timeMs <= endMs)
+ .map((e) => ({ ...e }));
+ },
+
+ getAspectRatio() {
+ if (!host._videoLayout) return null;
+ return host._videoLayout.canvasWidth / host._videoLayout.canvasHeight;
+ },
+
+ getActiveFrame() {
+ return host._activeFrame;
+ },
+
+ isExtensionActive(extId: string) {
+ return host.activeExtensions.has(extId);
+ },
+
+ getPlaybackState() {
+ return host._playbackState ? { ...host._playbackState } : null;
+ },
+
+ getCanvasDimensions() {
+ if (!host._videoLayout) return null;
+ return { width: host._videoLayout.canvasWidth, height: host._videoLayout.canvasHeight };
+ },
+
+ onSettingChange(callback: (settingId: string, value: unknown) => void): () => void {
+ if (!host.settingChangeCallbacks.has(extensionId)) {
+ host.settingChangeCallbacks.set(extensionId, new Set());
+ }
+ host.settingChangeCallbacks.get(extensionId)!.add(callback);
+
+ const dispose = () => {
+ const cbs = host.settingChangeCallbacks.get(extensionId);
+ if (cbs) {
+ cbs.delete(callback);
+ if (cbs.size === 0) host.settingChangeCallbacks.delete(extensionId);
+ }
+ };
+ disposables.push(dispose);
+ return dispose;
+ },
+
+ getAllSettings(): Record<string, unknown> {
+ host.ensureExtensionSettingsLoaded(extensionId);
+ return { ...(host.extensionSettings.get(extensionId) ?? {}) };
+ },
+ };
+ }
+
+ async syncConfiguredExtensions(discovered: ExtensionInfo[]): Promise<void> {
+ const desired = new Map(
+ discovered.filter((ext) => ext.status === "active").map((ext) => [ext.manifest.id, ext]),
+ );
+
+ for (const activeId of Array.from(this.activeExtensions.keys())) {
+ if (!desired.has(activeId)) {
+ await this.deactivateExtension(activeId);
+ }
+ }
+
+ for (const ext of discovered) {
+ if (ext.status !== "active" || this.activeExtensions.has(ext.manifest.id)) {
+ continue;
+ }
+
+ try {
+ const moduleUrl = createExtensionModuleUrl(ext.path, ext.manifest.main);
+ await this.activateExtension(ext, moduleUrl);
+ } catch (err) {
+ console.error(
+ `[extensions] Failed to activate configured extension ${ext.manifest.id}:`,
+ err,
+ );
+ }
+ }
+ }
+
+ // ---------------------------------------------------------------------------
+ // Auto-Activation (idempotent — safe to call from multiple places)
+ // ---------------------------------------------------------------------------
+
+ private _autoActivatePromise: Promise<void> | null = null;
+
+ /**
+ * Discover and activate all builtin extensions. Idempotent — only runs
+ * the discovery/activation sequence once no matter how many callers invoke it.
+ */
+ autoActivateBuiltins(): Promise<void> {
+ if (this._autoActivatePromise) return this._autoActivatePromise;
+
+ this._autoActivatePromise = (async () => {
+ // Use the real (unproxied) reference — this is app code, not extension code
+ const api = _realElectronAPI ?? window.electronAPI;
+ if (!api?.extensionsDiscover) return;
+ try {
+ const discovered: ExtensionInfo[] = await api.extensionsDiscover();
+ await this.syncConfiguredExtensions(discovered);
+ } catch (err) {
+ console.error("[extensions] Failed to discover extensions:", err);
+ }
+ })();
+
+ return this._autoActivatePromise;
+ }
+}
+
+/**
+ * Singleton extension host instance for the renderer process.
+ */
+export const extensionHost = new ExtensionHost();
diff --git a/src/lib/extensions/fileUrls.ts b/src/lib/extensions/fileUrls.ts
new file mode 100644
index 00000000..0314a290
--- /dev/null
+++ b/src/lib/extensions/fileUrls.ts
@@ -0,0 +1,47 @@
+const WINDOWS_ABSOLUTE_PATH = /^[a-zA-Z]:[\\/]/;
+
+function ensureTrailingSlash(value: string): string {
+ return value.endsWith("/") ? value : `${value}/`;
+}
+
+function trimTrailingSlash(value: string): string {
+ return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+
+function toDirectoryFileUrl(directoryPath: string): URL {
+ const normalized = directoryPath.replace(/\\/g, "/");
+
+ if (normalized.startsWith("file://")) {
+ return new URL(ensureTrailingSlash(normalized));
+ }
+
+ if (normalized.startsWith("/")) {
+ return new URL(`file://${ensureTrailingSlash(normalized)}`);
+ }
+
+ if (WINDOWS_ABSOLUTE_PATH.test(normalized)) {
+ return new URL(`file:///${ensureTrailingSlash(normalized)}`);
+ }
+
+ return new URL(`file://${ensureTrailingSlash(normalized)}`);
+}
+
+export function resolveExtensionRelativeFileUrl(
+ extensionPath: string,
+ relativePath: string,
+): string {
+ const baseUrl = toDirectoryFileUrl(extensionPath);
+ const basePath = trimTrailingSlash(baseUrl.pathname);
+ const resolvedUrl = new URL(relativePath, baseUrl);
+ const resolvedPath = trimTrailingSlash(resolvedUrl.pathname);
+
+ if (resolvedPath !== basePath && !resolvedPath.startsWith(`${basePath}/`)) {
+ throw new Error(`Invalid extension path: ${relativePath}`);
+ }
+
+ return resolvedUrl.toString();
+}
+
+export function createExtensionModuleUrl(extensionPath: string, entryPoint: string): string {
+ return resolveExtensionRelativeFileUrl(extensionPath, entryPoint);
+}
\ No newline at end of file
diff --git a/src/lib/extensions/index.ts b/src/lib/extensions/index.ts
new file mode 100644
index 00000000..f8af0538
--- /dev/null
+++ b/src/lib/extensions/index.ts
@@ -0,0 +1,29 @@
+export { extensionHost, ExtensionHost } from './extensionHost';
+export type {
+ ExtensionManifest,
+ ExtensionInfo,
+ ExtensionPermission,
+ ExtensionStatus,
+ RecordlyExtensionAPI,
+ RecordlyExtensionModule,
+ RenderHookPhase,
+ RenderHookFn,
+ RenderHookContext,
+ CursorEffectFn,
+ CursorEffectContext,
+ ExtensionEventType,
+ ExtensionEvent,
+ ExtensionSettingsPanel,
+ ExtensionSettingField,
+ ExtensionContributions,
+ ContributedCursorStyle,
+ ContributedSound,
+ ContributedWallpaper,
+ ContributedWebcamFrame,
+ ContributedFrame,
+ FrameInstance,
+ MarketplaceExtension,
+ MarketplaceSearchResult,
+ MarketplaceReviewStatus,
+ ExtensionReview,
+} from './types';
diff --git a/src/lib/extensions/renderHooks.ts b/src/lib/extensions/renderHooks.ts
new file mode 100644
index 00000000..8de9d374
--- /dev/null
+++ b/src/lib/extensions/renderHooks.ts
@@ -0,0 +1,266 @@
+/**
+ * Extension Render Hooks — Integration Layer
+ *
+ * Provides utility functions to call extension render hooks from
+ * preview and export canvas pipelines. This is the bridge between
+ * app renderers and extension-registered hooks.
+ */
+
+import { extensionHost } from '@/lib/extensions';
+import type { RenderHookPhase, RenderHookContext, CursorEffectContext } from '@/lib/extensions';
+
+// ---------------------------------------------------------------------------
+// Scene pixel helpers — created per-context (capture ctx + videoLayout)
+// ---------------------------------------------------------------------------
+
+function makePixelHelpers(ctx: CanvasRenderingContext2D, videoLayout?: RenderHookContext['videoLayout']) {
+ const getPixelColor = (x: number, y: number) => {
+ const px = Math.round(x);
+ const py = Math.round(y);
+ const d = ctx.getImageData(px, py, 1, 1).data;
+ return { r: d[0], g: d[1], b: d[2], a: d[3] };
+ };
+
+ const sampleGrid = (
+ sx: number, sy: number, sw: number, sh: number, step: number,
+ ) => {
+ let rSum = 0, gSum = 0, bSum = 0, aSum = 0, count = 0;
+ const clampedW = Math.max(1, Math.round(sw));
+ const clampedH = Math.max(1, Math.round(sh));
+ const data = ctx.getImageData(Math.round(sx), Math.round(sy), clampedW, clampedH).data;
+ for (let y = 0; y < clampedH; y += step) {
+ for (let x = 0; x < clampedW; x += step) {
+ const i = (y * clampedW + x) * 4;
+ rSum += data[i]; gSum += data[i + 1]; bSum += data[i + 2]; aSum += data[i + 3];
+ count++;
+ }
+ }
+ if (count === 0) return { r: 0, g: 0, b: 0, a: 0 };
+ return {
+ r: Math.round(rSum / count),
+ g: Math.round(gSum / count),
+ b: Math.round(bSum / count),
+ a: Math.round(aSum / count),
+ };
+ };
+
+ const getMaskRect = () => {
+ if (videoLayout) return videoLayout.maskRect;
+ return { x: 0, y: 0, width: ctx.canvas.width, height: ctx.canvas.height };
+ };
+
+ const getAverageSceneColor = () => {
+ const m = getMaskRect();
+ const step = Math.max(1, Math.round(Math.min(m.width, m.height) / 32));
+ return sampleGrid(m.x, m.y, m.width, m.height, step);
+ };
+
+ const getEdgeAverageColor = (edgeWidth = 4) => {
+ const m = getMaskRect();
+ const ew = Math.max(1, edgeWidth);
+ let rSum = 0, gSum = 0, bSum = 0, aSum = 0, count = 0;
+
+ const bands = [
+ { x: m.x, y: m.y, w: m.width, h: ew }, // top
+ { x: m.x, y: m.y + m.height - ew, w: m.width, h: ew }, // bottom
+ { x: m.x, y: m.y + ew, w: ew, h: m.height - ew * 2 }, // left
+ { x: m.x + m.width - ew, y: m.y + ew, w: ew, h: m.height - ew * 2 }, // right
+ ];
+ const step = Math.max(1, Math.round(Math.min(m.width, m.height) / 64));
+ for (const b of bands) {
+ if (b.w <= 0 || b.h <= 0) continue;
+ const avg = sampleGrid(b.x, b.y, b.w, b.h, step);
+ const bandSamples = Math.ceil(b.w / step) * Math.ceil(b.h / step);
+ rSum += avg.r * bandSamples;
+ gSum += avg.g * bandSamples;
+ bSum += avg.b * bandSamples;
+ aSum += avg.a * bandSamples;
+ count += bandSamples;
+ }
+ if (count === 0) return { r: 0, g: 0, b: 0, a: 0 };
+ return {
+ r: Math.round(rSum / count),
+ g: Math.round(gSum / count),
+ b: Math.round(bSum / count),
+ a: Math.round(aSum / count),
+ };
+ };
+
+ const getDominantColors = (maxColors = 5) => {
+ const m = getMaskRect();
+ const step = Math.max(1, Math.round(Math.min(m.width, m.height) / 24));
+ const clampedW = Math.max(1, Math.round(m.width));
+ const clampedH = Math.max(1, Math.round(m.height));
+ const data = ctx.getImageData(Math.round(m.x), Math.round(m.y), clampedW, clampedH).data;
+ // Quantize to 5-bit per channel
+ const buckets = new Map<number, { r: number; g: number; b: number; count: number }>();
+ for (let y = 0; y < clampedH; y += step) {
+ for (let x = 0; x < clampedW; x += step) {
+ const i = (y * clampedW + x) * 4;
+ const qr = data[i] >> 3;
+ const qg = data[i + 1] >> 3;
+ const qb = data[i + 2] >> 3;
+ const key = (qr << 10) | (qg << 5) | qb;
+ const existing = buckets.get(key);
+ if (existing) {
+ existing.r += data[i];
+ existing.g += data[i + 1];
+ existing.b += data[i + 2];
+ existing.count++;
+ } else {
+ buckets.set(key, { r: data[i], g: data[i + 1], b: data[i + 2], count: 1 });
+ }
+ }
+ }
+ const totalSamples = Array.from(buckets.values()).reduce((s, b) => s + b.count, 0) || 1;
+ return Array.from(buckets.values())
+ .sort((a, b) => b.count - a.count)
+ .slice(0, maxColors)
+ .map(b => ({
+ r: Math.round(b.r / b.count),
+ g: Math.round(b.g / b.count),
+ b: Math.round(b.b / b.count),
+ frequency: b.count / totalSamples,
+ }));
+ };
+
+ return { getPixelColor, getAverageSceneColor, getEdgeAverageColor, getDominantColors };
+}
+
+/**
+ * Execute all extension render hooks for a phase against a canvas context.
+ *
+ * Call this from FrameRenderer at the appropriate point in the pipeline.
+ * The context is saved/restored around each hook call.
+ */
+export function executeExtensionRenderHooks(
+ phase: RenderHookPhase,
+ ctx: CanvasRenderingContext2D,
+ params: {
+ width: number;
+ height: number;
+ timeMs: number;
+ durationMs: number;
+ cursor?: { cx: number; cy: number; interactionType?: string } | null;
+ smoothedCursor?: RenderHookContext['smoothedCursor'];
+ videoLayout?: RenderHookContext['videoLayout'];
+ zoom?: RenderHookContext['zoom'];
+ shadow?: RenderHookContext['shadow'];
+ sceneTransform?: RenderHookContext['sceneTransform'];
+ },
+): void {
+ if (!extensionHost.hasRenderHooks(phase)) return;
+
+ const helpers = makePixelHelpers(ctx, params.videoLayout);
+
+ const context: RenderHookContext = {
+ width: params.width,
+ height: params.height,
+ timeMs: params.timeMs,
+ durationMs: params.durationMs,
+ cursor: params.cursor ?? null,
+ smoothedCursor: params.smoothedCursor ?? null,
+ ctx,
+ videoLayout: params.videoLayout,
+ zoom: params.zoom,
+ shadow: params.shadow,
+ sceneTransform: params.sceneTransform,
+ getPixelColor: helpers.getPixelColor,
+ getAverageSceneColor: helpers.getAverageSceneColor,
+ getEdgeAverageColor: helpers.getEdgeAverageColor,
+ getDominantColors: helpers.getDominantColors,
+ };
+
+ extensionHost.executeRenderHooks(phase, context);
+}
+
+/**
+ * Track active cursor effects (animations that persist across frames).
+ */
+interface ActiveCursorEffectInstance {
+ interactionTimeMs: number;
+ cx: number;
+ cy: number;
+ interactionType: 'click' | 'double-click' | 'right-click' | 'mouseup';
+}
+
+const activeCursorInteractions: ActiveCursorEffectInstance[] = [];
+const MAX_EFFECT_DURATION_MS = 2000;
+
+/**
+ * Notify that a cursor interaction occurred (call from cursor telemetry handler).
+ */
+export function notifyCursorInteraction(
+ timeMs: number,
+ cx: number,
+ cy: number,
+ interactionType: string,
+): void {
+ if (!extensionHost.hasCursorEffects()) return;
+
+ const validTypes = new Set(['click', 'double-click', 'right-click', 'mouseup']);
+ if (!validTypes.has(interactionType)) return;
+
+ activeCursorInteractions.push({
+ interactionTimeMs: timeMs,
+ cx,
+ cy,
+ interactionType: interactionType as ActiveCursorEffectInstance['interactionType'],
+ });
+}
+
+/**
+ * Execute cursor effects for the current frame.
+ * Called after the cursor is drawn in the render pipeline.
+ */
+export function executeExtensionCursorEffects(
+ ctx: CanvasRenderingContext2D,
+ timeMs: number,
+ width: number,
+ height: number,
+ extra?: {
+ zoom?: CursorEffectContext['zoom'];
+ sceneTransform?: CursorEffectContext['sceneTransform'];
+ videoLayout?: CursorEffectContext['videoLayout'];
+ },
+): void {
+ if (!extensionHost.hasCursorEffects() || activeCursorInteractions.length === 0) return;
+
+ // Process all active interactions, removing expired ones
+ for (let i = activeCursorInteractions.length - 1; i >= 0; i--) {
+ const interaction = activeCursorInteractions[i];
+ const elapsedMs = timeMs - interaction.interactionTimeMs;
+
+ // Remove if too old
+ if (elapsedMs > MAX_EFFECT_DURATION_MS || elapsedMs < 0) {
+ activeCursorInteractions.splice(i, 1);
+ continue;
+ }
+
+ const effectCtx: CursorEffectContext = {
+ timeMs,
+ cx: interaction.cx,
+ cy: interaction.cy,
+ interactionType: interaction.interactionType,
+ width,
+ height,
+ ctx,
+ elapsedMs,
+ zoom: extra?.zoom,
+ sceneTransform: extra?.sceneTransform,
+ videoLayout: extra?.videoLayout,
+ };
+
+ const stillActive = extensionHost.executeCursorEffects(effectCtx);
+ if (!stillActive) {
+ activeCursorInteractions.splice(i, 1);
+ }
+ }
+}
+
+/**
+ * Clear all active cursor effect animations (e.g., on seek).
+ */
+export function clearCursorEffects(): void {
+ activeCursorInteractions.length = 0;
+}
diff --git a/src/lib/extensions/sceneTransform.ts b/src/lib/extensions/sceneTransform.ts
new file mode 100644
index 00000000..1f3edbe1
--- /dev/null
+++ b/src/lib/extensions/sceneTransform.ts
@@ -0,0 +1,17 @@
+export interface SceneTransform {
+ scale: number;
+ x: number;
+ y: number;
+}
+
+export function applyCanvasSceneTransform(
+ ctx: CanvasRenderingContext2D,
+ transform: SceneTransform | null | undefined,
+): void {
+ if (!transform) {
+ return;
+ }
+
+ ctx.translate(transform.x, transform.y);
+ ctx.scale(transform.scale, transform.scale);
+}
diff --git a/src/lib/extensions/types.ts b/src/lib/extensions/types.ts
new file mode 100644
index 00000000..0836e1ea
--- /dev/null
+++ b/src/lib/extensions/types.ts
@@ -0,0 +1,593 @@
+/**
+ * Recordly Extension System — Core Types
+ *
+ * Extensions are renderer-loaded modules that can hook into the render pipeline,
+ * bundle assets, register UI panels, and respond to playback/timeline events.
+ */
+
+// ---------------------------------------------------------------------------
+// Extension Manifest (recordly-extension.json)
+// ---------------------------------------------------------------------------
+
+export interface ExtensionManifest {
+ /** Unique identifier, e.g. "com.example.click-sparkles" */
+ id: string;
+ /** Human-readable name */
+ name: string;
+ /** Semver version string */
+ version: string;
+ /** Short one-line description */
+ description: string;
+ /** Author name or organisation */
+ author?: string;
+ /** Homepage / repository URL */
+ homepage?: string;
+ /** License identifier (SPDX) */
+ license?: string;
+ /** Minimum Recordly version required */
+ engine?: string;
+ /** Icon path relative to extension root */
+ icon?: string;
+ /** Entry point file relative to extension root (JS module) */
+ main: string;
+ /** APIs this extension requires — used for permission gating */
+ permissions: ExtensionPermission[];
+ /** Asset categories this extension provides */
+ contributes?: ExtensionContributions;
+}
+
+export type ExtensionPermission =
+ | "render" // Hook into the frame render pipeline
+ | "cursor" // Access cursor telemetry & register cursor effects
+ | "audio" // Provide or manipulate audio
+ | "timeline" // Observe timeline lifecycle events
+ | "ui" // Register settings panels and frames
+ | "assets" // Resolve bundled asset paths
+ | "export"; // Hook into export lifecycle
+
+/**
+ * Optional manifest metadata for packaged assets.
+ *
+ * Recordly does not auto-register these entries at runtime today.
+ * Extensions still need to wire behavior from activate() via host APIs like
+ * registerFrame(), registerSettingsPanel(), resolveAsset(), and playSound().
+ */
+export interface ExtensionContributions {
+ /** Cursor style packs: array of cursor style definitions */
+ cursorStyles?: ContributedCursorStyle[];
+ /** Sound packs: click sounds, transition sounds, etc. */
+ sounds?: ContributedSound[];
+ /** Wallpaper/background images or videos */
+ wallpapers?: ContributedWallpaper[];
+ /** Webcam frames/overlays */
+ webcamFrames?: ContributedWebcamFrame[];
+ /** Device frames (browser chrome, laptop bezels, phone frames, etc.) */
+ frames?: ContributedFrame[];
+}
+
+export interface ContributedCursorStyle {
+ id: string;
+ label: string;
+ /** Path to cursor image relative to extension root */
+ defaultImage: string;
+ /** Optional click state image */
+ clickImage?: string;
+ /** Hotspot offset from top-left (normalized 0-1) */
+ hotspot?: { x: number; y: number };
+}
+
+export interface ContributedSound {
+ id: string;
+ label: string;
+ /** Sound category */
+ category: "click" | "transition" | "ambient" | "notification";
+ /** Path to audio file relative to extension root */
+ file: string;
+ /** Duration in ms (auto-detected if omitted) */
+ durationMs?: number;
+}
+
+export interface ContributedWallpaper {
+ id: string;
+ label: string;
+ /** Path to image/video file relative to extension root */
+ file: string;
+ /** Thumbnail for the picker */
+ thumbnail?: string;
+ /** Whether this is a video wallpaper */
+ isVideo?: boolean;
+}
+
+export interface ContributedWebcamFrame {
+ id: string;
+ label: string;
+ /** Path to frame overlay image (PNG with transparency) */
+ file: string;
+ thumbnail?: string;
+}
+
+export interface ContributedFrame {
+ id: string;
+ label: string;
+ /** Category for grouping in the picker */
+ category: "browser" | "laptop" | "phone" | "tablet" | "desktop" | "custom";
+ /** Path to frame overlay image (PNG or SVG with transparency) relative to extension root */
+ file?: string;
+ /** Alternative: a data URL (e.g. from Canvas.toDataURL) for runtime-generated frames */
+ dataUrl?: string;
+ /** Thumbnail for the picker */
+ thumbnail?: string;
+ /**
+ * Insets defining where the screen content sits inside the frame image,
+ * as fractions (0-1) of the frame image dimensions.
+ * { top, right, bottom, left }
+ */
+ screenInsets: { top: number; right: number; bottom: number; left: number };
+ /** Whether the frame has a dark or light appearance (for wallpaper matching) */
+ appearance?: "light" | "dark";
+ /**
+ * Resolution-independent draw function. Called at the target dimensions
+ * to draw the frame chrome, leaving the screen area transparent.
+ * Preferred over file/dataUrl — avoids bitmap scaling artifacts.
+ */
+ draw?: (ctx: CanvasRenderingContext2D, width: number, height: number) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Extension Runtime State
+// ---------------------------------------------------------------------------
+
+export type ExtensionStatus = "installed" | "active" | "disabled" | "error";
+
+export interface ExtensionInfo {
+ manifest: ExtensionManifest;
+ status: ExtensionStatus;
+ /** Absolute path to extension directory */
+ path: string;
+ /** Error message if status is 'error' */
+ error?: string;
+ /** Whether this is a built-in extension */
+ builtin?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Marketplace Types
+// ---------------------------------------------------------------------------
+
+export type MarketplaceReviewStatus = "pending" | "approved" | "rejected" | "flagged";
+
+export interface MarketplaceExtension {
+ /** Same as ExtensionManifest.id */
+ id: string;
+ name: string;
+ version: string;
+ description: string;
+ author: string;
+ /** Download URL for the extension archive (.zip) */
+ downloadUrl: string;
+ /** Icon URL */
+ iconUrl?: string;
+ /** Screenshots */
+ screenshots?: string[];
+ /** Number of downloads */
+ downloads: number;
+ /** Average rating (0-5) */
+ rating: number;
+ /** Number of ratings */
+ ratingCount: number;
+ /** Category tags */
+ tags: string[];
+ /** Permissions required */
+ permissions: ExtensionPermission[];
+ /** Whether this extension has been reviewed and approved */
+ reviewStatus: MarketplaceReviewStatus;
+ /** When the extension was published */
+ publishedAt: string;
+ /** When last updated */
+ updatedAt: string;
+ /** Author homepage URL */
+ homepage?: string;
+ /** Whether this version is already installed locally */
+ installed?: boolean;
+}
+
+export interface MarketplaceSearchResult {
+ extensions: MarketplaceExtension[];
+ total: number;
+ page: number;
+ pageSize: number;
+}
+
+export interface ExtensionReview {
+ id: string;
+ extensionId: string;
+ extensionName: string;
+ version: string;
+ author: string;
+ submittedAt: string;
+ status: MarketplaceReviewStatus;
+ reviewNotes?: string;
+ manifest: ExtensionManifest;
+ downloadUrl: string;
+}
+
+// ---------------------------------------------------------------------------
+// Extension API — Render Hooks
+// ---------------------------------------------------------------------------
+
+/** Context passed to render hooks each frame */
+export interface RenderHookContext {
+ /** Output canvas width */
+ width: number;
+ /** Output canvas height */
+ height: number;
+ /** Current playback time in ms */
+ timeMs: number;
+ /** Total video duration in ms */
+ durationMs: number;
+ /** Current cursor position (normalized 0-1, null if no cursor) */
+ cursor: { cx: number; cy: number; interactionType?: string } | null;
+ /** Current smoothed cursor state and trailing path (normalized 0-1) */
+ smoothedCursor?: {
+ cx: number;
+ cy: number;
+ trail: Array<{ cx: number; cy: number }>;
+ } | null;
+ /** The 2D rendering context to draw on */
+ ctx: CanvasRenderingContext2D;
+ /** Current video content layout (position & size inside the canvas) */
+ videoLayout?: {
+ /** Position & size of the masked video content area (in canvas pixels) */
+ maskRect: { x: number; y: number; width: number; height: number };
+ /** Border radius applied to the video (in canvas pixels) */
+ borderRadius: number;
+ /** Padding around the video (in canvas pixels) */
+ padding: number;
+ };
+ /** Current zoom state */
+ zoom?: {
+ /** 1 = no zoom, >1 = zoomed in */
+ scale: number;
+ /** Normalized focus point (0-1) */
+ focusX: number;
+ focusY: number;
+ /** 0 = idle, 1 = fully zoomed in */
+ progress: number;
+ };
+ /** Current scene transform (motion animation offset & scale).
+ * Hooks that run outside the built-in transform (post-webcam, post-annotations, final)
+ * can apply this manually to follow zoom/pan motion:
+ * ctx.save(); ctx.translate(t.x, t.y); ctx.scale(t.scale, t.scale); … ctx.restore();
+ */
+ sceneTransform?: {
+ scale: number;
+ x: number;
+ y: number;
+ };
+ /** Current shadow settings */
+ shadow?: {
+ enabled: boolean;
+ intensity: number;
+ };
+
+ // ------------------------------------------------------------------
+ // Scene pixel helpers (sample from the current canvas)
+ // ------------------------------------------------------------------
+
+ /**
+ * Get the RGBA color at a specific pixel (canvas coords).
+ * Returns { r, g, b, a } with values 0–255.
+ */
+ getPixelColor(x: number, y: number): { r: number; g: number; b: number; a: number };
+
+ /**
+ * Average RGBA color across the entire video content area (maskRect).
+ * Samples a grid for performance.
+ */
+ getAverageSceneColor(): { r: number; g: number; b: number; a: number };
+
+ /**
+ * Average RGBA color along the edges of the video content area.
+ * Useful for matching wallpapers/frames to scene content.
+ * @param edgeWidth — thickness of edge band in pixels (default 4)
+ */
+ getEdgeAverageColor(edgeWidth?: number): { r: number; g: number; b: number; a: number };
+
+ /**
+ * Get dominant colors in the video content area.
+ * Returns up to `count` colors sorted by frequency.
+ */
+ getDominantColors(count?: number): Array<{ r: number; g: number; b: number; frequency: number }>;
+}
+
+/** Render hook phases — extensions draw in the registered phase */
+export type RenderHookPhase =
+ | "background" // Before video frame (custom backgrounds)
+ | "post-video" // After video frame, before zoom transform
+ | "post-zoom" // After zoom transform
+ | "post-cursor" // After cursor is drawn (click effects, trails)
+ | "post-webcam" // After webcam overlay
+ | "post-annotations" // After annotations
+ | "final"; // Last pass (watermarks, HUD overlays)
+
+export type RenderHookFn = (ctx: RenderHookContext) => void;
+
+// ---------------------------------------------------------------------------
+// Extension API — Cursor Effect Hooks
+// ---------------------------------------------------------------------------
+
+export interface CursorEffectContext {
+ /** Current time in ms */
+ timeMs: number;
+ /** Cursor position (normalized 0-1) */
+ cx: number;
+ cy: number;
+ /** Interaction type that triggered this effect */
+ interactionType: "click" | "double-click" | "right-click" | "mouseup";
+ /** Canvas dimensions */
+ width: number;
+ height: number;
+ /** 2D context to draw the effect */
+ ctx: CanvasRenderingContext2D;
+ /** Milliseconds since the interaction occurred */
+ elapsedMs: number;
+ /** Current zoom state (same as RenderHookContext.zoom) */
+ zoom?: {
+ scale: number;
+ focusX: number;
+ focusY: number;
+ progress: number;
+ };
+ /** Current scene transform applied to the canvas */
+ sceneTransform?: {
+ scale: number;
+ x: number;
+ y: number;
+ };
+ /** Video content layout inside the canvas */
+ videoLayout?: {
+ maskRect: { x: number; y: number; width: number; height: number };
+ borderRadius: number;
+ padding: number;
+ };
+}
+
+export type CursorEffectFn = (ctx: CursorEffectContext) => boolean; // return false to stop animation
+
+// ---------------------------------------------------------------------------
+// Extension API — Event System
+// ---------------------------------------------------------------------------
+
+export type ExtensionEventType =
+ | "playback:timeupdate"
+ | "playback:play"
+ | "playback:pause"
+ | "cursor:click"
+ | "cursor:move"
+ | "timeline:region-added"
+ | "timeline:region-removed"
+ | "export:start"
+ | "export:frame"
+ | "export:complete";
+
+export interface ExtensionEvent {
+ type: ExtensionEventType;
+ timeMs?: number;
+ data?: unknown;
+}
+
+export type ExtensionEventHandler = (event: ExtensionEvent) => void;
+
+// ---------------------------------------------------------------------------
+// Extension API — Settings UI
+// ---------------------------------------------------------------------------
+
+export interface ExtensionSettingField {
+ id: string;
+ label: string;
+ type: "toggle" | "slider" | "select" | "color" | "text";
+ defaultValue: unknown;
+ /** For sliders */
+ min?: number;
+ max?: number;
+ step?: number;
+ /** For select */
+ options?: { label: string; value: string }[];
+}
+
+export interface ExtensionSettingsPanel {
+ /** Unique panel ID */
+ id: string;
+ /** Display label in settings */
+ label: string;
+ /** Icon name (lucide icon) */
+ icon?: string;
+ /** If set, renders inside this existing section (e.g. 'cursor', 'scene').
+ * Otherwise, creates a new standalone section. */
+ parentSection?: string;
+ /** Setting fields */
+ fields: ExtensionSettingField[];
+}
+
+// ---------------------------------------------------------------------------
+// Extension API — The API object passed to extension activate()
+// ---------------------------------------------------------------------------
+
+export interface RecordlyExtensionAPI {
+ /** Register a render hook at a specific pipeline phase */
+ registerRenderHook(phase: RenderHookPhase, hook: RenderHookFn): () => void;
+
+ /** Register a cursor click effect */
+ registerCursorEffect(effect: CursorEffectFn): () => void;
+
+ /** Register a device frame (browser chrome, laptop bezel, etc.) */
+ registerFrame(frame: ContributedFrame): () => void;
+
+ /** Listen to extension events */
+ on(event: ExtensionEventType, handler: ExtensionEventHandler): () => void;
+
+ /** Register a settings panel for this extension */
+ registerSettingsPanel(panel: ExtensionSettingsPanel): () => void;
+
+ /** Get the current value of an extension setting */
+ getSetting(settingId: string): unknown;
+
+ /** Set an extension setting value */
+ setSetting(settingId: string, value: unknown): void;
+
+ /** Resolve an asset path relative to the extension root */
+ resolveAsset(relativePath: string): string;
+
+ /**
+ * Play a sound from a bundled audio file (relative to extension root).
+ * Returns a stop function to cancel playback early.
+ * Optional volume (0-1, default 1).
+ */
+ playSound(relativePath: string, options?: { volume?: number }): () => void;
+
+ /** Log a message (visible in dev tools, prefixed with extension ID) */
+ log(message: string, ...args: unknown[]): void;
+
+ // ------------------------------------------------------------------
+ // Query APIs — read-only access to project / playback state
+ // ------------------------------------------------------------------
+
+ /** Get video info (resolution, duration, fps) */
+ getVideoInfo(): {
+ width: number;
+ height: number;
+ durationMs: number;
+ fps: number;
+ } | null;
+
+ /** Get the current video content layout (mask rect, padding, etc.) */
+ getVideoLayout(): {
+ maskRect: { x: number; y: number; width: number; height: number };
+ canvasWidth: number;
+ canvasHeight: number;
+ borderRadius: number;
+ padding: number;
+ } | null;
+
+ /**
+ * Query cursor telemetry at a given time (nearest point).
+ * Returns null if no telemetry is available.
+ */
+ getCursorAt(timeMs: number): {
+ cx: number;
+ cy: number;
+ timeMs: number;
+ interactionType?: string;
+ pressure?: number;
+ } | null;
+
+ /** Get the latest smoothed cursor position and trail for the active renderer. */
+ getSmoothedCursor(): {
+ cx: number;
+ cy: number;
+ timeMs: number;
+ trail: Array<{ cx: number; cy: number }>;
+ } | null;
+
+ /** Get the current zoom state */
+ getZoomState(): {
+ scale: number;
+ focusX: number;
+ focusY: number;
+ progress: number;
+ } | null;
+
+ /** Get the current shadow configuration */
+ getShadowConfig(): {
+ enabled: boolean;
+ intensity: number;
+ };
+
+ /**
+ * Get keystroke events in a time range.
+ * Returns an array of keystroke events within [startMs, endMs].
+ */
+ getKeystrokesInRange(
+ startMs: number,
+ endMs: number,
+ ): Array<{
+ timeMs: number;
+ key: string;
+ modifiers: string[];
+ }>;
+
+ /**
+ * Get the current aspect ratio of the output canvas (width / height).
+ */
+ getAspectRatio(): number | null;
+
+ /**
+ * Get the active device frame ID, or null if none is selected.
+ */
+ getActiveFrame(): string | null;
+
+ /**
+ * Check whether a specific extension is currently active.
+ */
+ isExtensionActive(extensionId: string): boolean;
+
+ /**
+ * Get the current playback state (time, duration, playing status).
+ */
+ getPlaybackState(): {
+ currentTimeMs: number;
+ durationMs: number;
+ isPlaying: boolean;
+ } | null;
+
+ /**
+ * Get the output canvas dimensions in pixels.
+ */
+ getCanvasDimensions(): { width: number; height: number } | null;
+
+ /**
+ * Subscribe to changes in this extension's settings.
+ * The callback receives the setting ID that changed and its new value.
+ * Returns a dispose function.
+ */
+ onSettingChange(callback: (settingId: string, value: unknown) => void): () => void;
+
+ /**
+ * Get ALL settings for this extension as a key-value map.
+ * Useful for bulk-reading initial state on activation.
+ */
+ getAllSettings(): Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Extension Module — what the extension's main JS file must export
+// ---------------------------------------------------------------------------
+
+export interface RecordlyExtensionModule {
+ /** Called when the extension is activated */
+ activate(api: RecordlyExtensionAPI): void | Promise<void>;
+ /** Called when the extension is deactivated */
+ deactivate?(): void | Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Device Frame — Runtime Instance (resolved paths)
+// ---------------------------------------------------------------------------
+
+export interface FrameInstance {
+ /** Unique id: extensionId + '/' + frame.id */
+ id: string;
+ /** Extension that contributed this frame */
+ extensionId: string;
+ label: string;
+ category: ContributedFrame["category"];
+ /** Resolved absolute file:// URL to the frame overlay (PNG, SVG, or data URL) */
+ filePath: string;
+ /** Resolved absolute file:// URL to the thumbnail (or filePath if absent) */
+ thumbnailPath: string;
+ /** Screen insets (fraction 0-1 of frame image) */
+ screenInsets: { top: number; right: number; bottom: number; left: number };
+ appearance?: "light" | "dark";
+ /** Resolution-independent draw function (if provided by the extension) */
+ draw?: (ctx: CanvasRenderingContext2D, width: number, height: number) => void;
+}