@lalalic/markcut 3.2.14 → 3.2.16

package/scripts/verify-mcp-preview.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// Real MCP stdio compile-and-release verification. No player manager or HTTP child.
+import {Client} from "@modelcontextprotocol/client";
+import {StdioClientTransport} from "@modelcontextprotocol/client/stdio";
+import {mkdtemp,writeFile,readFile,readdir,rm} from "node:fs/promises";
+import {tmpdir} from "node:os";
+import {join} from "node:path";
+import {execFileSync} from "node:child_process";
+import assert from "node:assert/strict";
+
+const run=await mkdtemp(join(tmpdir(),"markcut-static-e2e-"));
+const exportRoot=join(run,"export");
+const report={timestamp:new Date().toISOString(),checks:[]};
+let client;
+function processes(){
+ return execFileSync("ps",["-axo","pid,ppid,command"],{encoding:"utf8"}).split("\n")
+ .filter(x=>x.includes("src/mcp/managed-player.mjs")||
+   (x.includes("src/player/server.mjs")&&x.includes(".markcut-preview-")));
+}
+const before=processes();
+async function connect(){
+ const transport=new StdioClientTransport({
+  command:process.execPath,args:["src/mcp/server.mjs"],cwd:process.cwd(),
+  env:{...process.env,NEOY_PUBLIC_ORIGIN:"https://neoy.example.test",MARKCUT_EXPORT_ROOT:exportRoot}
+ });
+ client=new Client({name:"static-e2e",version:"1.0.0"});
+ await client.connect(transport);
+}
+async function preview(file){
+ const started=Date.now();
+ const response=await client.callTool({name:"markcut.preview",arguments:{path:file}});
+ if(response.isError)throw new Error(response.content?.[0]?.text||"preview failed");
+ const operation=response.structuredContent;
+ assert.ok(operation.operationId,"tool should return operation identity immediately");
+ assert.match(operation.operationUrl,/^https:\/\/neoy\.example\.test\/files\/_neoy\/markcut\/operations\/[a-f0-9-]{36}\.json$/);
+ assert.ok(Date.now()-started<3000,"the tool should not await compilation");
+ const statusFile=join(exportRoot,"operations",operation.operationId+".json");
+ for(let attempt=0;attempt<300;attempt++){
+  const status=JSON.parse(await readFile(statusFile,"utf8"));
+  if(status.state==="failed")throw new Error("Compiler failed: "+status.error);
+  if(status.state==="ready"){
+   const data=status.result;
+   assert.match(data.compiledUrl,/^https:\/\/neoy\.example\.test\/files\/_neoy\/markcut\/cache\/[a-f0-9]{64}\.json$/);
+   assert.ok(!data.previewUrl,"no local player process");
+   return data;
+  }
+  await new Promise(r=>setTimeout(r,100));
+ }
+ throw new Error("Compile worker did not finish within 30 seconds");
+}
+async function compiled(p){
+ return JSON.parse(await readFile(join(exportRoot,"cache",p.contentHash+".json"),"utf8"));
+}
+async function check(name,fn){
+ try {const detail=await fn();report.checks.push({name,status:"PASS",detail});}
+ catch(e){report.checks.push({name,status:"FAIL",error:String(e)});throw e;}
+}
+const md=(name)=>'# video\nwidth:640 height:480 fps:30 layout:series\n## '+name+'\n- component duration:2 jsx:"<div>'+name+'</div>"\n';
+try {
+ const a=join(run,"A.md"),b=join(run,"B.md");
+ await writeFile(a,md("Alpha-v1"));
+ await writeFile(b,md("Beta-v1"));
+ await connect();
+ let A,B;
+ await check("two Videos coexist",async()=>{
+  [A,B]=await Promise.all([preview(a),preview(b)]);
+  assert.notEqual(A.contentHash,B.contentHash);
+  assert.match(JSON.stringify(await compiled(A)),/Alpha-v1/);
+  assert.match(JSON.stringify(await compiled(B)),/Beta-v1/);
+  return {a:A.contentHash,b:B.contentHash};
+ });
+ await check("repeated compile uses same immutable hash",async()=>{
+  const identical=await preview(a);
+  assert.equal(identical.contentHash,A.contentHash);
+ });
+ await writeFile(a,md("Alpha-v2"));
+ await check("new version preserves older static JSON",async()=>{
+  const latest=await preview(a);
+  assert.notEqual(latest.contentHash,A.contentHash);
+  assert.match(JSON.stringify(await compiled(A)),/Alpha-v1/);
+  assert.match(JSON.stringify(await compiled(latest)),/Alpha-v2/);
+  assert.match(JSON.stringify(await compiled(B)),/Beta-v1/);
+ });
+ await check("no port slots: eleven versions of one Video retain only ten",async()=>{
+  const versions=[];
+  for(let i=0;i<11;i++){
+   await writeFile(a,md("Alpha-"+i));
+   versions.push(await preview(a));
+  }
+  const cache=await readdir(join(run,".markcut","cache"));
+  assert.equal(cache.filter(x=>x.endsWith(".json")).length,11); // 10 A + 1 B
+  await readFile(join(exportRoot,"cache",versions[10].contentHash+".json"));
+  await assert.rejects(readFile(join(exportRoot,"cache",versions[0].contentHash+".json")));
+  assert.match(JSON.stringify(await compiled(B)),/Beta-v1/);
+  return {aHistory:10,bHistory:1};
+ });
+ await check("restart does not expire retained static preview",async()=>{
+  await client.close();
+  await connect();
+  const latest=await preview(b);
+  assert.equal(latest.contentHash,B.contentHash);
+  assert.match(JSON.stringify(await compiled(B)),/Beta-v1/);
+ });
+ await check("invalid path does not replace previous compiled",async()=>{
+  const invalid=await client.callTool({name:"markcut.preview",arguments:{path:join(run,"missing.md")}});
+  assert.equal(invalid.isError,true);
+  const existing=await compiled(B);
+  assert.match(JSON.stringify(existing),/Beta-v1/);
+ });
+ await client.close();client=null;
+ await check("no managed player or child process spawned",async()=>{
+  const after=processes();
+  assert.deepEqual(after,before);
+  return {preexisting:before.length,new:0};
+ });
+}catch(error){report.error=String(error);process.exitCode=1;}
+finally{
+ try{await client?.close()}catch{}
+ report.completedAt=new Date().toISOString();
+ const out=process.env.MARKCUT_EVIDENCE_FILE;
+ if(out)await writeFile(out,JSON.stringify(report,null,2)+"\n");
+ console.log(JSON.stringify(report,null,2));
+ await rm(run,{recursive:true,force:true});
+}

package/skills/markcut/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: markcut
-description: use markdown to describe stream trees, provide CLI to render stream trees to video via `npx @lalalic/markcut`. use it to structure video scenes, and generate TTS, TTI, TTV, STT media automatically.
+description: Author, compile, preview, review and render videos from Markcut Markdown stream trees. Use for scene planning, TTS/TTI/TTV/STT media generation, Google Maps GPS routes, native CLI previews, and interactive ChatGPT MCP video reviews with contextual feedback and approval.
 ---
 
 ## Stream Tree Specs
@@ -78,15 +78,21 @@ npx @lalalic/markcut spots --waypoints "lat,lng;lat,lng" # discover POIs along a
 
 ---
 
-## MCP Markdown Review
+## MCP Video Preview and Human Review (Player v24)
 
-Use the model-visible MCP tool `markcut.preview({ path })` when a human needs to review a Markdown artifact. This is a generic Markdown review surface and is separate from the video-specific `npx @lalalic/markcut preview <file>` CLI.
+Use the model-visible `markcut.preview({path})` tool when a human needs to **watch and review a Markcut video** in ChatGPT. It is a video player, **not** a generic Markdown renderer and not the same as the local `npx @lalalic/markcut preview <file>` command.
 
-- `path` must be an absolute path to a Markdown file.
-- The user sees the rendered Markdown and can either **Approve** or submit feedback with **Request changes**.
-- Markcut does not edit the file. The calling agent owns all source changes.
-- On `approved`, continue the workflow.
-- On `changes_requested`, apply the feedback to the source Markdown, then call `markcut.preview({ path })` again for another review round.
+- Supply an absolute `.md` path (or a supported NeoY mounted HTTPS Markdown URL). An optional `relay` object correlates an Agents Relay task but is not needed for standalone review.
+- The MCP call returns promptly with an asynchronous compilation operation. The hosted iframe shows actual compilation stages, then loads a published immutable compiled JSON and media snapshot. There is no persistent player-manager process.
+- Player controls include Play/Pause, Seek, volume/audio, fullscreen and a **horizontal clickable scene list** sourced from compiled scene metadata. The title bar displays **Markcut · video title**, a **Browser TTS** switch, and the player version at right.
+- **Browser TTS** is an optional preview playback mode (default on when subtitle VTT exists). It speaks existing caption/script text in the browser; it does **not** use STT. Toggle off for generated audio and the original subtitle renderer. This switch does not currently skip compilation-time TTS or affect final renders. Playback timing and seeking are approximate for browser speech.
+- Google Maps `map` streams (route/cinematic) can be prerendered by Remotion into MP4 during MCP compilation. The published compiled JSON then references video streams, not live map tiles or a browser-exposed API key. If the render key is unavailable or prerendering fails, the original live Google Maps stream is preserved as a fallback. Native Map support remains available.
+- **Send feedback** (formerly Request changes) requires text and sends `ui/message` with `decision: "changes_requested"`, the source path, revision/content hash, and `playbackContext` (current `sceneId`, `sceneName`, `timeSeconds`) when available. The calling agent must interpret the feedback, edit the supplied video Markdown, and invoke `markcut.preview` again for the next turn. The player does not edit files.
+- **Approve** sends `decision: "approved"` via `ui/message` for the specific revision. Do not approve a different/newer revision on the basis of an old review.
+- Earlier previews are read-only once superseded; the submitted revision is checked against the latest published hash.
+- **Verification boundary:** compilation, static MP4 publication, and focused tests have passed, but complete real-hosted ChatGPT feedback → agent edit → re-preview → approval E2E still requires acceptance testing. Do not claim it is verified based on tool metadata alone.
+
+See [docs/mcp-static-preview.md](../../docs/mcp-static-preview.md) for the lifecycle and [./review.md](./review.md) for content-quality review guidance.
 
 ## review
 use the review contract defined in [./review.md](./review.md) to guide the review process.

package/src/mcp/bridge.mjs

@@ -1,16 +1,168 @@
-export function buildPreviewBridgeScript(submitToolName) {
-  return `
-const feedback=document.getElementById('feedback'),status=document.getElementById('status'),player=document.getElementById('video-player'),pathLabel=document.getElementById('path-label');
-let nextRequestId=0;
-const pendingRequests=new Map();
-function send(message){window.parent.postMessage(message,'*');}
-function rpcRequest(method,params){const id=++nextRequestId;send({jsonrpc:'2.0',id,method,params});return new Promise((resolve,reject)=>pendingRequests.set(id,{resolve,reject}));}
-async function waitForVideo(url){status.textContent='Preparing video…';for(;;){try{const response=await fetch(url+'api/ready',{cache:'no-store'});if(response.ok){const ready=await response.json();if(ready.ready){player.src=url;status.textContent='Video ready for review.';return;}}}catch{}await new Promise(resolve=>setTimeout(resolve,1500));}}
-function applyToolResult(params){const result=params?.result||params||{},data=result.structuredContent||result.structured_content||{};if(typeof data.path==='string')pathLabel.textContent=data.path;if(typeof data.previewUrl==='string')waitForVideo(data.previewUrl);}
-window.addEventListener('message',event=>{if(event.source!==window.parent)return;const message=event.data;if(!message||typeof message!=='object'||message.jsonrpc!=='2.0')return;if(Object.prototype.hasOwnProperty.call(message,'id')&&pendingRequests.has(message.id)){const pending=pendingRequests.get(message.id);pendingRequests.delete(message.id);if(message.error)pending.reject(new Error(message.error.message||'MCP request failed'));else pending.resolve(message.result);return;}if(message.method==='ui/notifications/tool-result')applyToolResult(message.params);});
-async function initializeBridge(){try{await rpcRequest('ui/initialize',{appInfo:{name:'Markcut Preview',version:'1.1.0'},appCapabilities:{},protocolVersion:'2026-01-26'});send({jsonrpc:'2.0',method:'ui/notifications/initialized'});if(!player.src)status.textContent='Waiting for video preview…';}catch(error){status.textContent=error.message||'MCP initialization failed.';}}
-async function submit(decision){const value=feedback.value.trim();if(decision==='changes_requested'&&!value){status.textContent='Feedback is required.';feedback.focus();return;}const result={decision};if(value&&decision==='changes_requested')result.feedback=value;status.textContent='Submitting...';try{await rpcRequest('tools/call',{name:'${submitToolName}',arguments:result});await rpcRequest('ui/message',{role:'user',content:[{type:'text',text:JSON.stringify(result)}]});status.textContent=decision==='approved'?'Approved.':'Changes requested.';}catch(error){status.textContent=error.message||'Unable to submit review.';}}
-initializeBridge();
-document.getElementById('approve').onclick=()=>submit('approved');document.getElementById('changes').onclick=()=>submit('changes_requested');
+export function buildPreviewBridgeScript() {
+return `
+const feedback=document.getElementById('feedback'),status=document.getElementById('status'),pathLabel=document.getElementById('path-label');
+let nextId=0,identity=null,busy=false,expectedPath=null,activePath=null,activeRelay=null,submittedRevision=null;
+const pending=new Map();
+const resultsByPath=new Map();
+let fallbackGeneration=0;
+async function loadRemoteScenes(path){
+ const generation=++fallbackGeneration;
+ try{
+  const digest=await crypto.subtle.digest('SHA-256',new TextEncoder().encode(path));
+  const hash=Array.from(new Uint8Array(digest),x=>x.toString(16).padStart(2,'0')).join('');
+  const url=__MARKCUT_ORIGIN__+'/files/_neoy/markcut/revisions/'+hash+'.json';
+  for(let attempt=0;attempt<25 && generation===fallbackGeneration;attempt++){
+   try{
+    const response=await fetch(url+'?try='+attempt,{cache:'no-store'});
+    if(response.ok){const data=await response.json();
+      if(data.requestedPath===path && (data.compiledUrl||data.compiled) && generation===fallbackGeneration){
+       if(window.__markcutRevision?.requestedPath===path)return;
+       resultsByPath.set(path,data);renderRevision(data);return;
+      }
+    }
+   }catch(e){if(attempt===24)status.textContent='Scene fetch failed: '+String(e);}
+   await new Promise(resolve=>setTimeout(resolve,600));
+  }
+  if(generation===fallbackGeneration && !window.__markcutRevision)status.textContent='Scene data unavailable from NeoY';
+ }catch(e){status.textContent='Scene lookup failed: '+String(e);}
+}
+function send(msg){window.parent.postMessage(msg,'*');}
+function request(method,params){const id=++nextId;send({jsonrpc:'2.0',id,method,params});return new Promise((resolve,reject)=>pending.set(id,{resolve,reject}));}
+function showVideoName(path,title){const el=document.getElementById('video-md-version');if(!el)return;const file=typeof path==='string'?decodeURIComponent(path.split('/').pop()||'video.md'):'video.md';el.textContent=typeof title==='string'&&title.trim()?title.trim():file.replace(/\.md$/i,'').replace(/[-_]+/g,' ');}
+function applyToolInput(params){
+ const input=params?.arguments||params?.input||params?.toolInput||params||{};
+ if(typeof input.path!=='string')return;
+ expectedPath=input.path;
+ loadRemoteScenes(expectedPath);
+ showVideoName(expectedPath);
+ const cached=resultsByPath.get(expectedPath);
+ if(cached){if(cached.operationUrl)trackOperation(cached);else renderRevision(cached);return;}
+ if(window.__markcutRevision?.path!==expectedPath && window.__markcutRevision?.requestedPath!==expectedPath){
+  identity=null;
+  window.__markcutRevision=null;
+  window.dispatchEvent(new CustomEvent('markcut:revision',{detail:null}));
+  pathLabel.textContent=expectedPath;
+  status.textContent='Waiting for matching video scenes…';
+ }
+}
+let operationGeneration=0;
+async function trackOperation(data){
+ const generation=++operationGeneration;
+ ++fallbackGeneration; // Prevent an old published revision from replacing in-progress UI.
+ let url;
+ try{url=new URL(data.operationUrl);}catch{status.textContent='Invalid operation URL';return;}
+ if(url.origin!==__MARKCUT_ORIGIN__||!url.pathname.startsWith('/files/_neoy/markcut/operations/')||!(/^[a-f0-9-]{36}[.]json$/.test(url.pathname.split('/').pop()))){
+  status.textContent='Invalid operation URL';return;
+ }
+ document.getElementById('interactive-ui').hidden=true;
+ reviewReadonly(true,'Compiling…');
+ for(let attempt=0;attempt<1800&&generation===operationGeneration;attempt++){
+  try{
+   const response=await fetch(url.href+'?t='+Date.now(),{cache:'no-store'});
+   if(!response.ok)throw new Error('HTTP '+response.status);
+   const progress=await response.json();
+   if(generation!==operationGeneration)return;
+   if(progress.state==='ready'&&progress.result){renderRevision({...progress.result,requestedPath:data.requestedPath||data.path,relay:data.relay});return;}
+   if(progress.state==='failed'){reviewReadonly(true,'Compilation failed: '+progress.error);return;}
+   const elapsed=Math.round((Date.now()-(progress.startedAt||Date.now()))/1000);
+   status.textContent='Compiling · '+(progress.stage||'working')+' · '+elapsed+'s';
+  }catch(e){status.textContent='Waiting for compile status… '+String(e);}
+  await new Promise(resolve=>setTimeout(resolve,1000));
+ }
+ if(generation===operationGeneration)status.textContent='Compilation status timed out';
+}
+function applyToolResult(params){
+ const result=params?.result||params||{};
+ const data=result.structuredContent||result.structured_content||result._meta?.ui?.props||{};
+ if(typeof data.path==='string')resultsByPath.set(data.path,data);
+ if(typeof data.requestedPath==='string')resultsByPath.set(data.requestedPath,data);
+ if(expectedPath&&data.path!==expectedPath&&data.requestedPath!==expectedPath)return;
+ if(data.operationUrl){trackOperation(data);return;}
+ renderRevision(data);
+}
+let renderGeneration=0;
+async function currentRevisionMatches(path,hash){
+ if(!path||!hash)return false;
+ const digest=await crypto.subtle.digest('SHA-256',new TextEncoder().encode(path));
+ const key=Array.from(new Uint8Array(digest),x=>x.toString(16).padStart(2,'0')).join('');
+ const response=await fetch(__MARKCUT_ORIGIN__+'/files/_neoy/markcut/revisions/'+key+'.json?t='+Date.now(),{cache:'no-store'});
+ if(!response.ok)throw new Error('Latest preview status unavailable');
+ const latest=await response.json();
+ return latest.contentHash===hash;
+}
+function reviewReadonly(readonly,message){
+ document.getElementById('approve').disabled=readonly;
+ document.getElementById('changes').disabled=readonly;
+ if(readonly&&message)status.textContent=message;
+}
+async function renderRevision(data){
+ const generation=++renderGeneration;
+ if(data.path){pathLabel.textContent=data.path;showVideoName(data.path,data.title||data.videoTitle);}
+ if(!data.compiled&&!data.compiledUrl){status.textContent='Compiled scenes unavailable';return;}
+ identity={previewId:data.id,revisionId:data.revisionId,contentHash:data.contentHash};
+ activePath=data.requestedPath||data.path||expectedPath||null;
+ activeRelay=data.relay||null;
+ if(submittedRevision!==data.revisionId){busy=false;submittedRevision=null;}
+ reviewReadonly(true,'Loading static compiled scenes…');
+ try{
+  let compiled=data.compiled;
+  if(data.compiledUrl){
+   const url=new URL(data.compiledUrl);
+   if(url.origin!==__MARKCUT_ORIGIN__||!url.pathname.startsWith('/files/_neoy/markcut/cache/')||!(/^[a-f0-9]{64}[.]json$/.test(url.pathname.split('/').pop())))
+    throw new Error('Invalid immutable preview URL');
+   const response=await fetch(url.href,{cache:'force-cache'});
+   if(!response.ok)throw new Error('Static compiled scenes unavailable: HTTP '+response.status);
+   compiled=await response.json();
+  }
+  if(generation!==renderGeneration)return;
+  document.getElementById('interactive-ui').hidden=false;
+  window.__markcutRevision={...data,compiled};
+  window.dispatchEvent(new CustomEvent('markcut:revision',{detail:window.__markcutRevision}));
+  status.textContent='';
+  if(!data.compiledUrl){reviewReadonly(false);return;}
+  const same=await currentRevisionMatches(activePath,identity.contentHash);
+  if(generation!==renderGeneration)return;
+  reviewReadonly(!same,same?'':'Historical Preview · Read-only');
+ }catch(e){
+  if(generation!==renderGeneration)return;
+  reviewReadonly(true,'Preview unavailable or review state unverified: '+String(e));
+ }
+}
+window.addEventListener('message',event=>{
+ if(event.source!==window.parent)return;
+ const message=event.data;
+ if(!message||message.jsonrpc!=='2.0')return;
+ if(Object.prototype.hasOwnProperty.call(message,'id')&&pending.has(message.id)){
+  const item=pending.get(message.id);pending.delete(message.id);
+  if(message.error)item.reject(new Error(message.error.message||'MCP request failed'));
+  else item.resolve(message.result);
+ }else if(message.method==='ui/notifications/tool-input')applyToolInput(message.params);
+ else if(message.method==='ui/notifications/tool-result')applyToolResult(message.params);
+});
+async function initialize(){
+ try {await request('ui/initialize',{appInfo:{name:'Markcut Preview',version:'2.0.0'},appCapabilities:{},protocolVersion:'2026-01-26'});send({jsonrpc:'2.0',method:'ui/notifications/initialized'});}
+ catch(e){status.textContent=e.message||'MCP initialization failed';}
+}
+async function submit(decision){
+ if(busy)return;
+ const value=feedback.value.trim();
+ if(decision==='changes_requested'&&!value){status.textContent='Feedback is required.';return;}
+ if(!identity){status.textContent='Preview identity unavailable.';return;}
+ if(window.__markcutRevision?.compiledUrl){
+  try{if(!await currentRevisionMatches(activePath,identity.contentHash)){reviewReadonly(true,'Historical Preview · Read-only');return;}}
+  catch(e){reviewReadonly(true,'Cannot verify latest preview: '+String(e));return;}
+ }
+ const result={...identity,decision};
+ if(activePath)result.path=activePath;
+ if(activeRelay)result.relay=activeRelay;
+ if(decision==='changes_requested'){result.feedback=value;if(window.__markcutPlaybackContext)result.playbackContext=window.__markcutPlaybackContext;}
+ busy=true;status.textContent='Submitting…';
+ const submittedId=result.revisionId;
+ try{await request('ui/message',{role:'user',content:[{type:'text',text:JSON.stringify(result)}]});if(identity?.revisionId===submittedId){submittedRevision=submittedId;status.textContent=decision==='approved'?'Approved.':'Feedback sent. Waiting for the updated preview.';}}
+ catch(e){busy=false;status.textContent=e.message||'Unable to submit review';}
+}
+document.getElementById('approve').onclick=()=>submit('approved');
+document.getElementById('changes').onclick=()=>submit('changes_requested');
+initialize();
 `;
 }

package/src/mcp/browser-speech-preview.ts

@@ -0,0 +1,60 @@
+import * as React from "react";
+import type {PlayerRef} from "@remotion/player";
+
+type Cue={start:number;end:number;text:string};
+function seconds(s:string){const a=s.replace(",",".").split(":").map(Number);return a.reduce((v,n)=>v*60+n,0);}
+export function parseVtt(text:string):Cue[]{
+ const lines=text.replace(/\r/g,"").split("\n"),cues:Cue[]=[];
+ for(let i=0;i<lines.length;i++){
+  if(!lines[i].includes("-->"))continue;
+  const match=lines[i].match(/(\d{2}:)?\d{2}:\d{2}[.,]\d+\s*-->\s*((\d{2}:)?\d{2}:\d{2}[.,]\d+)/);
+  if(!match)continue;
+  const [from,to]=match[0].split("-->").map(x=>x.trim());
+  const start=seconds(from),end=seconds(to);
+  let content="";while(lines[++i]?.trim())content+=(content?" ":"")+lines[i].replace(/<[^>]*>/g,"");
+  if(content)cues.push({start,end,text:content});
+ }
+ return cues;
+}
+export function useBrowserSpeechPreview(root:any,playerRef:React.RefObject<PlayerRef|null>,enabled:boolean){
+ const [cues,setCues]=React.useState<Cue[]>([]);
+ const [time,setTime]=React.useState(0);
+ React.useEffect(()=>{
+  setCues([]);
+  if(!enabled||!root?.subtitle?.src)return;
+  const ctrl=new AbortController();
+  fetch(root.subtitle.src,{signal:ctrl.signal}).then(r=>{if(!r.ok)throw Error("VTT unavailable");return r.text()})
+    .then(text=>setCues(parseVtt(text))).catch(()=>{});
+  return ()=>ctrl.abort();
+ },[root?.subtitle?.src,enabled]);
+ React.useEffect(()=>{
+  if(!enabled||typeof window==="undefined"||!("speechSynthesis" in window))return;
+  const synth=window.speechSynthesis;
+  let player:PlayerRef|null=null,disposed=false,lastIndex=-1;
+  const stop=()=>{synth.cancel();lastIndex=-1;};
+  const update=()=>{
+   if(!player||disposed)return;
+   const t=player.getCurrentFrame()/(root?.fps||30);
+   setTime(t);
+   if(!player.isPlaying()){stop();return;}
+   const index=cues.findIndex(c=>t>=c.start&&t<c.end);
+   if(index===lastIndex)return;
+   synth.cancel();lastIndex=index;
+   if(index>=0&&!player.isMuted()){
+    const utterance=new SpeechSynthesisUtterance(cues[index].text);
+    utterance.rate=1;utterance.volume=player.getVolume();
+    synth.speak(utterance);
+   }
+  };
+  const attach=()=>{
+   if(player||!playerRef.current)return;
+   player=playerRef.current;
+   for(const event of ["frameupdate","play","pause","seeked","ended","mutechange"])player.addEventListener(event,update);
+  };
+  attach();
+  const poll=setInterval(attach,150);
+  return()=>{disposed=true;clearInterval(poll);if(player)for(const event of ["frameupdate","play","pause","seeked","ended","mutechange"])player.removeEventListener(event,update);stop();};
+ },[enabled,cues,root?.fps,playerRef]);
+ const active=cues.find(c=>time>=c.start&&time<c.end);
+ return {caption:enabled?active?.text||"":""};
+}

package/src/mcp/compile-operation.mjs

@@ -0,0 +1,52 @@
+import {spawn} from "node:child_process";
+import {randomUUID,createHash} from "node:crypto";
+import {mkdirSync,writeFileSync,renameSync,statSync,readFileSync,readdirSync,rmSync} from "node:fs";
+import {join} from "node:path";
+import {fileURLToPath} from "node:url";
+import {EXPORT_ROOT,publicOrigin,resolvePreviewPath} from "./remote-assets.mjs";
+import {validateMarkdownPath} from "./preview.mjs";
+const folder=join(EXPORT_ROOT,"operations");
+const RETAIN_MS=24*60*60*1000;
+function cleanupOldOperations(){
+ try{
+  const cutoff=Date.now()-RETAIN_MS;
+  for(const entry of readdirSync(folder,{withFileTypes:true})){
+   if(!entry.isFile()||!entry.name.endsWith(".json"))continue;
+   const file=join(folder,entry.name);
+   const info=statSync(file);
+   if(info.mtimeMs<cutoff)rmSync(file,{force:true});
+  }
+ }catch{}
+}
+
+export function writeOperation(id,data){
+ if(!/^[a-f0-9-]{36}$/.test(id))throw new Error("Invalid operation ID");
+ mkdirSync(folder,{recursive:true});
+ const temp=join(folder,id+"."+process.pid+".tmp");
+ writeFileSync(temp,JSON.stringify(data),{mode:0o644});
+ renameSync(temp,join(folder,id+".json"));
+}
+export function startCompileOperation(path,relay){
+ const valid=validateMarkdownPath(resolvePreviewPath(path));
+ if(!statSync(valid).isFile())throw new Error("Preview source must be a Markdown file");
+ const sourceHash=createHash("sha256").update(readFileSync(valid)).digest("hex");
+ cleanupOldOperations();
+ const id=randomUUID(),startedAt=Date.now();
+ writeOperation(id,{id,state:"compiling",stage:"queued",startedAt,requestedPath:path});
+ const worker=fileURLToPath(new URL("./compile-worker.mjs",import.meta.url));
+ const child=spawn(process.execPath,[worker,id,valid,path,JSON.stringify(relay||null),sourceHash],{detached:true,stdio:"ignore"});
+ child.on("error",e=>{
+  writeOperation(id,{id,state:"failed",stage:"failed",startedAt,requestedPath:path,error:e.message});
+ });
+ child.on("exit",(code,signal)=>{
+  try{
+   const state=JSON.parse(readFileSync(join(folder,id+".json"),"utf8"));
+   if(state.state==="compiling"){
+    writeOperation(id,{id,state:"failed",stage:"failed",startedAt,requestedPath:path,
+      error:"Compiler exited unexpectedly: "+(signal||code)});
+   }
+  }catch{}
+ });
+ child.unref();
+ return {operationId:id,operationUrl:publicOrigin()+"/files/_neoy/markcut/operations/"+id+".json",path:valid,requestedPath:path,state:"compiling"};
+}

package/src/mcp/compile-worker.mjs

@@ -0,0 +1,20 @@
+import {createHash} from "node:crypto";
+import {readFileSync} from "node:fs";
+import {ensureVideoPreview} from "./preview.mjs";
+import {publishPreviewRevision} from "./remote-assets.mjs";
+import {writeOperation} from "./compile-operation.mjs";
+const [id,path,requestedPath,relayText,sourceHash]=process.argv.slice(2);
+const startedAt=Date.now();
+function update(stage){writeOperation(id,{id,state:"compiling",stage,startedAt,updatedAt:Date.now(),requestedPath});}
+try{
+ update("resolving-and-compiling");
+ const actualHash=createHash("sha256").update(readFileSync(path)).digest("hex");
+ if(actualHash!==sourceHash)throw new Error("Source changed while queued; retry preview");
+ const result=await ensureVideoPreview(path,{onProgress:update});
+ update("publishing");
+ publishPreviewRevision(requestedPath,{...result,requestedPath});
+ writeOperation(id,{id,state:"ready",stage:"complete",startedAt,updatedAt:Date.now(),requestedPath,result:{...result,requestedPath,relay:JSON.parse(relayText)}});
+}catch(e){
+ writeOperation(id,{id,state:"failed",stage:"failed",startedAt,updatedAt:Date.now(),requestedPath,error:e?.message||String(e)});
+ process.exitCode=1;
+}

package/src/mcp/map-footage.mjs

@@ -0,0 +1,52 @@
+import {mkdtemp,writeFile,stat,rename,rm,mkdir} from "node:fs/promises";
+import {tmpdir} from "node:os";
+import {join,resolve,dirname} from "node:path";
+import {execFile} from "node:child_process";
+import {promisify} from "node:util";
+import {fileURLToPath} from "node:url";
+const run=promisify(execFile);
+const projectRoot=resolve(dirname(fileURLToPath(import.meta.url)),"../..");
+export function findMapScenes(root){
+ return (root?.children||[]).filter(x=>x?.type==="scene"&&x.visible!==false&&
+  Array.isArray(x.children)&&x.children.some(child=>child.type==="map"));
+}
+export async function renderMapFootage(compiled,{generatedDir,key,onProgress=()=>{}}){
+ const root=compiled.root||compiled;
+ const scenes=findMapScenes(root);
+ if(!scenes.length)return {compiled,rendered:0,skipped:0};
+ if(!key)return {compiled,rendered:0,skipped:scenes.length};
+ const output=structuredClone(compiled);
+ const outputRoot=output.root||output;
+ let rendered=0,skipped=0;
+ await mkdir(generatedDir,{recursive:true});
+ for(const [index,scene] of findMapScenes(outputRoot).entries()){
+  // Render a complete scene so map overlays are retained. The fallback tree
+  // remains unchanged until the video has been successfully produced.
+  const duration=Number(scene.durationInSeconds)||0;
+  if(duration<=0){skipped++;continue;}
+  const name="map-footage-"+index+".mp4";
+  const destination=join(generatedDir,name);
+  const temporary=await mkdtemp(join(tmpdir(),"markcut-map-render-"));
+  try{
+   const source=structuredClone(scene);
+   const isolated={...structuredClone(outputRoot),isSeries:true,children:[source],durationInSeconds:duration};
+   delete isolated.subtitle; // Global captions belong to the final video, not map footage.
+   const file=join(temporary,"props.json");
+   await writeFile(file,JSON.stringify({root:isolated}),{mode:0o600});
+   onProgress("rendering-map-footage-"+(index+1)+"-of-"+scenes.length);
+   await run(resolve(projectRoot,"node_modules/.bin/remotion"),[
+    "render",resolve(projectRoot,"src/index.ts"),"Root",join(temporary,name),
+    "--props",file,"--codec","h264","--concurrency","1"
+   ],{cwd:projectRoot,timeout:180000,maxBuffer:1024*1024*4,env:process.env});
+   if((await stat(join(temporary,name))).size<1024)throw Error("Empty map footage");
+   await rename(join(temporary,name),destination);
+   scene.children=[{id:"map-footage-"+index,type:"video",visible:true,start:0,end:duration,
+    durationInSeconds:duration,src:destination,volume:0}];
+   rendered++;
+  }catch(error){
+   skipped++;
+   onProgress("map-footage-fallback-"+(index+1));
+  }finally{await rm(temporary,{recursive:true,force:true});}
+ }
+ return {compiled:output,rendered,skipped};
+}