@lalalic/markcut 3.2.14 → 3.2.15

package/src/mcp/preview.mjs

@@ -1,39 +1,83 @@
-import { spawn } from "node:child_process";
-import { access } from "node:fs/promises";
-import { constants as fsConstants } from "node:fs";
-import { isAbsolute, extname, dirname, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { mkdir, writeFile, readdir, rename, rm, stat, utimes } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
+import { constants as fsConstants, readFileSync } from "node:fs";
+import { isAbsolute, extname, dirname, resolve, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildPreviewBridgeScript } from "./bridge.mjs";
+import { externalizePreviewMedia, publicOrigin, resolveMountedFile, resolvePreviewPath, publishPlayerBundle, publishCompiledCache, prunePublishedCache, EXPORT_ROOT } from "./remote-assets.mjs";
 
 export const TOOL_NAME = "markcut.preview";
-export const SUBMIT_TOOL_NAME = "markcut.preview.submit";
-export const RESOURCE_URI = "ui://markcut/video-preview-v3.html";
+export const RESOURCE_URI = "ui://markcut/video-preview-v24.html";
+// Legacy entrypoints remain registered, but serve the current implementation.
+export const LEGACY_RESOURCE_URIS = [
+  "ui://markcut/video-preview-v3.html",
+  "ui://markcut/video-preview-v4.html",
+  "ui://markcut/video-preview-v5.html",
+  "ui://markcut/video-preview-v6.html",
+  "ui://markcut/video-preview-v7.html",
+  "ui://markcut/video-preview-v8.html",
+  "ui://markcut/video-preview-v9.html",
+  "ui://markcut/video-preview-v10.html",
+  "ui://markcut/video-preview-v11.html",
+  "ui://markcut/video-preview-v12.html",
+  "ui://markcut/video-preview-v13.html",
+  "ui://markcut/video-preview-v14.html",
+  "ui://markcut/video-preview-v15.html",
+  "ui://markcut/video-preview-v16.html",
+  "ui://markcut/video-preview-v17.html",
+  "ui://markcut/video-preview-v18.html",
+  "ui://markcut/video-preview-v19.html",
+  "ui://markcut/video-preview-v20.html",
+  "ui://markcut/video-preview-v21.html",
+  "ui://markcut/video-preview-v22.html",
+  "ui://markcut/video-preview-v23.html",
+];
 export const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
-export const PLAYER_PORT = 4571;
-export const PLAYER_ORIGIN = `http://127.0.0.1:${PLAYER_PORT}`;
-
+// Google Maps JS loads libraries, tiles and Routes RPCs from these HTTPS origins.
+// The MCP app sandbox enforces the declared domains; native localhost does not.
+export const MAPS_CSP_DOMAINS = Object.freeze([
+  "https://maps.googleapis.com",
+  "https://maps.gstatic.com",
+  "https://maps-api-v3.googleapis.com",
+  "https://routes.googleapis.com",
+]);
+export function previewCsp() {
+  return {
+    connectDomains: [publicOrigin(), ...MAPS_CSP_DOMAINS],
+    resourceDomains: [publicOrigin(), ...MAPS_CSP_DOMAINS],
+    frameDomains: [],
+  };
+}
 const moduleDir = dirname(fileURLToPath(import.meta.url));
-const playerServer = resolve(moduleDir, "../player/server.mjs");
-let managedPlayer = null;
-let managedPath = null;
-let startPromise = null;
+const bundlePath = resolve(moduleDir,"remotion-app.bundle.js");
+const pendingCompiles = new Map();
+const activeCompilesByPath = new Map();
+const KEEP = 10;
 
-export function buildPreviewResourceResult() {
+export function getPreviewMedia(contentHash) {
+  if (!/^[a-f0-9]{64}$/.test(contentHash)) throw new Error("Invalid Markcut content hash");
+  try {
+    return {compiled:JSON.parse(readFileSync(resolve(EXPORT_ROOT,"cache",contentHash+".json"),"utf8"))};
+  } catch {throw new Error("Unknown or expired Markcut compiled scenes");}
+}
+
+export function previewResourceUri(contentHash) {
+  return `${RESOURCE_URI}/${contentHash}`;
+}
+
+export function buildPreviewResourceResult(resourceUri = RESOURCE_URI) {
   return {
     ttlMs: 0,
     cacheScope: "private",
     contents: [{
-      uri: RESOURCE_URI,
+      uri: resourceUri,
       mimeType: RESOURCE_MIME_TYPE,
       text: buildPreviewHtml(),
       _meta: {
         ui: {
           prefersBorder: true,
-          csp: {
-            connectDomains: [PLAYER_ORIGIN],
-            resourceDomains: [],
-            frameDomains: [PLAYER_ORIGIN],
-          },
+          csp: previewCsp(),
         },
       },
     }],
@@ -50,60 +94,164 @@ export function validateMarkdownPath(value) {
   return value;
 }
 
-export async function ensureVideoPreview(path, options = {}) {
-  const validatedPath = validateMarkdownPath(path);
-  await access(validatedPath, fsConstants.R_OK);
-  if (managedPlayer && managedPath === validatedPath && managedPlayer.exitCode == null && !managedPlayer.killed) {
-    return { path: validatedPath, previewUrl: `${PLAYER_ORIGIN}/` };
-  }
-  if (startPromise && managedPath === validatedPath) return startPromise;
+export async function readPreviewAudio(path) {
+  const markdown = await readFile(path, "utf8");
+  const match = markdown.match(/^audio:\s*([^\r\n]+)\s*$/m);
+  const filename = match ? match[1].trim() : `${basename(path, ".md")}.wav`;
+  if (!/^[\w. -]+\.(wav|mp3|m4a|ogg)$/i.test(filename) || filename.startsWith(".")) throw new Error("audio must be a local audio filename in the Markdown directory");
+  const file = resolve(dirname(path), filename);
+  try { await access(file, fsConstants.R_OK); } catch (e) { if (!match && e.code === "ENOENT") return {}; throw e; }
+  const remote = resolveMountedFile(file);
+  if (remote) return {audioSrc: file}; // Freeze mounted local audio into this immutable preview.
+  const data = await readFile(file);
+  if (data.length > 2 * 1024 * 1024) throw new Error("audio file exceeds 2 MB preview limit for unmounted media");
+  const ext = filename.split(".").pop().toLowerCase();
+  const mime = {wav:"audio/wav",mp3:"audio/mpeg",m4a:"audio/mp4",ogg:"audio/ogg"}[ext];
+  return {audioSrc:`data:${mime};base64,${data.toString("base64")}`};
+}
 
-  if (managedPlayer && managedPlayer.exitCode == null && !managedPlayer.killed) {
-    managedPlayer.kill("SIGTERM");
+export function withPreviewAudio(compiled, audioSrc) {
+  if (!audioSrc) return compiled;
+  const root = compiled.root || compiled;
+  const children = root.children || [];
+  const duration = root.durationInSeconds || children.filter(child=>!child.isBackground).reduce((sum,child)=>sum+(child.durationInSeconds||child.duration||0),0);
+  if (!duration) throw new Error('compiled preview has no duration for audio track');
+  return {...compiled, ...(compiled.root ? {root:{...root,children:[...children,{id:'mcp-preview-audio',type:'audio',src:audioSrc,volume:1,isBackground:true,start:0,end:duration,duration,durationInSeconds:duration}]}} : {children:[...children,{id:'mcp-preview-audio',type:'audio',src:audioSrc,volume:1,isBackground:true,start:0,end:duration,duration,durationInSeconds:duration}]})};
+}
+
+async function atomicJson(path, value) {
+  const temp = path + "." + process.pid + "." + Math.random().toString(16).slice(2) + ".tmp";
+  await writeFile(temp, JSON.stringify(value, null, 2), {flag:"wx"});
+  try { await rename(temp, path); }
+  finally { await rm(temp, {force:true}); }
+}
+
+async function pruneCache(dir, indexFile, entries, currentHash) {
+  const unique=[currentHash,...entries.filter(hash=>hash!==currentHash)];
+  const kept=unique.slice(0,KEEP);
+  const retired=unique.slice(KEEP);
+  const index={latest:currentHash, entries:kept};
+  await atomicJson(indexFile,index);
+  // Only prune local entries that are not used by another variant index.
+  for(const hash of retired) {
+    const siblings=await readdir(resolve(dir,".."),{withFileTypes:true});
+    let referenced=false;
+    for(const folder of siblings) {
+      if(!folder.isDirectory() || folder.name==="cache" || folder.name==="generated")continue;
+      const variants=await readdir(resolve(dir,"..",folder.name),{withFileTypes:true}).catch(()=>[]);
+      for(const variant of variants) {
+        if(!variant.isDirectory())continue;
+        const data=await readFile(resolve(dir,"..",folder.name,variant.name,"cache-index.json"),"utf8").catch(()=>"");
+        try {if(JSON.parse(data).entries?.includes(hash))referenced=true;} catch{}
+      }
+    }
+    if(!referenced){
+      await rm(resolve(dir,hash+".json"),{force:true});
+      await prunePublishedCache(hash);
+    }
   }
-  managedPlayer = null;
-  managedPath = validatedPath;
+}
 
-  const spawnImpl = options.spawnImpl || spawn;
-  const settleMs = options.settleMs ?? 250;
-  startPromise = new Promise((resolvePromise, rejectPromise) => {
-    const child = spawnImpl(process.execPath, [playerServer, validatedPath, `--port=${PLAYER_PORT}`], {
-      cwd: resolve(moduleDir, "../.."),
-      stdio: ["ignore", "pipe", "pipe"],
+export async function ensureVideoPreview(path, options = {}) {
+  const validatedPath = validateMarkdownPath(resolvePreviewPath(path));
+  await access(validatedPath, fsConstants.R_OK);
+  const source=await readFile(validatedPath,"utf8");
+  const sourceHash=createHash("sha256").update(source).digest("hex");
+  const key=validatedPath+"\0"+sourceHash;
+  if(pendingCompiles.has(key))return pendingCompiles.get(key);
+  const prior=activeCompilesByPath.get(validatedPath)||Promise.resolve();
+  const task=prior.catch(()=>{}).then(async()=>{
+    const {parseMarkdownDescriptive,resolveAll,compileDescriptiveRoot}=await import("../player/pipeline.mjs");
+    const report=typeof options.onProgress==="function" ? options.onProgress : ()=>{};
+    report("checking-cache");
+    const baseDir=dirname(validatedPath);
+    const outputRoot=resolve(baseDir,".markcut");
+    const generated=resolve(outputRoot,"generated");
+    const dir=resolve(outputRoot,basename(validatedPath,".md"),"default");
+    const cacheDir=resolve(outputRoot,"cache");
+    const indexFile=resolve(dir,"cache-index.json");
+    const audio=await readPreviewAudio(validatedPath);
+    const referencedAssets=[];
+    for(const match of source.matchAll(/\b(?:src|audio)\s*:\s*["']?([^"'\s;]+\.(?:png|jpe?g|webp|svg|gif|mp4|mov|webm|wav|mp3|m4a|ogg|vtt|srt))/gi)){
+      const candidate=match[1];
+      if(candidate.includes("://")||candidate.startsWith("/"))continue;
+      try {
+        const info=await stat(resolve(baseDir,candidate));
+        if(info.isFile())referencedAssets.push([candidate,info.size,info.mtimeMs]);
+      }catch{}
+    }
+    referencedAssets.sort((a,b)=>String(a[0]).localeCompare(String(b[0])));
+    // Compilation generates random scene ids. Identity must be based on inputs,
+    // not on non-semantic runtime ids, so unchanged files reuse identical cache.
+    if(audio.audioSrc && audio.audioSrc.startsWith("/")){
+      const info=await stat(audio.audioSrc);
+      referencedAssets.push([audio.audioSrc,info.size,info.mtimeMs]);
+    }
+    const hash=createHash("sha256").update(validatedPath).update("\0")
+      .update(source).update("\0").update(JSON.stringify(referencedAssets)).update("\0").update(audio.audioSrc||"")
+      .update("\0").update(process.env.GOOGLE_MAPS_API_KEY||"")
+      .update("\0").update("map-footage-v2").digest("hex");
+    const id=hash;
+    let index={entries:[]};
+    try {index=JSON.parse(await readFile(indexFile,"utf8"));} catch{}
+    const cached=resolve(cacheDir,hash+".json");
+    let finalCompiled;
+    try {finalCompiled=JSON.parse(await readFile(cached,"utf8"));} catch{}
+    if(!finalCompiled) {
+    report("parsing-markdown");
+    const descriptive=parseMarkdownDescriptive(source);
+    report("resolving-assets-and-generating-media");
+    const resolved=await resolveAll(descriptive,{
+      sourcePath:validatedPath,baseDir,
+      seed:parseInt(sourceHash.slice(0,8),16), // avoid rewriting original Markdown
+      scriptOutputDir:resolve(generated,"tts"),
+      mediaOutputDir:resolve(generated,"media"),
+      includeOutputDir:resolve(generated,"includes"),
     });
-    managedPlayer = child;
-    let stderr = "";
-    let settled = false;
-    const finish = (error) => {
-      if (settled) return;
-      settled = true;
-      startPromise = null;
-      if (error) {
-        if (managedPlayer === child) managedPlayer = null;
-        rejectPromise(error);
-      } else {
-        resolvePromise({ path: validatedPath, previewUrl: `${PLAYER_ORIGIN}/` });
-      }
-    };
-    child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
-    child.once("error", (error) => finish(new Error(`unable to start Markcut player: ${error.message}`)));
-    child.once("exit", (code, signal) => {
-      if (managedPlayer === child) managedPlayer = null;
-      if (!settled) finish(new Error(`Markcut player exited during startup (${signal || code || "unknown"})${stderr ? `: ${stderr.trim()}` : ""}`));
+    report("compiling-scenes");
+    const compiled=compileDescriptiveRoot(resolved,{googleMapsApiKey:process.env.GOOGLE_MAPS_API_KEY});
+    const withAudio=withPreviewAudio(compiled,audio.audioSrc);
+    // Keep the live Google Maps stream when prerendering is unavailable.
+    const {renderMapFootage}=await import("./map-footage.mjs");
+    const footage=await renderMapFootage(withAudio,{
+      generatedDir:resolve(generated,"map-footage",id),
+      key:process.env.GOOGLE_MAPS_API_KEY,
+      onProgress:report,
     });
-    setTimeout(() => {
-      if (!settled) finish();
-    }, settleMs);
+    report("freezing-preview-assets");
+    const external=externalizePreviewMedia(footage.compiled,id,publicOrigin(),baseDir);
+    finalCompiled=external.compiled;
+    await mkdir(cacheDir,{recursive:true});
+    try {await writeFile(cached,JSON.stringify(finalCompiled,null,2),{flag:"wx"});}
+    catch(error){if(error.code!=="EEXIST")throw error;}
+    }
+    const currentSource=await readFile(validatedPath,"utf8");
+    if(createHash("sha256").update(currentSource).digest("hex")!==sourceHash)
+      throw new Error("Source changed during compilation; retry preview");
+    await mkdir(dir,{recursive:true});
+    report("publishing-static-preview");
+    // Static publication is completed before updating the latest pointer.
+    const compiledUrl=publishCompiledCache(hash, finalCompiled);
+    await atomicJson(resolve(dir,"compiled.json"),finalCompiled);
+    await utimes(cached,new Date(),new Date());
+    await pruneCache(cacheDir,indexFile,index.entries||[],hash);
+    const preview={
+      id,revisionId:id,contentHash:hash,sourceHash,path:validatedPath,
+      compiledUrl, resourceUri:RESOURCE_URI,
+      assetBaseUrl:publicOrigin()+"/files/_neoy/markcut/generated/"+id+"/",
+    };
+    return preview;
   });
-  return startPromise;
+  activeCompilesByPath.set(validatedPath,task);
+  pendingCompiles.set(key,task);
+  try{return await task;} finally{
+    pendingCompiles.delete(key);
+    if(activeCompilesByPath.get(validatedPath)===task)activeCompilesByPath.delete(validatedPath);
+  }
 }
 
-export function stopManagedVideoPreview() {
-  if (managedPlayer && managedPlayer.exitCode == null && !managedPlayer.killed) managedPlayer.kill("SIGTERM");
-  managedPlayer = null;
-  managedPath = null;
-  startPromise = null;
-}
+// Compatibility export: there is no longer a managed player to stop.
+export function stopManagedVideoPreview() {}
 
 export function reviewResult(decision, feedback = "") {
   if (decision === "approved") return { decision };
@@ -125,11 +273,15 @@ export function reviewMessage(result) {
 }
 
 export function buildPreviewHtml() {
-  return `<!doctype html>
-<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Markcut video review</title>
-<style>body{font:15px system-ui,sans-serif;margin:0;color:#17202a;background:#fff}main{max-width:980px;margin:auto;padding:16px}.meta{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:10px}.meta h1{font-size:18px;margin:0}.path{font-size:12px;color:#656d76;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.player{width:100%;aspect-ratio:9/16;max-height:72vh;border:1px solid #d8dee4;border-radius:10px;background:#0d1117;overflow:hidden}.player iframe{width:100%;height:100%;border:0;display:block}textarea{box-sizing:border-box;width:100%;min-height:82px;margin:12px 0 8px;padding:10px;border:1px solid #8c959f;border-radius:6px;font:inherit}button{border:0;border-radius:6px;padding:9px 14px;margin-right:8px;font:inherit;cursor:pointer}#approve{background:#1f883d;color:#fff}#changes{background:#cf222e;color:#fff}#status{min-height:1.4em;margin:8px 0;color:#656d76}</style></head>
-<body><main><div class="meta"><h1>Review video</h1><div class="path" id="path-label"></div></div><div class="player"><iframe id="video-player" title="Markcut video preview" allow="autoplay; fullscreen"></iframe></div>
-<label for="feedback">Feedback (required for requested changes)</label><textarea id="feedback" placeholder="What should be changed?"></textarea><div id="status" role="status">Starting preview…</div>
-<button id="approve">Approve</button><button id="changes">Request changes</button></main>
-<script>${buildPreviewBridgeScript(SUBMIT_TOOL_NAME)}</script></body></html>`;
+  const playerScriptUrl = publishPlayerBundle(bundlePath);
+  // Base64 keeps HTML parser-sensitive sequences inside the large JS bundle
+  // from terminating the embedding script tag or leaking source into the DOM.
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Markcut</title>
+<style>body{font:14px system-ui;margin:0;background:#fff;color:#17202a}main{padding:12px;max-width:960px;margin:auto}h1{font-size:17px}.path{font-size:12px;overflow-wrap:anywhere}.transport{display:flex;align-items:center;gap:10px;padding:12px 0}.transport input{flex:1;min-width:50px}button{cursor:pointer;padding:8px;border-radius:6px;border:1px solid #a8a8a8}#approve{background:#198038;color:white}#changes{background:#c72b29;color:white}textarea{width:100%;box-sizing:border-box;min-height:66px}.review-actions{display:flex;justify-content:space-between;align-items:center;width:100%;gap:16px}.review-actions button{min-width:150px}#remotion-canvas{background:#090b12}#status{padding:8px 0}#status:empty{display:none}#scene-thumbnails{display:flex;gap:7px;overflow-x:auto;padding:12px 2px;scrollbar-width:thin} .scene-pill{flex-shrink:0;padding:7px 11px;border:1px solid #d4dbe4;border-radius:9px;cursor:pointer;background:#f5f7fa;color:#475569;font-size:12px;white-space:nowrap} .scene-pill.active{background:#e7f0ff;color:#125ea2;border-color:#408bd7}</style></head>
+<body><main><header style="display:flex;justify-content:space-between;align-items:center"><h1>Markcut · <span id="video-md-version">video</span></h1><div style="display:flex;align-items:center;gap:14px;margin-left:auto"><span id="header-tts"></span><span id="player-version" style="font-size:12px;color:#667">v24</span></div></header><div class="path" id="path-label" hidden></div><div id="interactive-ui" hidden><div id="remotion-root"></div>
+<textarea id="feedback" aria-label="Feedback" placeholder="Feedback on this scene…"></textarea><div id="status" role="status">Starting preview…</div>
+<div class="review-actions"><button id="changes">Send feedback</button><button id="approve">Approve</button></div></div></main>
+<script src="${playerScriptUrl}"></script>
+<script>${buildPreviewBridgeScript().replaceAll("__MARKCUT_ORIGIN__",JSON.stringify(publicOrigin()))}</script></body></html>`;
 }

package/src/mcp/remote-assets.mjs

@@ -0,0 +1,185 @@
+import {readFileSync,mkdirSync,writeFileSync,existsSync,realpathSync,renameSync,copyFileSync,statSync} from "node:fs";
+import {homedir} from "node:os";
+import {join,resolve,sep,isAbsolute,extname} from "node:path";
+import {fileURLToPath} from "node:url";
+import {createHash} from "node:crypto";
+
+const supportDir = join(homedir(),"Library","Application Support","NeoY");
+export const EXPORT_ROOT = process.env.MARKCUT_EXPORT_ROOT || join(supportDir,"exports","_neoy","markcut");
+const DATA_URI = /data:(image|audio|video)\/[a-z0-9.+-]+(?:;base64)?,[a-z0-9%+\/=._~!$&()*,:;@?-]+/gi;
+const MAX_BYTES = 16 * 1024 * 1024;
+
+export function publicOrigin() {
+  if(process.env.NEOY_PUBLIC_ORIGIN) {
+    const url=new URL(process.env.NEOY_PUBLIC_ORIGIN);
+    if(url.protocol!=="https:")throw new Error("NeoY public origin requires HTTPS");
+    return url.origin;
+  }
+  const config=JSON.parse(readFileSync(join(supportDir,"deployment.json"),"utf8"));
+  if(config.tunnelMode==="named" && config.publicHostname) return "https://"+config.publicHostname;
+  const quick=join(supportDir,"public-url");
+  if(existsSync(quick)){
+    const url=new URL(readFileSync(quick,"utf8").trim());
+    if(url.protocol==="https:")return url.origin;
+  }
+  throw new Error("No public HTTPS URL configured for NeoY");
+}
+
+export function resolveMountedFile(path,origin=null,mountedRoots=null) {
+  let mounts=mountedRoots||{};
+  if(!mountedRoots)try{mounts=JSON.parse(readFileSync(join(supportDir,"file-mounts.json"),"utf8"));}catch{}
+  const absolute=resolve(path);
+  for(const [name,base] of Object.entries(mounts)){
+    if(!/^[a-z0-9_-]{1,64}$/i.test(name)||typeof base!=="string")continue;
+    const root=resolve(base);
+    if(!absolute.startsWith(root+sep))continue;
+    const relative=absolute.slice(root.length+1).split(sep);
+    if(relative.some(part=>part.startsWith(".")||part===".."||part===""))continue;
+    return (origin||publicOrigin())+"/files/"+encodeURIComponent(name)+"/"+relative.map(encodeURIComponent).join("/");
+  }
+  return null;
+}
+
+export function resolvePreviewPath(input, origin=publicOrigin(), mountedRoots=null) {
+  if(typeof input!=="string")throw new Error("Preview path must be a string");
+  if(isAbsolute(input) && !input.startsWith("/files/"))return input;
+  const url=new URL(input.startsWith("/files/") ? origin+input : input);
+  if(url.origin!==origin || url.search || url.hash || !url.pathname.startsWith("/files/"))
+    throw new Error("Only NeoY file URLs under /files/<mount>/ are accepted");
+  const parts=url.pathname.slice("/files/".length).split("/").map(decodeURIComponent);
+  const [name,...relative]=parts;
+  if(!name || name==="_neoy" || !/^[a-z0-9_-]{1,64}$/i.test(name) || !relative.length ||
+     relative.some(part=>!part || part==="." || part===".." || part.startsWith(".") || part.includes("/")))
+    throw new Error("Invalid mounted preview path");
+  let roots=mountedRoots||{};
+  if(!mountedRoots)try{roots=JSON.parse(readFileSync(join(supportDir,"file-mounts.json"),"utf8"));}catch{}
+  const base=roots[name];
+  if(typeof base!=="string" || !base.startsWith("/"))throw new Error("Unknown NeoY file mount: "+name);
+  const root=realpathSync(base);
+  const file=realpathSync(resolve(root,...relative));
+  if(!file.startsWith(root+sep))throw new Error("Preview path escapes NeoY mounted root");
+  return file;
+}
+
+export function publishPlayerBundle(bundlePath, origin=publicOrigin()) {
+  const bytes=readFileSync(bundlePath);
+  const hash=createHash("sha256").update(bytes).digest("hex").slice(0,20);
+  const directory=join(EXPORT_ROOT,"player");
+  mkdirSync(directory,{recursive:true});
+  const filename=hash+".js";
+  const target=join(directory,filename);
+  if(!existsSync(target))writeFileSync(target,bytes,{flag:"wx",mode:0o644});
+  return origin+"/files/_neoy/markcut/player/"+filename;
+}
+
+export function resolvePreviewSource(src,sourceDir,origin=publicOrigin(),mounts=null) {
+  if(src.startsWith("data:"))return src;
+  if(src.startsWith("https://"))return src;
+  if(src.startsWith("http://"))throw new Error("Preview media URL must be HTTPS");
+  if(src.startsWith("blob:"))throw new Error("Blob URLs cannot be shared with MCP App");
+  if(!sourceDir && !src.startsWith("file://") && !isAbsolute(src))return src;
+  const path=src.startsWith("file://")?fileURLToPath(src):isAbsolute(src)?src:resolve(sourceDir,src);
+  const mapped=resolveMountedFile(path,origin,mounts);
+  if(!mapped)throw new Error("Preview media file is not under a NeoY mounted root: "+path);
+  return mapped;
+}
+
+export function externalizePreviewMedia(compiled,revisionId,origin=publicOrigin(),sourceDir=null) {
+  if(!/^(?:[a-f0-9-]{36}|[a-f0-9]{64})$/i.test(revisionId))throw new Error("Invalid revision identity");
+  const directory=join(EXPORT_ROOT,"generated",revisionId);
+  const assets=[];
+  let bytes=0;
+  const frozenPaths=new Map();
+  function snapshotSource(src){
+    if(!sourceDir||src.startsWith("https://")||src.startsWith("data:"))return src;
+    if(src.startsWith("http://")||src.startsWith("blob:"))
+      throw new Error("Preview media must use HTTPS or local source files");
+    const full=src.startsWith("file://")?fileURLToPath(src):isAbsolute(src)?src:resolve(sourceDir,src);
+    const root=realpathSync(sourceDir);
+    let real;
+    try {real=realpathSync(full);} catch {return resolvePreviewSource(src,sourceDir,origin);}
+    if(!real.startsWith(root+sep))return resolvePreviewSource(src,sourceDir,origin);
+    if(frozenPaths.has(real))return frozenPaths.get(real);
+    const stats=statSync(real);
+    if(!stats.isFile()||stats.size>512*1024*1024)throw new Error("Preview local media must be a file of at most 512 MB");
+    const ext=extname(real).toLowerCase();
+    if(!/^[.](png|jpg|jpeg|webp|svg|gif|mp4|mov|webm|wav|mp3|m4a|ogg|vtt|srt)$/.test(ext))
+      throw new Error("Unsupported local preview media extension: "+ext);
+    mkdirSync(directory,{recursive:true});
+    const filename="file-"+frozenPaths.size+ext;
+    const target=join(directory,filename);
+    if(existsSync(target)){
+      const existing=statSync(target);
+      if(existing.size!==stats.size)throw new Error("Immutable preview media collision");
+    }else copyFileSync(real,target);
+    const url=origin+"/files/_neoy/markcut/generated/"+revisionId+"/"+filename;
+    frozenPaths.set(real,url);
+    assets.push(filename);
+    return url;
+  }
+  function replace(value){
+    if(typeof value==="string"){
+      if(/https?:\/\/(?:localhost|127\.0\.0\.1)(?=[:/]|$)/i.test(value))
+        throw new Error("Preview contains local media URL");
+      const converted = sourceDir ? value.replace(/(\bsrc\s*=\s*)(['"])([^'"\n]+)\2/g,
+        (all,prefix,quote,path)=>prefix+quote+snapshotSource(path)+quote) : value;
+      return converted.replace(DATA_URI,uri=>{
+        const comma=uri.indexOf(",");
+        const mime=uri.slice(5,comma).split(";")[0].toLowerCase();
+        const data=uri.slice(comma+1);
+        const buffer=uri.slice(0,comma).includes(";base64") ? Buffer.from(data,"base64") : Buffer.from(decodeURIComponent(data));
+        bytes+=buffer.length;
+        if(bytes>MAX_BYTES||assets.length>=64)throw new Error("Preview media asset limit exceeded");
+        const ext=({ "audio/wav":"wav","audio/mpeg":"mp3","audio/mp4":"m4a","audio/ogg":"ogg",
+          "image/png":"png","image/jpeg":"jpg","image/webp":"webp","image/svg+xml":"svg","video/mp4":"mp4" })[mime];
+        if(!ext)throw new Error("Unsupported media MIME type: "+mime);
+        mkdirSync(directory,{recursive:true});
+        const filename=assets.length+"."+ext;
+        const target=join(directory,filename);
+        if(existsSync(target)) {
+          if(!readFileSync(target).equals(buffer))throw new Error("Immutable preview asset collision");
+        }else writeFileSync(target,buffer,{flag:"wx",mode:0o644});
+        assets.push(filename);
+        return origin+"/files/_neoy/markcut/generated/"+revisionId+"/"+filename;
+      });
+    }
+    if(Array.isArray(value))return value.map(replace);
+    if(value&&typeof value==="object")return Object.fromEntries(Object.entries(value).map(([key,v])=>
+      [key,key==="src" && typeof v==="string" && !v.startsWith("data:")
+        ? snapshotSource(v) : replace(v)]));
+    return value;
+  }
+  return {compiled:replace(compiled),assets};
+}
+
+// Fallback for hosts that deliver tool-input but omit tool-result notifications.
+export function publishPreviewRevision(requestedPath,payload) {
+  const key=createHash("sha256").update(requestedPath).digest("hex");
+  const dir=join(EXPORT_ROOT,"revisions");
+  mkdirSync(dir,{recursive:true});
+  const target=join(dir,key+".json");
+  const temp=join(dir,key+"."+process.pid+".tmp");
+  writeFileSync(temp,JSON.stringify(payload),{mode:0o644});
+  renameSync(temp,target);
+  return publicOrigin()+"/files/_neoy/markcut/revisions/"+key+".json";
+}
+
+
+export function publishCompiledCache(hash, compiled, origin=publicOrigin()) {
+  if(!/^[a-f0-9]{64}$/.test(hash))throw new Error("Invalid compiled hash");
+  const dir=join(EXPORT_ROOT,"cache");
+  mkdirSync(dir,{recursive:true});
+  const file=join(dir,hash+".json");
+  const bytes=JSON.stringify(compiled);
+  if(existsSync(file)){
+    if(readFileSync(file,"utf8")!==bytes)throw new Error("Immutable compiled cache collision");
+  }else writeFileSync(file,bytes,{flag:"wx",mode:0o644});
+  return origin+"/files/_neoy/markcut/cache/"+hash+".json";
+}
+
+export async function prunePublishedCache(hash) {
+  if(!/^[a-f0-9]{64}$/.test(hash))throw new Error("Invalid compiled hash");
+  const {rm}=await import("node:fs/promises");
+  await rm(join(EXPORT_ROOT,"cache",hash+".json"),{force:true});
+  await rm(join(EXPORT_ROOT,"generated",hash),{recursive:true,force:true});
+}