@lalalic/markcut 3.2.11 → 3.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "3.2.11",
+  "version": "3.2.13",
   "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
   "bin": {
     "markcut": "bin/markcut"

package/src/mcp/bridge.mjs

@@ -1,13 +1,14 @@
 export function buildPreviewBridgeScript(submitToolName) {
   return `
-const feedback=document.getElementById('feedback'),status=document.getElementById('status'),article=document.querySelector('article'),pathLabel=document.querySelector('main>p code');
+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}));}
-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.markdown==='string'){article.innerHTML=data.markdown.split(/\\r?\\n/).map(line=>{const escaped=line.replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));if(line.startsWith('### '))return '<h3>'+escaped.slice(4)+'</h3>';if(line.startsWith('## '))return '<h2>'+escaped.slice(3)+'</h2>';if(line.startsWith('# '))return '<h1>'+escaped.slice(2)+'</h1>';if(line.startsWith('- '))return '<li>'+escaped.slice(2)+'</li>';return line.trim()?'<p>'+escaped+'</p>':''}).join('\\n');}}
+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.0.0'},appCapabilities:{},protocolVersion:'2026-01-26'});send({jsonrpc:'2.0',method:'ui/notifications/initialized'});status.textContent='Ready for review.';}catch(error){status.textContent=error.message||'MCP initialization failed.';}}
+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');

package/src/mcp/preview.mjs

@@ -1,10 +1,44 @@
-import { readFile } from "node:fs/promises";
-import { isAbsolute, extname } from "node:path";
+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 { fileURLToPath } from "node:url";
 import { buildPreviewBridgeScript } from "./bridge.mjs";
 
 export const TOOL_NAME = "markcut.preview";
 export const SUBMIT_TOOL_NAME = "markcut.preview.submit";
-export const RESOURCE_URI = "ui://markcut/markdown-preview-v2.html";
+export const RESOURCE_URI = "ui://markcut/video-preview-v3.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}`;
+
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const playerServer = resolve(moduleDir, "../player/server.mjs");
+let managedPlayer = null;
+let managedPath = null;
+let startPromise = null;
+
+export function buildPreviewResourceResult() {
+  return {
+    ttlMs: 0,
+    cacheScope: "private",
+    contents: [{
+      uri: RESOURCE_URI,
+      mimeType: RESOURCE_MIME_TYPE,
+      text: buildPreviewHtml(),
+      _meta: {
+        ui: {
+          prefersBorder: true,
+          csp: {
+            connectDomains: [PLAYER_ORIGIN],
+            resourceDomains: [],
+            frameDomains: [PLAYER_ORIGIN],
+          },
+        },
+      },
+    }],
+  };
+}
 
 export function validateMarkdownPath(value) {
   if (typeof value !== "string" || !isAbsolute(value)) {
@@ -16,13 +50,59 @@ export function validateMarkdownPath(value) {
   return value;
 }
 
-export async function readMarkdownPreview(path) {
+export async function ensureVideoPreview(path, options = {}) {
   const validatedPath = validateMarkdownPath(path);
-  try {
-    return { path: validatedPath, markdown: await readFile(validatedPath, "utf8") };
-  } catch (error) {
-    throw new Error(`unable to read Markdown file: ${error instanceof Error ? error.message : String(error)}`);
+  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;
+
+  if (managedPlayer && managedPlayer.exitCode == null && !managedPlayer.killed) {
+    managedPlayer.kill("SIGTERM");
   }
+  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"],
+    });
+    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()}` : ""}`));
+    });
+    setTimeout(() => {
+      if (!settled) finish();
+    }, settleMs);
+  });
+  return startPromise;
+}
+
+export function stopManagedVideoPreview() {
+  if (managedPlayer && managedPlayer.exitCode == null && !managedPlayer.killed) managedPlayer.kill("SIGTERM");
+  managedPlayer = null;
+  managedPath = null;
+  startPromise = null;
 }
 
 export function reviewResult(decision, feedback = "") {
@@ -40,38 +120,16 @@ export function reviewMessage(result) {
   return {
     jsonrpc: "2.0",
     method: "ui/message",
-    params: {
-      role: "user",
-      content: [{ type: "text", text: JSON.stringify(normalized) }],
-    },
+    params: { role: "user", content: [{ type: "text", text: JSON.stringify(normalized) }] },
   };
 }
 
-function escapeHtml(value) {
-  return value.replace(/[&<>"']/g, (character) => ({
-    "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;",
-  })[character]);
-}
-
-function renderMarkdown(markdown) {
-  return markdown.split(/\r?\n/).map((line) => {
-    const escaped = escapeHtml(line);
-    if (line.startsWith("### ")) return `<h3>${escaped.slice(4)}</h3>`;
-    if (line.startsWith("## ")) return `<h2>${escaped.slice(3)}</h2>`;
-    if (line.startsWith("# ")) return `<h1>${escaped.slice(2)}</h1>`;
-    if (line.startsWith("- ")) return `<li>${escaped.slice(2)}</li>`;
-    return line.trim() ? `<p>${escaped}</p>` : "";
-  }).join("\n");
-}
-
-export function buildPreviewHtml({ path = "", markdown = "" }) {
-  const safePath = escapeHtml(path);
-  const rendered = renderMarkdown(markdown);
+export function buildPreviewHtml() {
   return `<!doctype html>
-<html><head><meta charset="utf-8"><title>MarkCut Markdown review</title>
-<style>body{font:15px system-ui,sans-serif;margin:0;padding:24px;color:#17202a;background:#fff}main{max-width:860px;margin:auto}article{border:1px solid #d8dee4;border-radius:8px;padding:20px;overflow:auto}h1,h2,h3{margin-top:0}p{line-height:1.5}textarea{box-sizing:border-box;width:100%;min-height:100px;margin:16px 0 10px;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;color:#cf222e}</style></head>
-<body><main><h1>Review Markdown</h1><p><code>${safePath}</code></p><article>${rendered}</article>
-<label for="feedback">Feedback (required for requested changes)</label><textarea id="feedback" placeholder="What should be changed?"></textarea><div id="status" role="status"></div>
+<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>`;
 }

package/src/mcp/server.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/server";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
-import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import { registerAppResource, registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import { z } from "zod";
 import {
-  TOOL_NAME, SUBMIT_TOOL_NAME, RESOURCE_URI, buildPreviewHtml, readMarkdownPreview, reviewResult,
+  TOOL_NAME, SUBMIT_TOOL_NAME, RESOURCE_URI, PLAYER_ORIGIN, buildPreviewResourceResult, ensureVideoPreview, reviewResult,
 } from "./preview.mjs";
 
 const server = new McpServer({ name: "markcut", version: "3.2.0" });
@@ -13,7 +13,7 @@ registerAppTool(
   server,
   TOOL_NAME,
   {
-    description: "Ask a human to review a Markdown file and return an approval or requested changes.",
+    description: "Show the Markcut video player for a Markdown video definition and ask a human to approve it or request changes.",
     inputSchema: z.object({
       path: z.string().describe("Absolute path to a .md file"),
     }),
@@ -23,9 +23,9 @@ registerAppTool(
   },
   async ({ path }) => {
     try {
-      const preview = await readMarkdownPreview(path);
+      const preview = await ensureVideoPreview(path);
       return {
-        content: [{ type: "text", text: `Markdown ready for review: ${preview.path}` }],
+        content: [{ type: "text", text: `Video ready for review: ${preview.path}` }],
         structuredContent: { ...preview, resourceUri: RESOURCE_URI },
         _meta: {
           ui: { resourceUri: RESOURCE_URI, props: preview },
@@ -45,7 +45,7 @@ registerAppTool(
   server,
   SUBMIT_TOOL_NAME,
   {
-    description: "Submit the review decision from the Markdown preview UI.",
+    description: "Submit the review decision from the Markcut video preview UI.",
     inputSchema: z.object({
       decision: z.enum(["approved", "changes_requested"]),
       feedback: z.string().optional(),
@@ -72,29 +72,17 @@ registerAppTool(
 
 registerAppResource(
   server,
-  "MarkCut Markdown review",
+  "Markcut video review",
   RESOURCE_URI,
   {
     _meta: {
       ui: {
         prefersBorder: true,
-        csp: { connectDomains: [], resourceDomains: [] },
+        csp: { connectDomains: [PLAYER_ORIGIN], resourceDomains: [], frameDomains: [PLAYER_ORIGIN] },
       },
     },
   },
-  async () => ({
-    contents: [{
-      uri: RESOURCE_URI,
-      mimeType: RESOURCE_MIME_TYPE,
-      text: buildPreviewHtml({ path: "", markdown: "" }),
-      _meta: {
-        ui: {
-          prefersBorder: true,
-          csp: { connectDomains: [], resourceDomains: [] },
-        },
-      },
-    }],
-  }),
+  async () => buildPreviewResourceResult(),
 );
 
 await server.connect(new StdioServerTransport());

package/src/player/server.mjs

@@ -1158,6 +1158,18 @@ Edit request: ${text}`;
       return;
     }
 
+    // API: lightweight readiness probe for embedded MCP App previews.
+    if (path === "/api/ready" && req.method === "GET") {
+      const ready = compiledRootCache.has(variantLabel);
+      res.writeHead(200, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+        "Access-Control-Allow-Origin": "*",
+      });
+      res.end(JSON.stringify({ ready }));
+      return;
+    }
+
     // API: Get video.json data for a specific variant
     if (path === "/api/video-data") {
       try {

package/tests/mcp-preview.test.ts

@@ -3,7 +3,16 @@ import { mkdtempSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import vm from "node:vm";
-import { buildPreviewHtml, readMarkdownPreview, reviewMessage, reviewResult, validateMarkdownPath } from "../src/mcp/preview.mjs";
+import {
+  buildPreviewHtml,
+  buildPreviewResourceResult,
+  PLAYER_ORIGIN,
+  RESOURCE_MIME_TYPE,
+  RESOURCE_URI,
+  reviewMessage,
+  reviewResult,
+  validateMarkdownPath,
+} from "../src/mcp/preview.mjs";
 import { buildPreviewBridgeScript } from "../src/mcp/bridge.mjs";
 
 describe("MarkCut MCP Markdown preview", () => {
@@ -12,21 +21,29 @@ describe("MarkCut MCP Markdown preview", () => {
     expect(() => validateMarkdownPath("/tmp/notes.txt")).toThrow(/Markdown/);
   });
 
-  it("reads Markdown and builds a reviewable UI resource", async () => {
-    const directory = mkdtempSync(join(tmpdir(), "markcut-mcp-"));
-    const path = join(directory, "review.md");
-    writeFileSync(path, "# Hello\n\nThis is a review.");
-    const preview = await readMarkdownPreview(path);
-    const html = buildPreviewHtml(preview);
-    expect(preview.markdown).toContain("# Hello");
-    expect(html).toContain("This is a review.");
+  it("builds a video-player review UI instead of rendering Markdown", () => {
+    const html = buildPreviewHtml();
+    expect(html).toContain('id="video-player"');
+    expect(html).toContain("Review video");
     expect(html).toContain("Approve");
     expect(html).toContain("Request changes");
-    expect(html).toContain("ui/initialize");
     expect(html).toContain("ui/notifications/tool-result");
-    expect(html).toContain("tools/call");
-    expect(html).toContain("ui/message");
-    expect(html).toContain("review.md");
+    expect(html).toContain("previewUrl");
+    expect(html).not.toContain("<article>");
+  });
+
+  it("returns Codex-compatible private no-cache resource metadata", () => {
+    const result = buildPreviewResourceResult();
+    expect(result.ttlMs).toBe(0);
+    expect(result.cacheScope).toBe("private");
+    expect(result.contents).toHaveLength(1);
+    expect(result.contents[0]).toMatchObject({
+      uri: RESOURCE_URI,
+      mimeType: RESOURCE_MIME_TYPE,
+    });
+    expect(result.contents[0].text).toContain("ui/initialize");
+    expect(result.contents[0].text).toContain("ui/notifications/initialized");
+    expect(result.contents[0]._meta.ui.csp.frameDomains).toEqual([PLAYER_ORIGIN]);
   });
 
   it("returns approved", () => {
@@ -58,7 +75,7 @@ describe("MarkCut MCP Markdown preview", () => {
       id: 1,
       method: "ui/initialize",
       params: {
-        appInfo: { name: "Markcut Preview", version: "1.0.0" },
+        appInfo: { name: "Markcut Preview", version: "1.1.0" },
         appCapabilities: {},
         protocolVersion: "2026-01-26",
       },
@@ -76,6 +93,11 @@ describe("MarkCut MCP Markdown preview", () => {
     await tick();
     expect(harness.messages[1]).toMatchObject({ method: "ui/notifications/initialized" });
 
+    harness.toolResult({ path: "/tmp/video.md", previewUrl: PLAYER_ORIGIN + "/" });
+    await tick();
+    expect(harness.elements.player.src).toBe(PLAYER_ORIGIN + "/");
+    expect(harness.elements.pathLabel.textContent).toBe("/tmp/video.md");
+
     harness.elements.approve.onclick();
     expect(harness.messages[2]).toMatchObject({ id: 2, method: "tools/call" });
     expect(harness.messages).not.toContainEqual(expect.objectContaining({ method: "ui/message" }));
@@ -114,23 +136,30 @@ function createBridgeHarness() {
   const elements = {
     feedback: element(),
     status: element(),
-    article: element(),
+    player: element(),
     pathLabel: element(),
     approve: element(),
     changes: element(),
   };
   const parent = { postMessage(message: any) { messages.push(message); } };
   const document = {
-    getElementById(id: string) { return id === "feedback" ? elements.feedback : id === "status" ? elements.status : id === "approve" ? elements.approve : elements.changes; },
-    querySelector(selector: string) { return selector === "article" ? elements.article : elements.pathLabel; },
+    getElementById(id: string) {
+      if (id === "feedback") return elements.feedback;
+      if (id === "status") return elements.status;
+      if (id === "video-player") return elements.player;
+      if (id === "path-label") return elements.pathLabel;
+      if (id === "approve") return elements.approve;
+      return elements.changes;
+    },
   };
   const window = { parent, addEventListener(_type: string, listener: (event: any) => void) { listeners.push(listener); } };
-  const context = vm.createContext({ window, document });
+  const context = vm.createContext({ window, document, setTimeout, fetch: async () => ({ ok: true, json: async () => ({ ready: true }) }) });
   return {
     messages,
     elements,
     run() { vm.runInContext(buildPreviewBridgeScript("markcut.preview.submit"), context); },
     dispatch(event: any) { listeners.forEach((listener) => listener(event)); },
     respond(message: any) { this.dispatch({ source: parent, data: { jsonrpc: "2.0", ...message } }); },
+    toolResult(structuredContent: any) { this.dispatch({ source: parent, data: { jsonrpc: "2.0", method: "ui/notifications/tool-result", params: { result: { structuredContent } } } }); },
   };
 }