@lalalic/markcut 2.2.8 → 2.3.0

package/src/vision/cli.mjs

@@ -20,11 +20,7 @@
  *      f) Save complete metadata.json with metadata + userHint + perception
  *
  * Options:
- *   --label            Run full pipeline: preview → label → normalize → percept → segments
- *   --agent <tmpl>     Custom text LLM CLI for detect-scenes ({prompt})
- *   --itt <tmpl>       Custom ITT CLI template with {input}, {prompt}
- *   --vtt <tmpl>       Custom VTT CLI template with {input}, {prompt}
- *   --stt <tmpl>       Custom STT CLI template with {input}, {output}
+ *   --label            Open label preview → then continue with full AI pipeline
  *   --prompts-file <path> Path to prompts markdown file (default: vision_prompts.md)
  *   --vtt-sample-interval <n> Sample one video frame every N seconds (default: 5)
  *   --context "text"   Background context about people/places (injected into prompts)
@@ -32,7 +28,6 @@
  *   --skip-stt         Skip speech-to-text for videos
  *   --dry-run          Show what would be processed without running AI
  *   --show-prompts     Print the prompts file and exit
- *   --show-clis        Print the default ITT/VTT/STT CLI templates
  *   --help             Show this help
  *
  * Prompt overrides:
@@ -716,13 +711,13 @@ function mergeLabelsIntoMetadata(folder, metadata) {
 
 // ── Perception helpers ────────────────────────────────────────────────────
 
-function analyzeImage(imagePath, normPath, prompts, ittCli, context = "", userHint = "", userHints = null) {
+function analyzeImage(imagePath, normPath, prompts, context = "", userHint = "", userHints = null) {
   let ctxParts = [];
   if (context) ctxParts.push(`Context: ${context}`);
   if (userHint) ctxParts.push(`User hint: ${userHint}`);
   const ctx = ctxParts.length > 0 ? ctxParts.join("\n") + "\n\n" : "";
   const prompt = ctx + getPrompt(prompts, "image-perception");
-  const raw = runITT(normPath, prompt, ittCli);
+  const raw = runITT(normPath, prompt, DEFAULT_ITT_CLI);
   const parsed = looseJSONParse(raw);
   const rawText = stripThinkBlocks(extractRawText(raw));
   return normalizePerception({
@@ -790,7 +785,7 @@ function buildMergedCues(userHint, cues, sceneChangesMs, totalDurationMs) {
   return merged;
 }
 
-function analyzeVideo(videoPath, normInfo, normDir, prompts, vttCli, sttCli, context = "", userHint = "", ittCli = null, sampleInterval = DEFAULT_VTT_SAMPLE_INTERVAL, agentCli = null, userHints = null) {
+function analyzeVideo(videoPath, normInfo, normDir, prompts, context = "", userHint = "", sampleInterval = DEFAULT_VTT_SAMPLE_INTERVAL, userHints = null) {
   let ctxParts = [];
   if (context) ctxParts.push(`Context: ${context}`);
   if (userHint && typeof userHint === "string") ctxParts.push(`User hint: ${userHint}`);
@@ -800,13 +795,13 @@ function analyzeVideo(videoPath, normInfo, normDir, prompts, vttCli, sttCli, con
   // 1. VTT → overall video description
   emitInfo(`  Running video understanding...`);
   const descPrompt = ctx + getPrompt(prompts, "video-perception");
-  const descRaw = runVTT(normInfo.path, descPrompt, vttCli, ittCli, sampleInterval);
+  const descRaw = runVTT(normInfo.path, descPrompt, DEFAULT_VTT_CLI, DEFAULT_ITT_CLI, sampleInterval);
   const descText = stripThinkBlocks(extractRawText(descRaw));
   perception.desc = descText.slice(0, 500) || looseJSONParse(descRaw)?.desc || descRaw.slice(0, 500);
 
   // 2. STT → VTT subtitle
   emitInfo(`  Running speech-to-text...`);
-  perception.subtitle = runSTT(videoPath, normDir, sttCli);
+  perception.subtitle = runSTT(videoPath, normDir, DEFAULT_STT_CLI);
 
   // 3. Build merged cue timeline from VTT + user hints + ffprobe
   emitInfo(`  Building merged segment boundaries...`);
@@ -843,7 +838,7 @@ function analyzeVideo(videoPath, normInfo, normDir, prompts, vttCli, sttCli, con
     if (!existsSync(dummyInput)) {
       writeFileSync(dummyInput, Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "base64"));
     }
-    const segRaw = runAgent(dummyInput, `${segPrompt}\n\nInput:\n${segInput}`, agentCli || ittCli);
+    const segRaw = runAgent(dummyInput, `${segPrompt}\n\nInput:\n${segInput}`, DEFAULT_AGENT_CLI || DEFAULT_ITT_CLI);
     const segParsed = looseJSONParse(segRaw);
 
     if (segParsed && typeof segParsed === "object" && Object.keys(segParsed).length > 0) {
@@ -903,7 +898,7 @@ function analyzeVideo(videoPath, normInfo, normDir, prompts, vttCli, sttCli, con
       } else { clipPath = clipOut; }
 
       // Use runVTT for video clips (extracts frames, then runs ITT)
-      const segRawVis = runVTT(clipPath, visSegPrompt, vttCli, ittCli, sampleInterval);
+      const segRawVis = runVTT(clipPath, visSegPrompt, DEFAULT_VTT_CLI, DEFAULT_ITT_CLI, sampleInterval);
       const segVisText = extractRawText(segRawVis);
       seg.vision = stripThinkBlocks(looseJSONParse(segRawVis)?.desc || segVisText.slice(0, 300) || segRawVis.slice(0, 300));
       try { if (clipPath !== normInfo.path) rmSync(clipPath, { force: true }); } catch {}
@@ -917,7 +912,7 @@ function analyzeVideo(videoPath, normInfo, normDir, prompts, vttCli, sttCli, con
 
 // ── Full pipeline runner (step 2: label → normalize → percept → segments) ──
 
-async function runFullPipeline(folder, prompts, ittCli, vttCli, sttCli, context, pickSet, vttSampleInterval, skipSTT, dryRun, agentCli = null) {
+async function runFullPipeline(folder, prompts, context, pickSet, vttSampleInterval, skipSTT, dryRun) {
   const metadataPath = join(folder, "metadata.json");
 
   // ── Ensure metadata exists ──────────────────────────────────────────
@@ -987,12 +982,12 @@ async function runFullPipeline(folder, prompts, ittCli, vttCli, sttCli, context,
     return;
   }
 
-  await runNormalizeAndPercept(folder, metadataPath, prompts, ittCli, vttCli, sttCli, context, pickSet, vttSampleInterval, skipSTT, agentCli);
+  await runNormalizeAndPercept(folder, metadataPath, prompts, context, pickSet, vttSampleInterval, skipSTT);
 }
 
 // ── Normalize + Percept (internal step) ───────────────────────────────────
 
-async function runNormalizeAndPercept(folder, metadataPath, prompts, ittCli, vttCli, sttCli, context, pickSet, vttSampleInterval, skipSTT, agentCli = null) {
+async function runNormalizeAndPercept(folder, metadataPath, prompts, context, pickSet, vttSampleInterval, skipSTT) {
   const { results, cacheMap } = loadMetadata(folder);
   const cache = { ...cacheMap };
   const normDir = join(folder, ".normalized");
@@ -1022,14 +1017,14 @@ async function runNormalizeAndPercept(folder, metadataPath, prompts, ittCli, vtt
     let cacheKey = "";
     const ctx = context ? `Context: ${context}\n\n` : "";
     const imgPrompt = (userHint ? `User hint: ${userHint}\n\n` : "") + ctx + getPrompt(prompts, "image-perception");
-    const imgInput = `${ittCli ? "" : "@"}${shQuote(normPath)}`;
-    const imgCmd = substituteTemplate(ittCli || DEFAULT_ITT_CLI, { input: imgInput, prompt: imgPrompt });
+    const imgInput = `@${shQuote(normPath)}`;
+    const imgCmd = substituteTemplate(DEFAULT_ITT_CLI, { input: imgInput, prompt: imgPrompt });
     cacheKey = perceptionCacheKey(imgPath, imgCmd, "image");
     if (cache[cacheKey]) {
       perception = cache[cacheKey];
       emitInfo(`  (cached)`);
     } else {
-      perception = analyzeImage(imgPath, normPath, prompts, ittCli, context, userHint, userHints);
+      perception = analyzeImage(imgPath, normPath, prompts, context, userHint, userHints);
       if (perception.desc) cache[cacheKey] = perception;
       emitInfo(`  ${perception.desc?.slice(0, 80)}...`);
     }
@@ -1057,27 +1052,25 @@ async function runNormalizeAndPercept(folder, metadataPath, prompts, ittCli, vtt
     emitInfo(`\n🎬 Video: ${base}${userHint ? ` (hint: "${userHint}")` : ""}`);
     const vidPath = join(folder, fileName);
     const normInfo = normalizeVideo(vidPath, normDir, meta.duration);
-    const stt = skipSTT ? null : sttCli;
-
     let perception = {};
     let cacheKey = "";
     const ctxV = context ? `Context: ${context}\n\n` : "";
     const vidPrompt = (userHint ? `User hint: ${userHint}\n\n` : "") + ctxV + getPrompt(prompts, "video-perception");
     let vttActualCmd;
-    if (vttCli) {
-      vttActualCmd = substituteTemplate(vttCli, { input: shQuote(normInfo.path), prompt: vidPrompt });
+    if (DEFAULT_VTT_CLI) {
+      vttActualCmd = substituteTemplate(DEFAULT_VTT_CLI, { input: shQuote(normInfo.path), prompt: vidPrompt });
     } else {
       const dur = meta.duration || 0;
       const n = Math.max(5, Math.min(10, Math.ceil(dur / vttSampleInterval)));
       const framePaths = Array.from({ length: n }, (_, i) => `${basename(normInfo.path, extname(normInfo.path))}_${String(i + 1).padStart(3, "0")}.jpg`);
-      vttActualCmd = substituteTemplate(ittCli || DEFAULT_ITT_CLI, { input: framePaths.map(p => `@${p}`).join(" "), prompt: vidPrompt });
+      vttActualCmd = substituteTemplate(DEFAULT_ITT_CLI, { input: framePaths.map(p => `@${p}`).join(" "), prompt: vidPrompt });
     }
     cacheKey = perceptionCacheKey(vidPath, vttActualCmd, "video");
     if (cache[cacheKey]) {
       perception = cache[cacheKey];
       emitInfo(`  (cached)`);
     } else {
-      perception = analyzeVideo(vidPath, normInfo, normDir, prompts, vttCli, stt, context, userHint, ittCli, vttSampleInterval, agentCli, userHints);
+      perception = analyzeVideo(vidPath, normInfo, normDir, prompts, context, userHint, vttSampleInterval, userHints);
       if (perception.desc) cache[cacheKey] = perception;
     }
 
@@ -1105,10 +1098,6 @@ Usage:
 
 Options:
   --label              Open label preview → then continue with full AI pipeline
-  --agent <template>   Custom text LLM CLI for detect-scenes ({prompt})
-  --itt <template>     Custom ITT CLI template with {input}, {prompt}
-  --vtt <template>     Custom VTT CLI template with {input}, {prompt}
-  --stt <template>     Custom STT CLI template with {input}, {output}
   --prompts-file <path> Path to prompts markdown file (default: vision_prompts.md)
   --vtt-sample-interval <n> Sample one video frame every N seconds (default: 5)
   --context "text"     Background context about people/places (injected into prompts)
@@ -1116,7 +1105,6 @@ Options:
   --skip-stt           Skip speech-to-text for videos
   --dry-run            Show what would be processed without running AI
   --show-prompts       Print the prompts file and exit
-  --show-clis          Print the default ITT/VTT/STT CLI templates
   --help               Show this help
 
 Prompt overrides:
@@ -1126,10 +1114,6 @@ Prompt overrides:
 
 export async function main(args) {
   let folder = "";
-  let agentCli = null;
-  let ittCli = null;
-  let vttCli = null;
-  let sttCli = null;
   let promptsFile = PROMPTS_FILE;
   let context = "";
   let vttSampleInterval = DEFAULT_VTT_SAMPLE_INTERVAL;
@@ -1147,20 +1131,12 @@ export async function main(args) {
     const flag = args[i++];
     if (flag === "--help") { printUsage(); return; }
     else if (flag === "--label") { doLabel = true; }
-    else if (flag === "--agent" && args[i]) { agentCli = args[i++]; }
-    else if (flag === "--itt" && args[i]) { ittCli = args[i++]; }
-    else if (flag === "--vtt" && args[i]) { vttCli = args[i++]; }
-    else if (flag === "--stt" && args[i]) { sttCli = args[i++]; }
+
     else if (flag === "--prompts-file" && args[i]) { promptsFile = resolve(args[i++]); }
     else if (flag === "--vtt-sample-interval" && args[i]) { vttSampleInterval = parseInt(args[i++], 10) || DEFAULT_VTT_SAMPLE_INTERVAL; }
     else if (flag === "--context" && args[i]) { context = args[i++]; }
     else if (flag === "--show-prompts") { console.log(readFileSync(promptsFile, "utf-8")); return; }
-    else if (flag === "--show-clis") {
-      console.log(`DEFAULT_ITT_CLI:\n${DEFAULT_ITT_CLI}\n`);
-      console.log(`DEFAULT_VTT_CLI: (empty — uses ITT via frame extraction, sample every ${DEFAULT_VTT_SAMPLE_INTERVAL}s)\n`);
-      console.log(`DEFAULT_STT_CLI:\n${DEFAULT_STT_CLI}`);
-      return;
-    }
+
     else if (flag === "--skip-stt") { skipSTT = true; }
     else if (flag === "--pick" && args[i]) { for (const f of args[i++].split(",")) pickSet.add(f.trim()); }
     else if (flag === "--dry-run") { dryRun = true; }
@@ -1175,7 +1151,7 @@ export async function main(args) {
   for (const [name, value] of promptOverrides) prompts.set(name, value);
 
   if (doLabel) {
-    await runFullPipeline(folder, prompts, ittCli, vttCli, sttCli, context, pickSet, vttSampleInterval, skipSTT, dryRun, agentCli);
+    await runFullPipeline(folder, prompts, context, pickSet, vttSampleInterval, skipSTT, dryRun);
   } else {
     await runMetadataMode(folder, pickSet, dryRun);
   }

package/skills/markcut/docs/edit-mode.md

@@ -1,220 +0,0 @@
-# Watch Mode
-
-> `preview <file.md> --edit` — live editing loop with AI-assisted JSON editing.
-
-Edit mode gives you a browser player that **automatically reloads** when the source file changes, plus an **edit input** that calls an AI coding agent (pi) to make changes on your behalf.
-
-Generated artifacts (TTS audio, compiled includes, component bundles) are
-stored under `.markcut/` next to the source file — see [SKILL.md](../SKILL.md) for the full layout.
-
-## Quickstart
-
-```bash
-cd remotion-engine
-npm run preview -- sample-visual.json --edit
-# → Browser opens, terminal blocks until you close it
-```
-
-## Architecture
-
-```
-┌─────────────┐     HTTP      ┌──────────────────┐    spawn     ┌──────────┐
-│   Browser   │◄──────────────►│  player/server   │◄────────────►│  pi CLI  │
-│  (Chrome)   │     SSE        │   .mjs (Node)    │  one-shot    │ (agent)  │
-└──────┬──────┘                └────────┬─────────┘              └──────────┘
-       │                                │
-       │  POST /api/edit                │  fs.watchFile
-       │  {text: "make text bigger"}    │  (poll every 500ms)
-       │                                │
-       │  GET /api/video-data           ▼
-       │  ← stream tree JSON    ┌──────────────┐
-       │                        │ stream tree  │
-       │  EventSource           │ .json (file) │
-       │  /api/events           └──────────────┘
-       │  ← {type:"reload"}           ▲
-       │                              │
-       │  window.dispatchEvent        │ pi edits
-       │  ("refresh-player")          │ this file
-       │                              │
-```
-
-## File: `src/player/server.mjs`
-
-### Server startup (`cli.mjs` → `server.mjs`)
-
-```
-node src/render/cli.mjs preview file.json --edit --port 3031
-```
-
-1. `cli.mjs` spawns `server.mjs` with `--edit` flag
-2. `server.mjs` parses `file.json` to build a recursive tree description
-3. Starts `fs.watchFile(file.json, {interval:500})` — polls every 500ms for changes
-4. Starts HTTP server on specified port
-5. Auto-opens browser via `open http://localhost:PORT`
-
-### Page served
-
-The HTML page loads two scripts:
-
-| Script | Source | Role |
-|--------|--------|------|
-| `player.js` | Bundled esbuild output from `src/player/browser.tsx` | Renders the stream tree using `@remotion/player` with `MarkCut` |
-| Inline script | Generated by `getHtml()` in `server.mjs` | Watch-mode UI controls (close button, edit input, SSE) |
-
-### Edit flow
-
-```
-Browser                          Server                          pi CLI
-  │                                │                              │
-  │── POST /api/edit ────────────► │                              │
-  │   {text: "make text bigger"}   │                              │
-  │                                │── spawn("pi", ["-p", prompt])│
-  │                                │   prompt includes:           │
-  │                                │   • full tree description   │
-  │                                │     (recursive, any depth)  │
-  │                                │   • edit history             │
-  │                                │   • knowledge (all stream   │
-  │                                │     types, components,      │
-  │                                │     schema, styling guide)  │
-  │                                │   • edit request             │
-  │                                │                              │
-  │                                │   pi can edit ANY field on  │
-  │                                │   ANY node in the tree      │
-  │                                │                              ├── edits file.json
-  │                                │                              └── exits
-  │                                │◄── exit code 0              │
-  │◄── {done:true, output:"..."} ──┤                              │
-  │                                │                              │
-  │ suppressReload = true          │                              │
-  │ header shows "Changed text..." │                              │
-  │                                │                              │
-  │  (fs.watchFile fires SSE       │                              │
-  │   but suppressReload=true      │                              │
-  │   so it's ignored)             │                              │
-  │                                │                              │
-  │ after 4s:                      │                              │
-  │ dispatchEvent("refresh-player")│                              │
-  │ → player re-fetches /api/data  │                              │
-  │ → re-renders with new JSON     │                              │
-```
-
-### Key design decisions
-
-**Why in-place refresh instead of `location.reload()`?**
-- Timeline playback continues uninterrupted
-- Status text persists until next edit
-- No page flash
-
-**Why `suppressReload`?**
-- SSE fires ~500ms after pi edits the file
-- API response arrives at the same time
-- `suppressReload` flag ignores the SSE event during edit
-- The client reloads itself after showing the summary
-
-## File: `src/player/browser.tsx`
-
-The bundled player app:
-
-1. Fetches `/api/video-data` on mount
-2. Renders the stream tree using `@remotion/player` with `MarkCut`
-3. Listens for `"refresh-player"` custom DOM event
-4. On refresh event: re-fetches data, re-renders in-place
-
-## File: `src/render/cli.mjs`
-
-The CLI routes `--edit` flag to the player server:
-
-```javascript
-if (args.edit) {
-  const serverArgs = ["src/player/server.mjs", file, "--edit", `--port=${port}`];
-  const child = spawn("node", serverArgs, { cwd: ROOT, stdio: "inherit" });
-  // ...blocks until server exits...
-}
-```
-
-## API Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/video-data` | GET | Returns the raw stream tree JSON file |
-| `/api/scenes` | GET | Returns parsed scenes array with timing |
-| `/api/video-info` | GET | Returns scenes + totalDuration + mode flags |
-| `/api/edit` | POST | Accepts `{text}` → spawns pi to edit the JSON → file watcher triggers → SSE reload |
-| `/api/shutdown` | POST | Kills the server process, unblocking the agent |
-| `/api/events` | GET | SSE stream — sends `{type:"reload"}` when file changes |
-| `/api/labels` | GET/POST | (label mode only) Save/load scene labels |
-
-## The pi prompt
-
-Each edit call sends a structured prompt with a **recursive tree description** instead of a flat scene list:
-
-```
-You are editing sample-visual.json, a Remotion stream tree JSON.
-
-The stream tree (indentation shows nesting; timing in seconds):
-  root "root" (1080×1920, 30fps, series, transition:fade)
-    folder "scene-1" (parallel)
-      component GradientBackground {type:"radial",animated:true,noise:true} [05s, bg]
-      component AnimatedHeadline {"text":"Hello Remotion",...} [0.54.5s]
-    folder "scene-2" (parallel)
-      component GradientBackground {type:"linear",animated:true} [05s, bg]
-      subtitle "This text is styled with CSS" fontSize:52 [0.54.5s]
-    ...
-
-Previous edits:
-1. make scene 1 headline text orange
-
-Edit request: make scene 1 headline text bigger
-
---- Knowledge ---
-You can edit ANY field on ANY node in the JSON...
-Stream types: root, folder, video, audio, image, subtitle, component, effect, rhythm, map
-...
-IMPORTANT: Read the full existing JSON file before editing. Only edit the JSON file. You can change, add, or remove any field on any node. Output ONLY a one-line summary of what specific change you made.
-```
-
-The tree description walks the JSON recursively, showing:
-- **Nesting depth** via indentation
-- **Type** and **id/name** of each node
-- **Key fields** (dimensions, fps, theme, series/parallel, transitions)
-- **Timing** from leaf span (`[start→end]`)
-- **isBackground** flag (`[bg]`)
-- **Component props** and node-specific fields (fontSize, fit, style, volume, etc.)
-
-This means pi can edit **any aspect of the JSON** ÔÇö not just scene props. Nested folders, effects, rhythms, maps, actions, styles, themes, global stylesheets, audio config ÔÇö everything is visible and editable.
-
-## Session context
-
-The server maintains `editHistory[]` — every edit is appended. On each call, previous edits are included so pi knows what was done before:
-
-```
-Previous edits:
-1. make scene 1 headline text orange
-2. change background from radial to linear gradient
-3. add 3D angle to device mockup in scene 4
-```
-
-This gives pi enough context to make coherent changes across multiple edit rounds.
-
-## Close / tab-close
-
-| Action | What happens |
-|--------|-------------|
-| Click **✕** | `sendBeacon("/api/shutdown")` → server exits → agent unblocks |
-| Close **tab** | SSE connection drops → 3s grace → server exits |
-| Close **browser** | Same as tab close |
-
-## Label mode (`--label`)
-
-`preview <file.json> --label` starts the same player but with a **label input** instead of the edit input. Labels are saved to `labels.json` next to the source file. No AI editing, no file watching.
-
-## Build
-
-The browser bundle is built with esbuild:
-
-```bash
-bash scripts/build-player.sh
-# → src/player/bundle/player.js
-```
-
-The bundle includes React, @remotion/player, MarkCut, all 13 built-in components, themes, templates, and the duration utility. It is served as a static file by the player server.

package/skills/markcut/docs/label-mode.md

@@ -1,112 +0,0 @@
-# Label System
-
-Interactive media labeling before understanding clips in json stream tree.
-The stream tree follow rules, see [docs/json-descriptive.md](docs/json-descriptive.md) for full details .
-
-## Overview
-
-The label player lets you load a stream tree, browse its clips, and attach descriptive labels to each clip's media. 
-The output is an updated `labels.json` file with `description` fields populated.
-
-## Usage
-
-```bash
-# Label from a stream tree JSON or labels.json
-npx markcut preview labels.json --label
-
-# Specify port
-npx markcut preview labels.json --label --port 3031
-```
-
-### Labels Persistence
-The stream tree follow rules, see [docs/json-descriptive.md](docs/json-descriptive.md) for full details .
-Labels are saved to the source file.
-
-```json
-{
-  "root": {
-    "id": "root",
-    "type": "root",
-    "children": [
-      {
-        "id": "scene-1",
-        "type": "folder",
-        "children": [
-          {
-            "id": "scene-1-media",
-            "type": "image",
-            "src": "/media/photo.jpg",
-            "start": 0, "end": 5,
-            "description": "Best group shot from the campfire"
-          }
-        ]
-      },
-      {
-        "id": "scene-2",
-        "type": "folder",
-        "children": [
-          {
-            "id": "scene-2-media",
-            "type": "video",
-            "src": "/media/clip.mp4",
-            "start": 0, "end": 5,
-            "description": "Sunset timelapse — use for intro"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-The `description` field on each media leaf node holds the label text.
-
-## Workflow
-
-```
-Stream tree JSON (labels.json)
-       │
-       ▼
-─── preview --label ───→ Browse & label clips
-       │                        │
-       │                        ▼
-       │                  Updated labels.json
-       │                        │
-       ▼                        ▼
-    Use in Storyboard ──────→ Assemble → Render
-```
-
-1. **Prepare** a stream tree JSON with scenes
-2. **Label** with `preview --label` to add descriptions to each scene
-3. **Export** labels are saved alongside the source file
-4. **Use** the labeled scenes in your storyboard or assembly workflow
-
-## API Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/video-data` | GET | Returns the raw stream tree JSON |
-| `/api/video-info` | GET | Returns scenes array with timing + totalDuration |
-| `/api/labels` | GET | Returns the current stream tree with descriptions |
-| `/api/labels` | POST | Saves updated descriptions ({descriptions: {index: "text"}}) |
-| `/api/shutdown` | POST | Kills the server |
-| `/api/events` | GET | SSE events (reload on file change) |
-
-## Implementation
-
-Source: `src/player/server.mjs` (unified server, use `--label` flag)
-UI controls: `src/player/components/LabelControls.tsx` (React component)
-
-- Built on Node.js `http` module (no Express dependency)
-- Serves bundled `player.js` (esbuild output from `src/player/browser.tsx`)
-- Labels saved atomically to disk on each POST
-- Supports stream tree JSON, descriptive JSON, and markdown input
-- React components in `src/player/components/` replace the old HTML-based `ui/` directory
-
-## Reference
-
-| Topic | Link |
-|-------|------|
-| Storyboard (video planning) | [storyboard.md](storyboard.md) |
-| Stream tree types | `SKILL.md` |
-| Dynamic components | [dynamic-components.md](dynamic-components.md) |