openvideokit 0.1.0__tar.gz

openvideokit-0.1.0/.env.example

@@ -0,0 +1,97 @@
+# ──────────────────────────────────────────────────────────────────────────
+# OpenVideoKit environment variables — copy to `.env` and fill in.
+# `.env` is gitignored; never commit real keys.
+# All vars are optional unless marked (required).
+#
+# Most users only edit the AI section below (OPENAI_*). Server + Frontend
+# defaults work out of the box.
+# ──────────────────────────────────────────────────────────────────────────
+
+# ── AI (LangGraph agent — see docs/ai.md) ─────────────────────────────────
+# Any OpenAI-compatible endpoint works: OpenAI, OpenRouter, Ollama, vLLM, LM Studio.
+# OpenAI:           https://api.openai.com/v1
+# OpenRouter:       https://openrouter.ai/api/v1
+# Requesty:         https://router.requesty.ai/v1
+# Ollama:           http://localhost:11434/v1
+OPENAI_BASE_URL=https://openrouter.ai/api/v1
+# (required to use AI) Your API key for the endpoint above.
+OPENAI_API_KEY=
+# Default chat model id (whatever the endpoint above accepts).
+# OVK_AI_MODEL=gpt-5.4-nano
+# OVK_AI_MODEL=openai/gpt-oss-120b:free
+# OVK_AI_MODEL=google/gemma-4-26b-a4b-it:free
+# OVK_AI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free
+OVK_AI_MODEL=poolside/laguna-xs-2.1:free
+# Reserved for Tier-2 (set_slide_html) coding model; v1 falls back to OVK_AI_MODEL.
+# OVK_AI_TIER2_MODEL=gpt-5.4-nano
+OVK_AI_TIER2_MODEL=openrouter/free
+# Sampling temperature for the agent.
+OVK_AI_TEMPERATURE=0.3
+# Cap on agent tool-calling steps per turn (bounds cost + latency).
+OVK_AI_MAX_STEPS=50
+# Reasoning effort for reasoning-capable models: low / medium / high.
+# Leave empty for non-reasoning models (gpt-4o-mini, etc.) — passing it errors.
+# Set when OVK_AI_MODEL is a reasoning model (gpt-5, o1, o3, gpt-oss, …).
+OVK_AI_REASONING_EFFORT=medium
+
+# ── AI Web tools (see docs/ai.md §Web Tools) ──────────────────────────────
+# web_search (DuckDuckGo via ddgs) + web_fetch (crawl4ai/Playwright).
+# The tools are always registered so the agent knows they exist; this flag
+# controls whether a call actually hits the network or returns a "disabled"
+# notice the agent relays to the user.
+# On = each web_fetch launches a headless Chromium. First run also needs:
+#   uv run playwright install chromium
+OVK_ENABLE_WEB=true
+
+# ── AI monitoring (see docs/ai-monitoring.md) ─────────────────────────────
+# Dump the full LLM context (system prompt + tools + messages + project
+# snapshot) + a live execution trace per run_agent turn to
+# {OVK_DATA_DIR}/{project_id}/monitor/. Defaults ON during initial
+# development; set false in production.
+OVK_AI_MONITORING=true
+# Comma-separated sink list. Only "file" is implemented today; reserved for
+# future sinks (s3, otlp, http, langsmith).
+# OVK_AI_MONITORING_SINKS=file
+# Per-tool-result truncation cap (chars) in trace files. 0 = no truncation.
+# OVK_AI_MONITORING_TOOL_LIMIT=8000
+
+# ── Server ────────────────────────────────────────────────────────────────
+OVK_HOST=0.0.0.0
+OVK_PORT=8000
+# Where generated audio + assets + project JSON are written (relative to cwd).
+OVK_DATA_DIR=data
+# Where render job dirs + output MP4s are written. Defaults to {OVK_DATA_DIR}/jobs.
+OVK_JOBS_DIR=data/jobs
+# Where the committed slide-layout templates live (read-only catalog).
+# Defaults to <repo_root>/templates/slides.
+# OVK_TEMPLATES_SLIDES_DIR=templates/slides
+# Max concurrent render subprocesses (1–2 for a laptop).
+OVK_MAX_CONCURRENT_RENDERS=1
+# Chrome workers PER render subprocess (passed to `hyperframes render --workers`).
+OVK_RENDER_HF_WORKERS=3
+# Auto-render preview MP4s for every slide-layout template on `ovk serve`
+# startup. Renders happen sequentially before the server accepts requests.
+# Output is gitignored (templates/slides/**/output.mp4). Set false to skip.
+OVK_TEMPLATES_AUTO_RENDER=true
+# Base URL prepended to the content-key when building media asset URLs
+# (images/video/audio). Default: local serve path (/api/assets/<key>.<ext>).
+# Set absolute (https://bucket.s3.amazonaws.com/assets/) to serve from S3/CDN.
+OVK_ASSETS_BASE_URL=/api/assets/
+
+# ── MCP server (see docs/mcp.md) ──────────────────────────────────────────
+# Expose the OVK toolset to external AI agents (Claude Code, Cursor, Gemini
+# CLI) via the Model Context Protocol at /mcp/. Enabled by default.
+# Set false to disable the /mcp endpoint.
+OVK_MCP_ENABLED=true
+# MCP token — NOT YET ENFORCED (OVK-SEC-011). The /mcp endpoint is
+# unauthenticated regardless of this value. Do not rely on it for security.
+# OVK_MCP_TOKEN=
+
+# ── Frontend (Vite, ovk-web/) ─────────────────────────────────────────────
+# The browser SPA reads these at build/dev time, not the Python server.
+# Point the SPA at a remote backend instead of the Vite dev proxy.
+VITE_API_BASE_URL=/api
+# Auto-continue the AI agent after you Accept a proposal (sends a receipt
+# with the created/edited slide ids so the AI knows the real state, then
+# auto-fires the next turn). Default on; set false to disable.
+VITE_AI_AUTOCONTINUE=true

openvideokit-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.pytest_cache/
+.ruff_cache/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Runtime data (created on demand, never commit)
+sessions/
+jobs/
+data/
+*.log
+*.mp4
+*.webm
+*.mov
+
+# Generated TTS artifacts (not source)
+templates/*/assets/voiceover.mp3
+templates/*/assets/voiceover_timings.json
+
+# HyperFrames render work directories (created by npx hyperframes render)
+templates/**/work-*
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*~
+
+# Local secrets / overrides
+.env
+.env.local
+*.local
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Built SPA (produced by `pnpm --filter ovk-web build`, never commit).
+# Vite outputs into static/ (see ovk-web/vite.config.ts → build.outDir).
+static/
+
+tmp/
+
+# Local act test secrets (never commit)
+scripts/.act.secrets

openvideokit-0.1.0/AGENTS.md

@@ -0,0 +1,377 @@
+# AGENTS.md
+
+> Guide for AI agents working on OpenVideoKit.
+
+## What is this repo?
+
+OpenVideoKit is a **scene-based, AI-first video editor**. Users edit slides in a React SPA → a Python SSR server stamps values into self-contained GSAP compositions → `<hyperframes-player>` renders them live → edge-tts generates voiceover → export to MP4 via `npx hyperframes render`. A **LangGraph AI copilot** (BYO key) proposes edits the user accepts or rejects (AI flow == human flow), and an **MCP server** lets any external AI agent (Claude Code, Cursor, Gemini CLI, Goose) drive the same 28-tool API. Inference runs on the user's own machine — the cloud control plane never proxies and never charges.
+
+**Tech stack:** Python 3.13, FastAPI, uv, edge-tts, HyperFrames (Node CLI), GSAP, FFmpeg, LangGraph, FastMCP; React 19 + Vite frontend.
+
+## Quick start
+
+```bash
+uv sync --extra dev          # install all deps
+cp .env.example .env         # then edit .env (set OPENAI_API_KEY for AI)
+uv run openvideokit          # serve on http://0.0.0.0:8765
+```
+
+## Environment variables
+
+All runtime config is env-driven. A root `.env` (gitignored) is **auto-loaded**
+by `src/openvideokit/config.py` via `python-dotenv` at import time —
+`load_dotenv()` is a silent no-op if `.env` is absent, so the server boots fine
+either way; real env vars always override `.env`. See `.env.example` for the
+full documented list. Groups:
+
+| Group | Vars | Where |
+|---|---|---|
+| Server | `OVK_HOST`, `OVK_PORT`, `OVK_DATA_DIR`, `OVK_JOBS_DIR`, `OVK_TEMPLATES_SLIDES_DIR`, `OVK_STATIC_DIR`, `OVK_ASSETS_BASE_URL`, `OVK_MAX_CONCURRENT_RENDERS`, `OVK_RENDER_HF_WORKERS`, `OVK_TTS_WORKERS`, `OVK_TEMPLATES_AUTO_RENDER` | `config.py` |
+| AI (LangGraph agent) | `OPENAI_BASE_URL`, `OPENAI_API_KEY` (required for AI), `OVK_AI_MODEL` (default `gpt-5.4-nano`), `OVK_AI_TIER2_MODEL`, `OVK_AI_TEMPERATURE`, `OVK_AI_MAX_STEPS`, `OVK_AI_REASONING_EFFORT` (low/medium/high; reasoning models only), `OVK_ENABLE_WEB` | `ai/config.py` (see `docs/ai.md`) |
+| AI monitoring | `OVK_AI_MONITORING` (default `true` during dev), `OVK_AI_MONITORING_SINKS` (default `file`), `OVK_AI_MONITORING_TOOL_LIMIT` (default `8000`) | `ai/monitor/config.py` (see `docs/ai-monitoring.md`) |
+| MCP | `OVK_MCP_ENABLED` (default `true`), `OVK_MCP_TOKEN` (reserved for future auth) | `config.py` (see `docs/mcp.md`) |
+| Frontend (Vite) | `VITE_API_BASE_URL` | `ovk-web/src/shared/config.ts` |
+
+Config sources resolve in priority order: **real env vars > `.env` at repo root > `~/.openvideokit/config.toml` > hardcoded defaults**. The TOML file is auto-created on first `ovk serve` (chmod 600, secrets safe) and pre-fills values from existing `.env` so users migrating don't lose settings. See [`docs/config.md`](docs/config.md) for the full philosophy and `ovk config init/get/set/edit/path` CLI commands.
+
+`OPENAI_BASE_URL`/`OPENAI_API_KEY` accept any OpenAI-compatible endpoint
+(OpenAI, OpenRouter `https://openrouter.ai/api/v1`, Ollama
+`http://localhost:11434/v1`, vLLM, LM Studio).
+
+## Commands
+
+| Task | Command |
+|---|---|
+| Run server | `uv run openvideokit` (alias: `uv run ovk serve`) |
+| Init user config | `uv run ovk config init` (writes `~/.openvideokit/config.toml`, chmod 600) |
+| Edit user config | `uv run ovk config edit` (opens `$EDITOR`) |
+| Read a config value | `uv run ovk config get server.port` |
+| Set a config value | `uv run ovk config set server.port 9000` |
+| Lint | `uv run ruff check src scripts` |
+| Lint + fix | `uv run ruff check --fix src scripts` |
+| Unit tests (fast, no render) | `uv run pytest tests/` |
+| Unit tests (all incl. render) | `uv run pytest tests/ --run-slow` |
+| E2E smoke test | `uv run --extra dev python scripts/test-e2e.py` |
+| Full pipeline test | `uv run --extra dev python scripts/test-e2e.py --render` |
+| Standalone voiceover gen | `uv run python scripts/generate_voiceover.py --template eco-bottle --bake` |
+| Render a template | `npx hyperframes render templates/eco-bottle --output out.mp4` |
+| Validate a template | `npx hyperframes lint templates/eco-bottle` |
+
+## Code style (indentation — critical)
+
+**Always use spaces, never tabs, in every file in this repo.**
+
+| Area | Indent | Enforced by |
+|---|---|---|
+| Python (`src/`, `scripts/`) | **4 spaces** | `ruff format` (`W191` rejects tabs; mixed tabs/spaces → `SyntaxError`) |
+| ovk-web (TS/TSX) | **2 spaces** | Biome (`indentStyle: "space"`, `indentWidth: 2`) |
+
+Tabs in Python break the build immediately (`W191` / `unindent does not match any outer indentation level`). When creating or editing a file, write every indented line with the correct number of spaces. Run the formatter before committing (`uv run ruff format` / `pnpm exec biome format --write`).
+
+### File writes — ALWAYS atomic
+
+**Never use `Path.write_text()` or `open().write()` directly for data files.** Use `store._atomic_write(path, data)` instead:
+
+```python
+from .store import _atomic_write
+
+# CORRECT — temp file + rename, crash-safe
+_atomic_write(path, json.dumps(data))
+
+# WRONG — half-written file on crash
+path.write_text(data)
+```
+
+`_atomic_write` writes to a `.tmp` file first, then `rename()`s it over the target. On POSIX, `rename` is atomic — readers either see the old or new file, never a partial write. This prevents corruption when the server crashes mid-write or when the file watcher reads a half-written file.
+
+## Module responsibilities
+
+| Module | Owns | Key functions |
+|---|---|---|
+| `config.py` | Paths, env vars, `JOBS` registry | `ensure_data_dirs()` |
+| `app.py` | FastAPI routes (thin) + MCP mount | `create_app()` |
+| `validation.py` | Identifier regex gates (path-safety) | `validate_project_id()`, `validate_slide_id()` |
+| `templating.py` | Schema I/O, Jinja2 stamping, HTML page generators | `stamp_session()`, `render_editor_page()`, `render_player_page()` |
+| `voiceover.py` | edge-tts pipeline: TTS + silence + concat + timings | `generate_voiceover()`, `generate_voiceover_smart()` |
+| `captions.py` | Word-level karaoke captions + scene transitions | `build_captions()`, `build_caption_timeline_js()`, `build_scene_transitions_js()` |
+| `rendering.py` | `npx hyperframes render` subprocess + job tracking | `start_render()`, `get_job()` |
+| `mcp/apply_op.py` | Pure EditOp reducer (port of ovk-web applyOp.ts) | `apply_op()`, `inverse_op()`, `fold_ops()` |
+| `mcp/persist.py` | Execute-on-call engine: fold ops + persist + TTS | `apply_ops()` |
+| `mcp/server.py` | FastMCP server wrapping 26 ai/tools/* + list_projects + create_project | `create_server()` |
+
+## Path safety & identifier validation — critical
+
+Every filesystem path under `OVK_DATA_DIR` is built by string-concatenating a `project_id`, `slide_id`, `audio_hash`, asset sha, `chat_id`, or `job_id` into a `Path(...)`. These identifiers arrive from **untrusted sources**: HTTP path params, JSON bodies, LangGraph tool args, and (soon) MCP tool args. A single `..`, `/`, `\`, or null byte escapes the sandbox.
+
+### The contract — validated AT the path helper, not just at the route
+
+The regex gate lives in `src/openvideokit/validation.py` and is enforced **inside** the path helpers themselves, so no caller can bypass it:
+
+```python
+# store.py — gate fires here, regardless of caller
+def _project_dir(project_id: str) -> Path:
+    validate_project_id(project_id)            # ← raises ValueError
+    return _DATA_PATH / project_id
+
+def _slide_dir(project_id: str, slide_id: str) -> Path:
+    return _slides_dir(project_id) / validate_slide_id(slide_id)
+```
+
+Same pattern in `chats._chats_dir`, `rendering._jobs_meta_path`, `rendering._job_dir`, `assets._blob_path`, `assets._meta_path`, `templates._template_dir`, `ai/context.OVKContext.project_dir`, `ai/monitor/sinks._contexts_dir`. Every one calls a `validate_*` before concat.
+
+Routes layer (`routes.py:_valid_*`) translate `ValueError → HTTPException(400)` for clean client errors; the underlying gate is the validator, not the route.
+
+### Identifier regexes
+
+| Identifier | Regex | Used in |
+|---|---|---|
+| `project_id` | `^[a-z0-9][a-z0-9-]*$` | directory name |
+| `slide_id` | `^[A-Za-z0-9_-]+$` | directory name under `slides/` |
+| `audio_hash` | `^[a-f0-9]+$` | `audio-<hash>.mp3` filename |
+| `asset sha` | `^[a-f0-9]{64}(\.[A-Za-z0-9]+)?$` | blob filename + optional `.<ext>` |
+| `template segment` | `^[a-z0-9][a-z0-9-]*$` | author/name dir under templates |
+| `chat_id` | `^[A-Za-z0-9_-]+$` | `<id>.jsonl` filename |
+| `job_id` | `^[A-Za-z0-9_-]+$` | directory under `jobs/` |
+
+All anchored `^...$`. Reject `..`, separators, whitespace, null bytes, percent-encoding.
+
+### When adding a new path helper
+
+1. **Never** do `_DATA_PATH / user_input` without validating first. Call the matching `validate_*` from `validation.py`.
+2. If the identifier is new (not in the table above), add a regex + `validate_*` to `validation.py` first.
+3. Reuse existing helpers where possible — `store._project_dir(id)` is preferred over `Path(DATA_DIR) / id` because it's already gated.
+4. The `resolve() + relative_to(base)` check in read tools (`read_file`, `tree`, `list_files`) is **defense-in-depth, not the primary gate** — it cannot detect a bad `project_id` because `base` itself is already wrong by that point. The regex gate fires first.
+
+### Tampered-disk robustness
+
+`list_projects`, `init_store`, and `_scan_disk` iterate `DATA_DIR` and may encounter malformed dir names (manual tampering / legacy data). They use `store._safe_load(name, loader)` which swallows `ValueError` and skips the entry rather than crashing the whole scan. `_load_from_disk` likewise skips slide ids in `project.json.slides[]` that fail the validator.
+
+### Tests
+
+- `tests/test_validation.py` — pins every validator + every path helper with the full traversal vector set (`..`, `/`, `\`, null bytes, percent-encoding, etc.) AND the tampered-disk graceful-skip behavior.
+- `tests/test_projects_routes.py::TestPathTraversal` — route-level 4xx behavior (client-visible).
+
+## Layout field types
+
+Layout `fields` in `template.json` support these types:
+
+| Type | Form control | What happens on submit |
+|---|---|---|
+| `text` | `<textarea>` | `__FIELD_ID__` placeholder replacement in layout HTML |
+| `image` | `<input type="file">` | Byte swap to `assets/`, `__FIELD_ID__` path replacement |
+| `voiceover` | `<textarea>` (amber styled) | **Batch TTS pipeline** — see below |
+
+### Slot extras
+
+- **`priority`**: Template-level field in `template.json`. Higher number = higher on home page (default 0, sorted alphabetically after prioritized ones).
+- **`caption_style`**: Template-level field. Controls caption CSS: `highlight`, `neon`, `editorial`, `eco-green`.
+- **`default_slides`**: Pre-fills the editor with slides and their default content.
+
+## Voiceover pipeline
+
+When a template has `voiceover` slots, `stamp_session()` batches ALL of them into one TTS run (edge-tts → ffprobe → ffmpeg concat → `voiceover.mp3` + captions). See **[docs/tts.md](docs/tts.md)** for the full pipeline, voice catalog, default voice policy, and cache layers.
+
+## Caption styling — CRITICAL RULES
+
+**Never use `transform`, `scale()`, `font-size`, or `text-shadow` changes on `.word--active`.** These cause visual layout shifts ("jumping") that look broken.
+
+### The correct caption pattern
+
+Caption highlighting uses **GSAP direct color tween** (not CSS class toggling):
+
+```javascript
+// CORRECT — smooth color tween, zero layout shift
+tl.to(wordSelector, { color: '#ffea00', duration: 0.15, ease: 'power2.out' }, wordStart);
+tl.to(wordSelector, { color: 'rgba(255,255,255,0.4)', duration: 0.15, ease: 'power2.in' }, wordEnd);
+```
+
+```css
+/* CORRECT — base word style */
+.caption-phrase .word {
+  display: inline-block;
+  font-size: 48px; font-weight: 800;
+  color: rgba(255, 255, 255, 0.4);   /* dim white default */
+  margin: 0 0.1em;
+  text-shadow: 0 4px 20px rgba(0, 0, 0, 0.8);
+  transition: color 0.2s ease;        /* smooth fallback */
+}
+
+/* CORRECT — emphasis (keyword highlight, static, no animation) */
+.caption-phrase .word--emphasis { color: #4ade80; }
+
+/* CORRECT — active state is ONLY a color change */
+.caption-phrase .word--active { color: #ffea00; }
+```
+
+### What NOT to do
+
+```css
+/* WRONG — causes layout shift / size jumping */
+.caption-phrase .word--active {
+  transform: scale(1.15);                          /* ← BANNED */
+  font-size: 56px;                                 /* ← BANNED */
+  text-shadow: 0 0 30px rgba(255,234,0,0.6);      /* ← BANNED (causes repaint jumps) */
+}
+
+/* WRONG — GSAP className toggle snaps instantly, doesn't animate */
+tl.to(word, { className: '+=word--active', duration: 0.05 }, start);
+```
+
+### Why `className` toggle is banned
+
+GSAP's `className` plugin reads computed styles before/after the class change and tweens the diff. This sounds smooth but in practice:
+- It can pick up unintended CSS property changes and animate them
+- The `duration: 0.05` is too short to be visible, making it an instant snap
+- It conflicts with CSS `transition` on the same element
+
+**Always use direct property tweens** (`color`, `opacity`) for word highlighting.
+
+## Sub-composition model (ALL templates)
+
+ALL templates use `"mode": "slide-editor"` with HF's `data-composition-src` to embed slides as separate files. There is no flat model.
+
+### Template structure
+
+```
+templates/my-template/
+├── template.json          ← slide-editor config (mode, layouts, default_slides)
+├── index.html             ← root shell (audio + slide host divs + timeline markers)
+├── layouts/               ← sub-composition layout files
+│   └── my-layout.html     ← bare <template> with __PLACEHOLDER__ markers
+└── assets/                ← images, audio, fonts
+```
+
+### Layout file format — CRITICAL
+
+Layout files MUST be bare `<template>` — **no `<html>` wrapper, no `<body>`, no `data-composition-variables`**.
+
+```html
+<template>
+  <div data-composition-id="__SLIDE_ID__" data-width="1920" data-height="1080">
+    <div class="content">
+      <h1>__TITLE__</h1>
+      <p>__BODY__</p>
+    </div>
+    <style>
+      [data-composition-id="__SLIDE_ID__"] { background: #0a0a14; }
+      [data-composition-id="__SLIDE_ID__"] .content {
+        text-align: center;
+        padding-top: 38vh;
+      }
+      [data-composition-id="__SLIDE_ID__"] h1 { font-size: 120px; ... }
+    </style>
+    <script>
+      var tl = gsap.timeline({ paused: true });
+      tl.from('[data-composition-id="__SLIDE_ID__"] .content > *', { opacity: 0, y: 40, duration: 0.4, stagger: 0.1 });
+      window.__timelines['__SLIDE_ID__'] = tl;
+    </script>
+  </div>
+</template>
+```
+
+### Why bare `<template>` (no `<html>` wrapper)
+
+HF's runtime extracts `<template>` content and mounts it. An `<html>` wrapper around `<template>` causes HF to NOT extract the content — the sub-comp renders blank. Verified in HF v0.7.3.
+
+### Why NOT `data-variable-values` / `getVariables()`
+
+HF's `getVariables()` returns empty `{}` in v0.7.3 sub-compositions. Values are stamped directly into the HTML via `__PLACEHOLDER__` string replacement at stamp time.
+
+### Why NOT flex/absolute centering
+
+HF's sub-comp mounting context doesn't reliably support `display:flex; align-items:center` or `position:absolute; transform:translate(-50%,-50%)`. Use the official HF pattern: `text-align: center` + `padding-top: XXvh` for vertical positioning. The `vh` unit is viewport-relative and works for any video size.
+
+### Placeholder convention
+
+- `__SLIDE_ID__` → replaced with `slide-0`, `slide-1`, etc.
+- `__TITLE__` → replaced with user's title text
+- `__BODY__` → replaced with user's body text
+- `__IMAGE__` → replaced with image path (if layout has image field)
+- `__STEP__` → replaced with step number (timeline-step layout)
+
+Each field ID is uppercased: field `title` → `__TITLE__`, field `body` → `__BODY__`.
+
+### Host div format
+
+```html
+<div data-composition-id="slide-0"
+     data-composition-src="compositions/slide-0.html"
+     data-start="0.5" data-duration="5.0"
+     class="clip" style="position:absolute;inset:0;z-index:100;"></div>
+```
+
+Key rules:
+- `position:absolute;inset:0;` is REQUIRED on the host div — without it, sub-comp content collapses to zero size
+- `z-index:100-idx` initially — first slide on top, root timeline swaps z-index at each slide start
+- `class="clip"` for HF's visibility management
+
+### Template JSON schema
+
+```json
+{
+  "id": "my-template",
+  "name": "Display Name",
+  "description": "Shown on home page + editor.",
+  "duration": 30.0,
+  "priority": 50,
+  "mode": "slide-editor",
+  "caption_style": "highlight",
+  "layouts": [
+    {
+      "id": "my-layout",
+      "name": "Layout Name",
+      "fields": [
+        {"id": "title", "type": "text", "label": "Title", "default": "Hello"},
+        {"id": "body", "type": "text", "label": "Body", "default": "World"},
+        {"id": "voice", "type": "voiceover", "label": "Voiceover", "default": ""}
+      ]
+    }
+  ],
+  "default_slides": [
+    {"layout": "my-layout", "title": "Slide 1", "body": "Content", "voice": "Narration text."}
+  ],
+  "slots": []
+}
+```
+
+### Root index.html markers
+
+Place these in `index.html` — `_stamp_slides()` replaces them:
+
+```html
+<!-- SLIDES_HERE -->     → host divs with data-composition-src
+<!-- CAPTION_LAYER -->   → caption HTML (word spans)
+/* CAPTION_CSS */        → caption CSS (style determined by caption_style)
+// SCENE_TRANSITIONS     → GSAP z-index swap JS
+// CAPTION_TIMELINE      → GSAP word-by-word highlight JS
+```
+
+### Debugging with HF tools
+
+```bash
+# Check for layout issues (text occlusion, overlap, positioning)
+npx hyperframes inspect sessions/<session_id> --at 2
+
+# Capture visual frames for verification
+npx hyperframes snapshot sessions/<session_id> --at 2,5,8 --output snapshots/
+```
+
+## Preview audio
+
+The preview page (`render_player_page()`) uses external `<audio>` elements synced to the HyperFrames player via event listeners. This bypasses the player's internal muting.
+
+- `ext-music`: music-bed, looped, volume 0.08
+- `ext-voiceover`: voiceover track (if `assets/voiceover.mp3` exists), volume 1.0, not looped
+
+Both sync to `_player.currentTime` via `timeupdate` events.
+
+## Common pitfalls
+
+1. **Never bypass the identifier validators**: Don't write `Path(DATA_DIR) / project_id` directly — `project_id` is untrusted and could be `..`. Always go through `store._project_dir(id)` / `store._slide_dir(pid, sid)` / `chats._chats_dir(id)`, or call `validate_*` from `validation.py` first. The regex gate fires inside the path helpers; bypassing it re-opens path traversal. See "Path safety & identifier validation" above.
+2. **edge-tts voice IDs need `Neural` suffix**: Use `vi-VN-HoaiMyNeural`, NOT `vi-VN-HoaiMy`. Default voice is `en-US-AvaMultilingualNeural` (multilingual). See [docs/tts.md](docs/tts.md).
+3. **asyncio.run() in FastAPI**: Must use thread-based wrapper (`tts_sentence_sync` in `voiceover.py`). Calling `asyncio.run()` directly inside a FastAPI route crashes with `RuntimeError`.
+4. **Google Fonts lint error**: All templates trigger `google_fonts_import` error from HF lint. Pre-existing issue, non-blocking. Use `--strict` only if you've switched to local `@font-face`.
+5. **`shutil.copytree` duplicates everything**: Every form submission copies the entire template dir. Keep templates small or add a session janitor.
+6. **Stamping: never use the string form of `replaceAll`/`replace`**: JavaScript's `String.prototype.replaceAll(token, replacement)` with a **string** replacement interprets `$&` (the matched substring), `$$`, `` $` ``, and `$'` — so a field/slide value containing any of those silently corrupts the stamped output. Always use the **function form** `replaceAll(token, () => value)`, which inserts the value literally. In `ovk-web` this is `stampSafe` (`shared/lib/placeholders.ts`); `stampNaive` (the string form) is kept only as a pinned negative test. Python's `str.replace` is literal (no `$` interpretation) and safe, but always `html_escape` values first.
+7. **SVG validation**: Always validate SVGs as XML before committing. Broken SVGs (duplicate attributes, unclosed tags) silently fail to render in Chrome. Run: `python3 -c "import xml.etree.ElementTree as ET; ET.parse('file.svg')"`.
+8. **Form submit sync**: The slide editor intercepts form submit and reads all textarea values from the DOM via `data-field` attributes. The `syncFromDOM()` function must run before any re-render (add/remove/reorder) to avoid losing typed values.

openvideokit-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: openvideokit
+Version: 0.1.0
+Summary: Deterministic video templating pipeline — form-driven, minimal LLM, HyperFrames underneath.
+Requires-Python: >=3.13
+Requires-Dist: crawl4ai>=0.9
+Requires-Dist: ddgs>=8.0
+Requires-Dist: edge-tts>=6.1.0
+Requires-Dist: fastapi>=0.138.0
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langchain-openai>=0.3
+Requires-Dist: langchain>=0.3
+Requires-Dist: langgraph>=0.4
+Requires-Dist: lxml-html-clean>=0.4.4
+Requires-Dist: nh3>=0.3.6
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: uvicorn[standard]>=0.49.0
+Requires-Dist: watchdog>=6.0.0
+Provides-Extra: dev
+Requires-Dist: requests>=2.32; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'