@codefilm/recorder 3.0.0

package/README.md

@@ -0,0 +1,1553 @@
+# code-film 🎬
+
+Cinematic screen region recorder for React and vanilla JavaScript applications. Capture perfect crop areas, dynamic focal zoom boundaries, custom aspect ratios, and export high-quality WebM/MP4 recordings seamlessly.
+
+---
+
+## Features
+
+- 🎯 **Cinematic Cropping**: Draw or snap a recording frame to strict aspect ratios (e.g., 16:9, 9:16, 4:5) without video stretching.
+- 🔍 **Automatic Focal Zoom**: Smooth, animated focal zooming (`requestAnimationFrame` LERP easing) centered on mouse hold.
+- ⚛️ **Zero-Dependency React Bindings**: Drop-in `<RegionRecorder>` component and headless `useFilmRecorder` hook.
+- 🎨 **Fully Customizable & Scoped CSS**: Clean modern glassmorphism styled with theme-friendly CSS custom properties (prefixed with `cfr-`).
+- 🛡️ **Iframe Friendly**: Fully supports tab capture and canvas cropping across cross-origin iframe boundaries.
+
+---
+
+## Installation
+
+Install the package via npm, yarn, or bun:
+
+```bash
+npm install @codefilm/recorder
+# or
+yarn add @codefilm/recorder
+# or
+bun add @codefilm/recorder
+```
+
+---
+
+## React Integration
+
+### 1. Quick Start (Drop-in UI Component)
+
+Import the recorder component and load the companion stylesheet. This mounts the full cinematic settings bar, coordinate grid, and crop outline.
+
+```tsx
+import React from "react";
+import { RegionRecorder } from "@codefilm/recorder";
+import "@codefilm/recorder/style.css";
+
+export default function App() {
+  return (
+    <div className="app-container">
+      {/* Cinematic Screen Recorder Component */}
+      <RegionRecorder
+        options={{
+          fps: 60,
+          autoZoom: true,
+          showOutline: false, // Hidden by default so it doesn't appear in the output video
+          showGrid: true,
+        }}
+      />
+
+      <main>
+        <h1>My Premium Application</h1>
+        <p>Record your screen dynamically using focal zoom transitions.</p>
+      </main>
+    </div>
+  );
+}
+```
+
+### 2. Headless Integration (Hook API)
+
+If you want to build a completely custom UI (e.g. customized control buttons, side panels, or branding) while leveraging the underlying capture logic:
+
+```tsx
+import React from "react";
+import { useFilmRecorder } from "@codefilm/recorder";
+import "@codefilm/recorder/style.css"; // Optional, or write your own styles
+
+export default function CustomRecorder() {
+  const { recorder, state } = useFilmRecorder({
+    fps: 60,
+    autoZoom: true,
+  });
+
+  if (!state || !recorder) return null;
+
+  return (
+    <div className="custom-dashboard">
+      <div className="status">Status: {state.recording ? "🔴 Recording" : "⚪ Idle"}</div>
+
+      <div className="buttons">
+        <button
+          onClick={() => (state.recording ? recorder.stopRecording() : recorder.startRecording())}
+        >
+          {state.recording ? "Stop Capture" : "Start Capture"}
+        </button>
+
+        <button onClick={() => recorder.resetFullScreen()}>Zoom Full Screen</button>
+
+        <button onClick={() => recorder.zoomTop()}>Zoom Top</button>
+
+        <button onClick={() => recorder.zoomBottom()}>Zoom Bottom</button>
+
+        <button onClick={() => recorder.zoomToMouse()}>Zoom Focal Mouse</button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Recording Artifacts
+
+By default, recordings still auto-download when stopped. For custom integrations, disable the download and receive the artifact directly:
+
+```ts
+const recorder = new FilmRecorder({
+  autoDownload: false,
+  includeTimelineMetadata: true,
+  onRecordingStop: (artifact) => {
+    console.log(artifact.blob, artifact.url, artifact.mimeType, artifact.filename);
+    console.log(artifact.timeline);
+    console.log(artifact.webm);
+  },
+});
+
+const latest = recorder.getLastRecording();
+
+// Revoke the object URL when your app no longer needs it.
+recorder.clearLastRecording();
+```
+
+`includeTimelineMetadata` returns container-agnostic timing data on the artifact. It is not muxed into the WebM container by the browser SDK, but it gives audio generators and renderer pipelines scene, action, marker, and timing data for synchronization:
+
+```ts
+artifact.timeline?.markers.forEach((marker) => {
+  console.log(marker.timeMs, marker.name, marker.data);
+});
+```
+
+### Ignoring DOM Elements During Recording
+
+Use `ignoreSelector` to hide matching page elements while recording is active. This is useful for controls, badges, or helper UI that should stay out of the captured video.
+
+```ts
+const recorder = new FilmRecorder({
+  ignoreSelector: "[data-code-film-ignore]",
+});
+
+recorder.setIgnoreSelector(".recording-toolbar");
+```
+
+### Recording Errors and Prepared Capture
+
+`startRecording()` returns `true` after MediaRecorder starts, returns `false` if recording is already active, and re-throws browser capture errors such as denied screen-share permission or missing user activation.
+
+```ts
+const recorder = new FilmRecorder({
+  onRecordingError: (err) => {
+    console.error("Recording failed", err);
+  },
+});
+
+try {
+  await recorder.startRecording();
+} catch (err) {
+  console.error(recorder.getLastRecordingError());
+}
+```
+
+For AI or agent flows, call `prepareCapture()` directly from a user click to satisfy browser activation, then start the actual MediaRecorder later so the LLM/script-generation wait is not recorded:
+
+```ts
+async function handleGenerateDemo() {
+  await recorder.prepareCapture(); // prompts immediately from the user gesture
+
+  const script = await generateFilmScript();
+
+  await recorder.startRecording(); // uses the prepared stream
+  await recorder.runFilmScript(script);
+  recorder.stopRecording();
+}
+```
+
+---
+
+## Element Selector Recording 🎯
+
+The SDK allows you to track and record specific DOM elements by their CSS selector (e.g., `#editor`, `.card-active`). The capture box automatically wraps around the target element, keeping its center as the center of the recording viewport while maintaining your chosen aspect ratio.
+
+The camera will dynamically pan and zoom in real-time to keep the element perfectly framed if it moves, resizes, or if the page scrolls.
+
+### Programmatic Usage
+
+You can set, change, or clear target elements dynamically:
+
+```typescript
+// Focus on a specific div with custom element padding
+recorder.setElementSelector("#my-element");
+recorder.setElementPadding(1.2); // 20% margin around the element
+
+// Stop tracking and zoom back to full screen
+recorder.setElementSelector(null);
+```
+
+To keep the recording box at a fixed size while it moves between targets, opt into the
+smallest 16:9 region:
+
+```typescript
+const recorder = new FilmRecorder({
+  fixedRecordingRegion: "smallest-16:9",
+});
+
+recorder.setElementSelector(".thread-thinking-status");
+```
+
+With `fixedRecordingRegion`, the SDK centers the fixed 16:9 capture box on the target
+instead of expanding the box to fit the full element.
+
+### Iframe Recording Bridge
+
+When the recorder lives in a parent page but the app being controlled is inside an iframe,
+install the SDK bridge on both sides. The host owns the `FilmRecorder`; the child forwards
+shortcuts and optional explicit commands with `postMessage`.
+
+Parent page:
+
+```typescript
+import { FilmRecorder, createRecorderIframeHost } from "@codefilm/recorder";
+
+const recorder = new FilmRecorder({
+  elementSelector: "#recording-region",
+  autoDownload: true,
+});
+
+const bridge = createRecorderIframeHost(recorder, {
+  allowedOrigins: ["http://127.0.0.1:5173"],
+});
+
+bridge.start();
+```
+
+Iframe child:
+
+```typescript
+import { createRecorderIframeClient } from "@codefilm/recorder";
+
+const bridge = createRecorderIframeClient({
+  targetOrigin: "http://127.0.0.1:10000",
+  shortcuts: true,
+});
+
+bridge.start();
+
+bridge.sendCommand("focus-mouse");
+```
+
+Supported commands are `toggle-recording`, `start-recording`, `stop-recording`,
+`focus-mouse`, `reset-full`, and `toggle-mouse-pause`. If `allowedOrigins` is set on
+the host, messages from any other iframe origin are ignored.
+
+### Recording Overlays
+
+Use SDK overlays for recording-only UI such as a presenter camera, captions, labels, or
+watermarks. Built-in camera overlays are composited into the final recorder canvas, so they
+remain visible even when recording an element selector or a fixed recording region.
+
+```typescript
+import { FilmRecorder, cameraOverlay } from "@codefilm/recorder";
+
+const recorder = new FilmRecorder({
+  elementSelector: ".app-shell",
+  includeTimelineMetadata: true,
+  overlays: [
+    cameraOverlay({
+      id: "presenter-camera",
+      enabled: true,
+      position: { x: 24, y: 24 },
+      size: 168,
+      shape: "circle",
+      draggable: true,
+      resizable: true,
+      mirror: true,
+    }),
+  ],
+});
+```
+
+You can also create and control an overlay imperatively:
+
+```typescript
+const camera = recorder.createCameraOverlay({
+  id: "presenter-camera",
+  size: 180,
+  position: "top-left",
+});
+
+await camera.requestPermission();
+await camera.show();
+camera.setSize(220);
+camera.moveTo({ x: 32, y: 32 });
+```
+
+If camera permission is denied, the SDK draws a visible fallback tile instead of leaving a
+blank overlay. Camera tracks stop when the overlay is hidden, destroyed, or when the recorder
+is disposed.
+
+Register custom DOM overlays when the host app owns the element:
+
+```typescript
+const caption = recorder.registerOverlay({
+  id: "caption",
+  element: document.querySelector("#recording-caption") as HTMLElement,
+  includeInCapture: true,
+  trackTimeline: true,
+});
+
+caption.show();
+caption.moveTo("bottom-left");
+```
+
+When `includeTimelineMetadata` is enabled, overlay changes add timeline markers named
+`overlay:shown`, `overlay:hidden`, `overlay:moved`, `overlay:resized`, and `overlay:error`.
+
+### Initialization Options
+
+You can also specify the target element selector directly when initializing:
+
+```typescript
+const recorder = new FilmRecorder({
+  elementSelector: "#main-content",
+  elementPadding: 1.15, // 15% margin around the element
+});
+```
+
+### React Integration
+
+When using the React `<RegionRecorder>` component or `useFilmRecorder` hook, pass the selector and padding via the options prop. It will automatically update in response to state changes:
+
+```tsx
+import React, { useState } from "react";
+import { RegionRecorder } from "@codefilm/recorder";
+
+export default function MyRecorder() {
+  const [selector, setSelector] = useState<string | null>("#element-1");
+
+  return (
+    <div>
+      <RegionRecorder
+        options={{
+          elementSelector: selector,
+          elementPadding: 1.2,
+        }}
+      />
+      <button onClick={() => setSelector("#element-1")}>Track Element 1</button>
+      <button onClick={() => setSelector("#element-2")}>Track Element 2</button>
+      <button onClick={() => setSelector(null)}>Full Screen</button>
+    </div>
+  );
+}
+```
+
+## Simulated Mouse Tours 🖱️
+
+You can programmatically trigger a simulated mouse movement and zoom tour to target elements. This creates a virtual cursor overlay on the page, slides it smoothly to the destination, performs a visual ripple click-hold, triggers the zoom-in, pauses, and then zooms back out.
+
+### Programmatic Usage
+
+Call the `playPointerTour` method at any time during a recording:
+
+```typescript
+// Move pointer to #my-element, perform click-hold to zoom in, hold for 2.5s, and zoom out
+await recorder.playPointerTour("#my-element", {
+  moveDuration: 1200, // Duration of pointer movement in ms
+  holdDuration: 2500, // Zoom hold duration in ms
+});
+```
+
+### Automatic Recording Tours
+
+You can configure the tour to play automatically when recording starts by passing the `movePointerToSelector` option:
+
+```typescript
+const recorder = new FilmRecorder({
+  movePointerToSelector: "#my-element",
+});
+```
+
+When recording begins, the virtual mouse cursor will automatically move to `#my-element`, zoom in, hold, and zoom out.
+
+---
+
+## AI Agent Prompt Automation & Script Runner 🤖
+
+You can automate complete cinematic recording tours directly from text prompts or structured film scripts using the **OpenAI Agents SDK** integration or the offline **Deterministic Script Runner**.
+
+---
+
+### 1. Proxy-First Runner Pattern (Recommended for Browser Apps)
+
+To avoid exposing your OpenAI API keys on the client-side, the SDK provides a helper `createRecorderAgentRunner` configured for server-side proxies.
+
+#### Installation
+```bash
+npm install @openai/agents openai zod
+```
+
+> [!IMPORTANT]
+> **Zod Version Resolution**:
+> The `code-film` SDK defines its built-in tool schemas using static, raw JSON Schema objects to be completely resilient against Zod runtime versions. If you are defining custom tools or using Zod, avoid aliasing or forcing deduplication of `zod` in your bundler configuration (e.g. Vite or Webpack) unless the versions are known to be compatible.
+
+#### React Implementation
+```tsx
+import React, { useState } from "react";
+import { useFilmRecorder, createRecorderAgentRunner } from "@codefilm/recorder";
+
+export default function AgentAutomationDemo() {
+  const { recorder, state, tourState, currentScene, stopTour } = useFilmRecorder({
+    fps: 30,
+    onTourStart: () => console.log("Tour started!"),
+    onReadyToEnd: () => setStatus("Finishing closing shot..."),
+    onTourStop: () => console.log("Tour finished!"),
+  });
+  const [status, setStatus] = useState("Idle");
+
+  const handleRunTour = async () => {
+    if (!recorder) return;
+
+    try {
+      // 1. Start recording stream (will prompt screen selection share dialog)
+      setStatus("Starting recording...");
+      await recorder.startRecording();
+      await new Promise((r) => setTimeout(r, 1000)); // wait for video stream to stabilize
+
+      // 2. Initialize the runner via your backend proxy with custom few-shot instructions/examples
+      const { runner, agent } = createRecorderAgentRunner(recorder, {
+        baseURL: `${window.location.origin}/api/openai/v1`,
+        apiKey: "proxied-by-server", // Server overrides this with the real key
+        maxTurns: 20, // Prevents infinite LLM turn loops
+        instructions: "Your custom agent instructions and few-shot examples here...",
+      });
+
+      setStatus("Agent executing film prompt...");
+
+      const prompt = "make a 10 second demo that types a product search, submits it, and focuses the result panel";
+      const result = await runner.run(agent, prompt);
+      setStatus(`Completed: ${result.finalOutput}`);
+    } catch (err: any) {
+      setStatus(`Error: ${err.message}`);
+    }
+  };
+
+  return (
+    <div className="agent-tour-card">
+      <h3>AI Automated Screen Tour</h3>
+      <div className="status">Status: {tourState} {currentScene && `(Scene: ${currentScene})`}</div>
+      <button onClick={handleRunTour} disabled={state?.recording}>
+        Start Recording Tour
+      </button>
+      <button onClick={stopTour} disabled={tourState !== "running"}>
+        Stop Tour
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+### 2. App-Aware Script Generation
+
+Use `generateAppFilmScript()` when an app wants one shared natural-language-to-code.film generator across multiple pages. The SDK owns the generic prompt structure, intent resolution, setup parsing, and setup-aware validation, while your app owns the profile and OpenAI transport.
+
+```typescript
+import {
+  generateAppFilmScript,
+  stripAppFilmSetup,
+  type AppFilmComplete,
+  type AppFilmProfile,
+} from "@codefilm/recorder/app-script";
+
+const app: AppFilmProfile = {
+  id: "demo-app",
+  name: "Demo App",
+  selectors: {
+    promptBox: {
+      selector: ".demo-input-card",
+      description: "Prompt composer card",
+      role: "input",
+    },
+    resultPanel: {
+      selector: ".demo-output-panel",
+      description: "Generated result panel",
+      role: "panel",
+      requiresSetup: ["result"],
+    },
+  },
+  pages: {
+    home: {
+      id: "home",
+      description: "Main demo page",
+      containerSelector: ".demo-app-shell",
+    },
+  },
+  setupCapabilities: ["result", "text"],
+  intents: [
+    {
+      id: "focus-result",
+      description: "Show an existing generated result panel.",
+      examples: ["result panel", "show generated result"],
+      negativeExamples: ["ask the app to generate a new result"],
+      page: "home",
+      defaultScopeSelector: ".demo-output-panel",
+      submitPrompt: false,
+      requiredSetup: ["result"],
+    },
+    {
+      id: "submit-prompt",
+      description: "Type a task into the prompt and submit it.",
+      examples: ["make an apple pie website", "use Browser to inspect localhost"],
+      page: "home",
+      defaultScopeSelector: ".demo-input-card",
+      submitPrompt: true,
+    },
+  ],
+  promptTools: [
+    {
+      id: "browser",
+      name: "Browser",
+      mention: "@Browser",
+      description: "Control the in-app browser.",
+      aliases: ["browser", "localhost", "web page"],
+      installed: true,
+    },
+  ],
+  attachmentTypes: [
+    {
+      id: "file",
+      label: "File",
+      aliases: ["file", "attachment"],
+    },
+  ],
+  defaults: {
+    minimalPromptMode: true,
+    defaultScope: "smallest-meaningful",
+  },
+};
+
+const complete: AppFilmComplete = async (request) => {
+  const response = await openai.responses.create({
+    model: "gpt-5.5",
+    instructions: request.instructions,
+    input: request.input,
+    tools: request.tools,
+    tool_choice: request.toolChoice,
+  });
+
+  return extractSingleFunctionToolCall(response);
+};
+
+const result = await generateAppFilmScript({
+  app,
+  input: "focus the generated result panel",
+  complete,
+  intentMode: "auto",
+  repair: true,
+});
+
+console.log(result.intent?.id); // "focus-result"
+hydrateAppFromFilmSetup(result.setup);
+await recorder.runFilmScript(stripAppFilmSetup(result.script));
+```
+
+With profile `intents`, the completion adapter receives a required `resolve_film_intent` tool call followed by `create_film_script`. The resolved intent is passed into script generation and returned as `result.intent`. Set `intentMode: "off"` to skip intent resolution and call `create_film_script` directly.
+
+`promptTools` and `attachmentTypes` keep app-native prompt chips structured. For example, a resolved `@Browser` tool or attached `package.json` file appears in `result.intent` and is also serialized as generic setup:
+
+```film
+# setup promptTool: {"id":"browser","mention":"@Browser","label":"Browser"}
+# setup attachment: {"type":"file","name":"package.json","label":"package.json"}
+```
+
+The SDK does not own API keys, proxy URLs, OpenAI clients, host app state, app profiles, selectors, or mock data.
+
+Generic setup helpers are available for app hydration:
+
+```typescript
+import {
+  parseAppFilmSetup,
+  prepareAppFilmScript,
+  serializeAppFilmSetup,
+  stripAppFilmSetup,
+  validateAppFilmScript,
+} from "@codefilm/recorder/app-script";
+
+const setup = parseAppFilmSetup(result.script, app.id);
+const validation = validateAppFilmScript(result.script, app);
+const executableScript = stripAppFilmSetup(result.script);
+```
+
+For route, worker, or storage handoff flows, prefer preparing the script once before displaying or playing it:
+
+```typescript
+const prepared = prepareAppFilmScript(result.script, {
+  app,
+  setup: result.setup,
+});
+
+hydrateAppFromFilmSetup(prepared.setup);
+setEditorText(prepared.displayScript); // setup comments stripped by default
+await recorder.runFilmScript(prepared.runnableScript);
+
+const handoffId = crypto.randomUUID();
+sessionStorage.setItem(`host-film:${handoffId}`, prepared.fullScript);
+```
+
+On the receiving host surface:
+
+```typescript
+const fullScript = sessionStorage.getItem(`host-film:${handoffId}`) ?? "";
+const prepared = prepareAppFilmScript(fullScript, { app });
+
+if (prepared.isFilmScript) {
+  hydrateAppFromFilmSetup(prepared.setup);
+  setVisibleScript(prepared.displayScript);
+  await recorder.runFilmScript(prepared.runnableScript);
+}
+```
+
+`fullScript` preserves setup comments for debugging and durable handoff. `displayScript` and `runnableScript` strip setup comments by default so metadata such as `# setup collection: ...` is not shown or typed as user prompt text.
+
+Enable trace metadata when debugging model/tool behavior:
+
+```typescript
+import { AppFilmGenerationError } from "@codefilm/recorder/app-script";
+
+try {
+  const traced = await generateAppFilmScript({
+    app,
+    input: "use Browser to inspect localhost",
+    complete,
+    repair: true,
+    trace: {
+      enabled: true,
+      includeRaw: false,
+      redact: (call) => ({
+        ...call,
+        request: {
+          ...call.request,
+          input: call.request.input.replace(/sk-[A-Za-z0-9_-]+/g, "[redacted]"),
+        },
+      }),
+    },
+  });
+
+  console.log(traced.trace?.calls.map((call) => call.phase));
+} catch (err) {
+  if (err instanceof AppFilmGenerationError) {
+    console.error(err.trace?.calls);
+  }
+  throw err;
+}
+```
+
+Trace calls capture `intent`, `script`, and `repair` phases, including tool definitions, tool-call arguments, timings, diagnostics, warnings, and errors. Provider `raw` payloads are omitted unless `includeRaw: true`.
+
+#### Prompt-to-Script Examples
+
+These examples show how minimal prompts should resolve before script generation. The host app owns the profile recipes, selectors, setup hydration, and prompt-chip rendering; the SDK provides the intent/tool-call structure and validation.
+
+##### `edit box`
+
+Prompt:
+
+```txt
+edit box
+```
+
+Resolved intent:
+
+```json
+{
+  "id": "show-edits",
+  "page": "thread",
+  "scopeSelector": ".preview-card.edited-files",
+  "submitPrompt": false,
+  "setupNeeded": ["collection", "item", "activeItem", "card:edited_files"],
+  "rationale": "The prompt names the edited-files UI, not a task to submit."
+}
+```
+
+Film script:
+
+```film
+# setup collection: {"id":"changes","label":"Changes"}
+# setup item: {"id":"package_edits","collectionId":"changes","label":"Package JSON Edits","time":"now"}
+# setup activeItem: "package_edits"
+# setup card: {"type":"edited_files","itemId":"package_edits","files":[{"path":"package.json","additions":"+1","deletions":"-0"}]}
+
+film "Show Package Edits" {
+  duration: 8s
+  aspect: 16:9
+  fps: 30
+
+  scene "Edited Files" @0s -> 8s {
+    camera { selector: ".preview-card.edited-files" padding: 1.16 }
+    pointer { selector: ".preview-card.edited-files" durationMs: 600 }
+    wait 7s
+  }
+}
+```
+
+##### `prompt box`
+
+Prompt:
+
+```txt
+prompt box
+```
+
+Resolved intent:
+
+```json
+{
+  "id": "focus-prompt",
+  "page": "home",
+  "scopeSelector": ".chat-input-card.prompt-box",
+  "submitPrompt": false,
+  "rationale": "The user named the prompt UI region and did not ask to type or submit."
+}
+```
+
+Film script:
+
+```film
+film "Prompt Box" {
+  duration: 5s
+  aspect: 16:9
+  fps: 30
+
+  scene "Prompt Box" @0s -> 5s {
+    camera { selector: ".chat-input-card.prompt-box" padding: 1.18 }
+    pointer { selector: ".chat-input-card.prompt-box" durationMs: 600 }
+    wait 4s
+  }
+}
+```
+
+##### `prompt box with sidebar`
+
+Prompt:
+
+```txt
+prompt box with sidebar
+```
+
+Resolved intent:
+
+```json
+{
+  "id": "focus-prompt",
+  "page": "home",
+  "scopeSelector": ".app-layout",
+  "submitPrompt": false,
+  "rationale": "The user asked to include sidebar, so use the full app shell."
+}
+```
+
+Film script:
+
+```film
+film "Prompt Box With Sidebar" {
+  duration: 6s
+  aspect: 16:9
+  fps: 30
+
+  scene "Prompt And Sidebar" @0s -> 6s {
+    camera { selector: ".app-layout" padding: 1.04 }
+    pointer { selector: ".chat-input-card.prompt-box" durationMs: 600 }
+    wait 5s
+  }
+}
+```
+
+##### `hello, world`
+
+Prompt:
+
+```txt
+hello, world
+```
+
+Resolved intent:
+
+```json
+{
+  "id": "render-text",
+  "page": "text",
+  "scopeSelector": ".new-film-text-card",
+  "submitPrompt": false,
+  "setupNeeded": ["text"],
+  "rationale": "The prompt is standalone text to render, not text to submit to the app."
+}
+```
+
+Film script:
+
+```film
+# setup text: {"text":"hello, world","duration":5}
+
+film "Hello World" {
+  duration: 5s
+  aspect: 16:9
+  fps: 30
+
+  scene "Text" @0s -> 5s {
+    camera { selector: ".new-film-text-card" padding: 1.18 }
+    wait 5s
+  }
+}
+```
+
+##### `apple pie website`
+
+Prompt:
+
+```txt
+apple pie website
+```
+
+Resolved intent:
+
+```json
+{
+  "id": "submit-prompt",
+  "page": "home",
+  "scopeSelector": ".chat-input-card",
+  "submitPrompt": true,
+  "promptText": "make a website about apple pie"
+}
+```
+
+Film script:
+
+```film
+film "Apple Pie Website" {
+  duration: 12s
+  aspect: 16:9
+  fps: 30
+
+  scene "Ask Codex" @0s -> 6s {
+    camera { selector: ".chat-input-card" padding: 1.16 }
+    type { selector: "#codex-prompt-input" text: "make a website about apple pie" cps: 24 }
+    pointer { selector: ".send-button" durationMs: 600 }
+    wait 800ms
+    click { selector: ".send-button" }
+    wait 1s
+  }
+
+  scene "Watch Response" @6s -> 12s {
+    camera { selector: ".chat-history-container" padding: 1.12 }
+    pointer { selector: ".chat-history-container" durationMs: 600 }
+    wait 5s
+  }
+}
+```
+
+##### `type hello into prompt`
+
+Prompt:
+
+```txt
+type hello into prompt
+```
+
+Resolved intent:
+
+```json
+{
+  "id": "submit-prompt",
+  "confidence": 0.9,
+  "page": "home",
+  "scopeSelector": ".chat-input-card",
+  "submitPrompt": true,
+  "promptText": "hello",
+  "rationale": "The user explicitly asked to type text into the prompt."
+}
+```
+
+Expected script shape:
+
+```film
+type { selector: "#codex-prompt-input" text: "hello" cps: 24 }
+pointer { selector: ".send-button" durationMs: 600 }
+wait 800ms
+click { selector: ".send-button" }
+```
+
+##### `use Computer to open settings`
+
+Prompt:
+
+```txt
+use Computer to open settings
+```
+
+Resolved intent:
+
+```json
+{
+  "id": "submit-prompt",
+  "page": "home",
+  "scopeSelector": ".chat-input-card",
+  "submitPrompt": true,
+  "promptText": "open System Settings",
+  "promptTools": [
+    { "id": "computer_use", "mention": "@Computer", "label": "Computer" }
+  ]
+}
+```
+
+Film script:
+
+```film
+# setup promptTool: {"id":"computer_use","mention":"@Computer","label":"Computer"}
+
+film "Open Settings With Computer" {
+  duration: 10s
+  aspect: 16:9
+  fps: 30
+
+  scene "Ask Computer" @0s -> 5s {
+    camera { selector: ".chat-input-card" padding: 1.16 }
+    type { selector: "#codex-prompt-input" text: "@Computer open System Settings" cps: 24 }
+    pointer { selector: ".send-button" durationMs: 600 }
+    wait 800ms
+    click { selector: ".send-button" }
+    wait 1s
+  }
+
+  scene "Watch Response" @5s -> 10s {
+    camera { selector: ".chat-history-container" padding: 1.12 }
+    pointer { selector: ".chat-history-container" durationMs: 600 }
+    wait 4s
+  }
+}
+```
+
+##### Six-word prompts
+
+Prompt:
+
+```txt
+Show package edits in thread output
+```
+
+Film script:
+
+```film
+# setup collection: {"id":"changes","label":"Changes"}
+# setup item: {"id":"package_edits","collectionId":"changes","label":"Package JSON Edits","time":"now"}
+# setup activeItem: "package_edits"
+# setup card: {"type":"edited_files","itemId":"package_edits","files":[{"path":"package.json","additions":"+1","deletions":"-0"}]}
+
+film "Package Edits" {
+  duration: 8s
+  aspect: 16:9
+  fps: 30
+
+  scene "Show Edits" @0s -> 8s {
+    camera { selector: ".preview-card.edited-files" padding: 1.16 }
+    pointer { selector: ".preview-card.edited-files" durationMs: 600 }
+    wait 7s
+  }
+}
+```
+
+Plugin-aware prompts:
+
+```txt
+Use Computer to open System Settings
+Ask Browser to inspect localhost homepage
+```
+
+Expected script snippets:
+
+```film
+# setup promptTool: {"id":"computer_use","mention":"@Computer","label":"Computer"}
+type { selector: "#codex-prompt-input" text: "@Computer open System Settings" cps: 24 }
+
+# setup promptTool: {"id":"browser","mention":"@Browser","label":"Browser"}
+type { selector: "#codex-prompt-input" text: "@Browser inspect the localhost homepage" cps: 24 }
+```
+
+##### Twelve-word prompts
+
+Prompt:
+
+```txt
+Show the prompt box with sidebar and active thread visible together
+```
+
+Film script:
+
+```film
+film "Prompt Box With Sidebar" {
+  duration: 6s
+  aspect: 16:9
+  fps: 30
+
+  scene "Prompt And Sidebar" @0s -> 6s {
+    camera { selector: ".app-layout" padding: 1.04 }
+    pointer { selector: ".chat-input-card.prompt-box" durationMs: 600 }
+    wait 5s
+  }
+}
+```
+
+Plugin-aware prompts:
+
+```txt
+Use Documents to summarize attached proposal and show answer in thread output
+Ask Browser to open localhost then return to prompt box view again
+```
+
+Expected script snippets:
+
+```film
+# setup promptTool: {"id":"documents","mention":"@Documents","label":"Documents"}
+# setup attachment: {"type":"file","name":"proposal.docx","label":"proposal.docx"}
+type { selector: "#codex-prompt-input" text: "@Documents summarize the attached proposal" cps: 24 }
+
+# setup promptTool: {"id":"browser","mention":"@Browser","label":"Browser"}
+type { selector: "#codex-prompt-input" text: "@Browser open localhost and report what is visible" cps: 24 }
+```
+
+##### Eighteen-word prompts
+
+Prompt:
+
+```txt
+Type apple pie website into Codex, submit it, then show the response appearing in the thread
+```
+
+Film script:
+
+```film
+film "Apple Pie Website" {
+  duration: 12s
+  aspect: 16:9
+  fps: 30
+
+  scene "Submit Prompt" @0s -> 6s {
+    camera { selector: ".chat-input-card" padding: 1.16 }
+    type { selector: "#codex-prompt-input" text: "make a website about apple pie" cps: 24 }
+    pointer { selector: ".send-button" durationMs: 600 }
+    wait 800ms
+    click { selector: ".send-button" }
+    wait 1s
+  }
+
+  scene "Show Response" @6s -> 12s {
+    camera { selector: ".chat-history-container" padding: 1.12 }
+    pointer { selector: ".chat-history-container" durationMs: 600 }
+    wait 5s
+  }
+}
+```
+
+Plugin-aware prompts:
+
+```txt
+Use Computer to open System Settings change nothing then show the prompt and response thread inside Codex UI
+Attach package.json ask OpenAI Developers to review scripts then show edited files inside prepared thread output view panel
+```
+
+Expected script snippets:
+
+```film
+# setup promptTool: {"id":"computer_use","mention":"@Computer","label":"Computer"}
+type { selector: "#codex-prompt-input" text: "@Computer open System Settings and report what is visible without changing anything" cps: 24 }
+
+# setup promptTool: {"id":"openai_developers","mention":"@OpenAI Developers","label":"OpenAI Developers"}
+# setup attachment: {"type":"file","name":"package.json","label":"package.json"}
+type { selector: "#codex-prompt-input" text: "@OpenAI Developers review the package.json scripts" cps: 24 }
+```
+
+##### Twenty-four-word prompts
+
+Prompt:
+
+```txt
+Start on a prepared package changes thread, focus the edited files card, then briefly show the thinking and activity rows below
+```
+
+Film script:
+
+```film
+# setup collection: {"id":"changes","label":"Changes"}
+# setup item: {"id":"package_edits","collectionId":"changes","label":"Package JSON Edits","time":"now"}
+# setup activeItem: "package_edits"
+# setup card: {"type":"edited_files","itemId":"package_edits","files":[{"path":"package.json","additions":"+1","deletions":"-0"}]}
+
+film "Package Changes Thread" {
+  duration: 12s
+  aspect: 16:9
+  fps: 30
+
+  scene "Edited Files" @0s -> 6s {
+    camera { selector: ".preview-card.edited-files" padding: 1.16 }
+    pointer { selector: ".preview-card.edited-files" durationMs: 600 }
+    wait 5s
+  }
+
+  scene "Thread Activity" @6s -> 12s {
+    camera { selector: ".chat-history-container" padding: 1.12 }
+    pointer { selector: ".thread-activity-status" durationMs: 600 }
+    wait 5s
+  }
+}
+```
+
+Plugin-aware prompts:
+
+```txt
+Use Browser to check localhost attach screenshot ask Build Web Apps to improve hero then show activity and edited files in thread output panel
+Attach package.json and README ask OpenAI Developers to review release notes then focus response activity row and terminal inside the prepared Codex thread view
+```
+
+Expected script snippets:
+
+```film
+# setup promptTool: {"id":"browser","mention":"@Browser","label":"Browser"}
+# setup promptTool: {"id":"build_web_apps","mention":"@Build Web Apps","label":"Build Web Apps"}
+# setup attachment: {"type":"image","name":"screenshot.png","label":"screenshot.png"}
+type { selector: "#codex-prompt-input" text: "@Browser @Build Web Apps check localhost and improve the hero using the screenshot" cps: 24 }
+
+# setup promptTool: {"id":"openai_developers","mention":"@OpenAI Developers","label":"OpenAI Developers"}
+# setup attachment: {"type":"file","name":"package.json","label":"package.json"}
+# setup attachment: {"type":"file","name":"README.md","label":"README.md"}
+type { selector: "#codex-prompt-input" text: "@OpenAI Developers review release notes using package.json and README context" cps: 24 }
+```
+
+##### UI state prompts
+
+Prompt:
+
+```txt
+Thinking
+```
+
+Film script:
+
+```film
+# setup activeItem: "thinking_thread"
+# setup status: {"type":"thinking","itemId":"thinking_thread","text":"Thinking"}
+
+film "Thinking Status" {
+  duration: 5s
+  aspect: 16:9
+  fps: 30
+
+  scene "Thinking" @0s -> 5s {
+    camera { selector: ".thread-thinking-status" padding: 1.18 }
+    pointer { selector: ".thread-thinking-status" durationMs: 600 }
+    wait 5s
+  }
+}
+```
+
+Prompt:
+
+```txt
+Worked for 1m 40s, and then go to click Update
+```
+
+Film script:
+
+```film
+# setup activeItem: "worked_time_thread"
+# setup status: {"type":"worked_time","itemId":"worked_time_thread","text":"1m 40s"}
+
+film "Worked Time Then Update" {
+  duration: 9s
+  aspect: 16:9
+  fps: 30
+
+  scene "Worked Time" @0s -> 5s {
+    camera { selector: ".worked-time-bar" padding: 1.18 }
+    pointer { selector: ".worked-time-bar" durationMs: 600 }
+    wait 4s
+  }
+
+  scene "Click Update" @5s -> 9s {
+    camera { selector: ".sidebar-container" padding: 1.12 }
+    pointer { selector: ".update-btn" durationMs: 600 }
+    wait 800ms
+    click { selector: ".update-btn" }
+    wait 2s
+  }
+}
+```
+
+---
+
+### 3. Deterministic Structured Script Runner (Offline, Zero-Cost)
+
+For structured film scripts, you can run them entirely client-side without any LLM API calls. This avoids token usage, latency, and agent turn limits.
+
+```typescript
+const script = `
+film "Product Search Demo" {
+  duration: 10s
+  aspect: 16:9
+  fps: 30
+
+  scene "Prompt" @0s -> 4s {
+    camera { selector: ".demo-input-card" padding: 1.16 }
+    type { selector: "#demo-prompt-input" text: "find ergonomic keyboards" cps: 22 }
+    click { selector: ".demo-submit-button" }
+    wait 900ms
+  }
+
+  scene "Result" @4s -> 7s {
+    camera { selector: ".demo-output-panel" padding: 1.15 }
+    wait 1500ms
+  }
+
+  scene "Details" @7s -> 10s {
+    click { selector: "[data-film-target='details']" }
+    camera { selector: ".demo-details-panel" padding: 1.08 }
+    wait 1600ms
+    camera { selector: null }
+  }
+}
+`;
+
+// Run offline script directly
+await recorder.runFilmScript(script, {
+  signal: abortController.signal, // optional AbortSignal to cancel tour execution
+  selectorTimeoutMs: 300, // fail fast if a required selector is not ready
+  typingDefaults: {
+    cps: 24,
+    jitter: 0.22,
+    punctuationPauseMs: 120,
+    mistakeRate: 0.012,
+  },
+  typingSeed: "product-search-demo-v1",
+  onSceneStart: async (scene) => console.log(`Scene started: ${scene.name}`),
+  onSceneEnd: async (scene) => console.log(`Scene ended: ${scene.name}`),
+  waitForCompletion: async ({ signal }) => {
+    await appRenderPromise;
+    if (signal.aborted) return;
+    await waitForReactPaint();
+  },
+  completionTimeoutMs: 120_000,
+});
+```
+
+Selector-based actions wait up to `selectorTimeoutMs` for their target. The default is `3000ms` for compatibility, but deterministic recordings often benefit from a shorter run-level timeout after app setup is complete:
+
+```typescript
+hydrateAppFromFilmSetup(setup);
+await waitForRequiredSelectors(script, { timeoutMs: 5000 });
+await recorder.startRecording();
+await recorder.runFilmScript(script, {
+  selectorTimeoutMs: 300,
+});
+```
+
+Typing options merge from lowest to highest priority:
+
+```text
+SDK defaults → recorder typingDefaults → run typingDefaults → type command fields
+```
+
+Use the exported natural preset when one profile is sufficient:
+
+```typescript
+import { FilmRecorder, HUMAN_TYPING_PRESET } from "@codefilm/recorder";
+
+const recorder = new FilmRecorder({
+  typingDefaults: HUMAN_TYPING_PRESET,
+  typingSeed: "repeatable-demo",
+});
+
+recorder.setTypingDefaults({
+  cps: 28,
+  jitter: 0.18,
+});
+```
+
+Film scripts support the complete typing vocabulary in one-line or multiline form:
+
+```typescript
+type {
+  selector: "#demo-prompt-input"
+  text: "find ergonomic keyboards"
+  cps: 24
+  jitter: 0.22
+  punctuationPauseMs: 120
+  mistakeRate: 0.012
+}
+```
+
+The `type` command always performs the full visible interaction sequence internally:
+
+```text
+move pointer → click/focus target → human-like type
+```
+
+Use `pointer` when the script should visibly focus a target without clicking it:
+
+```typescript
+scene "Preview target" @0s -> 2s {
+  camera { selector: ".target" padding: 1.12 }
+  pointer { selector: ".target" durationMs: 600 }
+  wait 500ms
+}
+```
+
+The older `move` command remains supported as a backwards-compatible alias.
+
+Use `zoom` for full-frame top, center, or bottom camera moves. This exposes the same framing effect as the manual `Cmd/Ctrl + ArrowUp` and `Cmd/Ctrl + ArrowDown` shortcuts:
+
+```typescript
+scene "Show lower fold" @0s -> 3s {
+  zoom { to: "bottom" }
+  wait 1s
+  zoom { to: "top" }
+  wait 1s
+  zoom { to: "center" }
+}
+```
+
+Customize the virtual pointer with one or more additional CSS classes:
+
+```typescript
+const recorder = new FilmRecorder({
+  pointerClassName: "my-demo-pointer high-contrast",
+  pointerFillColor: "#ffffff",
+  pointerBorderColor: "#18181b",
+  pointerRippleColor: "#64748b",
+  disableRipple: false,
+});
+
+recorder.setPointerClassName("my-demo-pointer compact");
+recorder.setPointerFillColor("#f8fafc");
+recorder.setPointerBorderColor("#0f172a");
+recorder.setPointerRippleColor("#38bdf8");
+recorder.setDisableRipple(true);
+```
+
+The SDK always preserves its base `cfr-simulated-pointer` class and click-state class.
+
+Recordings open on the largest top-anchored frame, and the virtual pointer's first movement enters from below the viewport.
+
+Lifecycle callbacks are async-aware. When a deterministic script or recorder agent finishes successfully, the SDK awaits `onReadyToEnd`, returns the camera to the top frame, holds it for one second, and then stops recording:
+
+```typescript
+const recorder = new FilmRecorder({
+  onReadyToEnd: async ({ recorder, signal, scenes }) => {
+    await persistTourState({ signal, sceneCount: scenes.length });
+    console.log("Final closing shot has started", recorder);
+  },
+});
+
+await recorder.runFilmScript(script, {
+  waitForCompletion: async ({ signal }) => {
+    await appRenderPromise;
+    if (!signal.aborted) await waitForReactPaint();
+  },
+});
+// Recording is stopped after the one-second closing shot.
+```
+
+The guaranteed completion order is:
+
+```text
+execute scenes
+→ await waitForCompletion()
+→ await onReadyToEnd()
+→ closing camera shot
+→ stop recording
+→ create/download artifact
+```
+
+For custom integrations, separate script execution from recording finalization:
+
+```typescript
+await recorder.executeFilmScript(script, {
+  signal: abortController.signal,
+});
+await externalWork;
+await recorder.finishRecording();
+```
+
+`waitForCompletion` observes the unified tour abort signal. It defaults to a 120-second timeout, configurable with `completionTimeoutMs`.
+
+Register application work from the action that triggered it to avoid stale completion promises:
+
+```typescript
+await recorder.runFilmScript(script, {
+  onActionEnd: async ({
+    command,
+    scene,
+    commandIndex,
+    signal,
+    waitUntil,
+  }) => {
+    if (command.type === "click" && command.selector === ".demo-submit-button") {
+      waitUntil(getActiveRenderPromise(signal));
+    }
+    console.log(scene.name, commandIndex);
+  },
+});
+```
+
+`finishRecording()` is guarded and idempotent. If called while execution or registered gates are active, it waits before starting the closing shot. Use `finishRecording({ force: true })` only to bypass those gates intentionally; `stopAll()` remains the immediate cancellation path.
+
+Observe `state.executionState` for `idle`, `executing`, `waiting`, `finalizing`, `finished`, and `error`.
+
+Validate generated scripts before requesting screen capture:
+
+```typescript
+const result = recorder.validateFilmScript(script);
+if (!result.valid) {
+  console.error(result.diagnostics);
+  return;
+}
+```
+
+---
+
+### 3. Human-Like Typing Configuration
+
+You can make typing simulations look natural (adding variations, punctuation pauses, or mistakes/backspacing) by passing `TypingOptions` to `simulateType`:
+
+```typescript
+await recorder.simulateType("#input-field", "Hello world. Let's test the editor!", {
+  cps: 25,                 // Characters per second
+  jitter: 0.25,            // 25% timing jitter variation (adds human speed changes)
+  punctuationPauseMs: 150, // Extra wait after punctuation marks (.,!?;:)
+  mistakeRate: 0.05,       // 5% chance of making a typo and backspacing to correct it
+});
+```
+
+---
+
+### 4. Selector Safety & Text Helpers
+
+All tool selectors are standard CSS selectors passed to `document.querySelector`. To make writing scripts easier, the SDK provides safe text-based selectors:
+
+```typescript
+// Move pointer to and click the button or link containing the text "Plugins"
+await recorder.clickText("Plugins");
+
+// Target camera crop and animate pointer to the element containing "Connect files"
+await recorder.focusText("Connect files");
+```
+
+If a selector or text target fails to locate any elements in the DOM, the SDK throws a descriptive, action-oriented error suggesting fixes (like adding stable `data-*` attributes).
+
+---
+
+### 5. Unified Abort/Stop Semantics
+
+Calling `recorder.stopTour()` or `recorder.stopAll()` will immediately stop all active typing runs, mouse pointer slides, scene waits, and LLM calls by triggering unified inner abort signals.
+
+```typescript
+// Aborts active tour runs immediately
+recorder.stopTour();
+
+// Aborts active tour runs and stops the browser media stream capture
+recorder.stopAll();
+```
+---
+
+## Configuration Options (`FilmRecorderOptions`)
+
+You can customize the recorder behavior by passing options:
+
+| Property                 | Type             | Default            | Description                                                         |
+| :----------------------- | :--------------- | :----------------- | :------------------------------------------------------------------ |
+| `fps`                    | `number`         | `60`               | Capture framerate.                                                  |
+| `resolutions`            | `Resolution[]`   | _Standard presets_ | Target output aspects (YouTube, TikTok, Instagram, etc.).           |
+| `defaultResolutionIndex` | `number`         | `0`                | Default active index in the resolutions list.                       |
+| `autoZoom`               | `boolean`        | `true`             | Enable focal zooming centered on mouse cursor.                      |
+| `pauseDuringScroll`      | `boolean`        | `true`             | Prevent zoom snapping while scrolling page content.                 |
+| `showGrid`               | `boolean`        | `true`             | Show helper columns/rows during layout mode.                        |
+| `showOutline`            | `boolean`        | `false`            | Include a colored outline around the captured region.               |
+| `enableShortcuts`        | `boolean`        | `true`             | Bind key combinations (`Ctrl+J` / `Cmd+J` for record toggle, etc.). |
+| `elementSelector`        | `string \| null` | `null`             | Query selector of the DOM element to track and record.              |
+| `elementPadding`         | `number`         | `1.1`              | Proportional padding multiplier around the tracked element.         |
+| `fixedRecordingRegion`  | `"smallest-16:9" \| null` | `null` | Keep the capture box at the smallest 16:9 grid size instead of auto-fitting elements. |
+| `movePointerToSelector`  | `string \| null` | `null`             | CSS Selector to automatically run a simulated pointer zoom tour.    |
+| `pointerClassName`       | `string`         | `""`               | Additional CSS class names applied to the virtual pointer element.  |
+| `pointerFillColor`       | `string`         | `"#ffffff"`        | Six-digit hex fill color for the virtual pointer SVG.               |
+| `pointerBorderColor`     | `string`         | `"#18181b"`        | Six-digit hex border color for the virtual pointer SVG.             |
+| `pointerRippleColor`     | `string`         | `"#64748b"`        | Six-digit hex color for the concentric click ripple.                |
+| `disableRipple`          | `boolean`        | `false`            | Disable concentric click ripple while preserving pointer clicks.    |
+| `ignoreSelector`         | `string \| null` | `null`             | CSS selector for DOM elements to hide during active recording.      |
+| `overlays`               | `RecordingOverlayDefinition[]` | `[]` | SDK-managed recording overlays such as `cameraOverlay(...)`.        |
+| `includeTimelineMetadata`    | `boolean`        | `false`            | Attach scene, action, and marker timing metadata to recording artifact. |
+| `selectorTimeoutMs`      | `number`         | `3000`             | Max wait for selector-based script actions before failing.          |
+
+---
+
+## Custom Theming
+
+Style the overlays and settings bar using CSS variables. Override these variables in your global CSS to match your application's design:
+
+```css
+:root {
+  /* Colors */
+  --cfr-bg: rgba(9, 9, 11, 0.9); /* Settings bar background color */
+  --cfr-fg: #f4f4f5; /* Text color */
+  --cfr-border: rgba(255, 255, 255, 0.1); /* Divider / grid line color */
+  --cfr-primary: #f4f4f5; /* Button default background */
+  --cfr-primary-fg: #09090b; /* Button default text */
+  --cfr-secondary: #27272a; /* Secondary button background */
+  --cfr-secondary-fg: #f4f4f5; /* Secondary button text */
+  --cfr-destructive: #ef4444; /* Recording state red background */
+  --cfr-outline: #f43f5e; /* Outline border color when enabled */
+
+  /* Glassmorphism */
+  --cfr-glass-blur: 12px; /* Backdrop blur level */
+}
+```
+
+---
+
+## Iframe Considerations
+
+If your application embeds `<iframe>` elements:
+
+1. **Canvas Cropping is Safe**: The browser's media recorder takes a screen/tab stream approved by the user. Drawing this stream to the canvas **does not taint the canvas**, meaning tab recording works perfectly even with cross-origin frames loaded.
+2. **Auto Zoom Hover Boundary**: Moving the cursor _inside_ a cross-origin iframe does not bubble mouse events up to the parent React application. To focus areas inside the iframe, use the manual zoom APIs (`zoomTop()`, `zoomCenter()`, `zoomBottom()`), the `zoom { to: "..." }` script command, or the shortcut hotkeys (`Cmd/Ctrl + ArrowDown` or `Cmd/Ctrl + ArrowUp`).
+
+---
+
+## Troubleshooting
+
+### Hook Conflict (Multiple Copies of React)
+
+When using npm linking for local development, you might encounter a "Hooks can only be called inside the body of a component" error. This is a common issue with local npm packages importing their own React copy.
+
+**Resolution**: Configure your bundler or build environment to resolve React to the application's root `node_modules`, or create symlinks inside the package folder:
+
+```bash
+cd node_modules/@codefilm/recorder
+npm link ../../node_modules/react
+npm link ../../node_modules/react-dom
+```
+
+---
+
+## License
+
+MIT © CodeFilm