@lalalic/markcut 3.2.5 → 3.2.7

package/.env.example

@@ -25,3 +25,13 @@ GOOGLE_MAPS_API_KEY=your_key_here
 # MARKCUT_MAX_VIDEO_DURATION=60
 # MARKCUT_MAX_VIDEO_DIMENSION=360
 # MARKCUT_VTT_SAMPLE_INTERVAL=5
+# ── Default Vision backend policy ────────────────────────────────────────────
+# Browser ChatGPT Temporary Chat is attempted first when this command exists.
+# MARKCUT_CHATGPT_BROWSER_INFER_CLI=/path/to/chatgpt-browser-infer
+# Codex fallback profiles are tried left-to-right; `default` means no -p flag.
+# MARKCUT_CODEX_VISION_PROFILES=zai,default
+# MARKCUT_CHATGPT_VISION_TIMEOUT_MS=600000
+# MARKCUT_CODEX_VISION_TIMEOUT_MS=600000
+# Local MLX is final fallback only.
+# MARKCUT_LOCAL_VISION_MODEL=mlx-community/MiniCPM-V-4.6-bf16
+# MARKCUT_LOCAL_VISION_TIMEOUT_MS=600000

package/README.md

@@ -341,4 +341,32 @@ flowchart LR
 | `--dry-run` | Show what would be processed without running AI |
 | `--show-prompts` | Print the prompts template file and exit |
 
+### Default Vision backend priority
+
+Markcut Vision is remote-first by default so ordinary perception does not require a heavy local VLM on the host Mac. Explicit `--itt` / `--vtt` flags and `MARKCUT_ITT_CLI` / `MARKCUT_VTT_CLI` environment variables still override these defaults.
+
+Default ITT tries, in order:
+
+1. **Browser ChatGPT Temporary Chat** through `chatgpt-browser-infer` (or `MARKCUT_CHATGPT_BROWSER_INFER_CLI`). The Neo runtime owns browser automation, isolation, attachment readiness, retries, and cleanup.
+2. **Codex CLI remote vision**, trying profiles from `MARKCUT_CODEX_VISION_PROFILES` (default `zai,default`). On this Mac that means the lightweight Z.ai profile first, then the normal Codex/OpenAI profile.
+3. **Local MLX MiniCPM** as the final fallback only. Override its model with `MARKCUT_LOCAL_VISION_MODEL`.
+
+Default VTT is intentionally empty. Markcut therefore performs its existing deterministic chronological frame extraction (5–10 representative frames, controlled by `--vtt-sample-interval`) and sends those frames through the same ITT priority chain. Set `--vtt` or `MARKCUT_VTT_CLI` when a dedicated video backend is explicitly desired.
+
+To expose the Neo Browser ChatGPT runtime on this Mac:
+
+```bash
+ln -sf "$HOME/Workspace/neo/skills/chatgpt-browser-worker/bin/chatgpt-browser-infer" "$HOME/.local/bin/chatgpt-browser-infer"
+```
+
+Useful policy overrides:
+
+```bash
+export MARKCUT_CODEX_VISION_PROFILES='zai,default'
+export MARKCUT_CHATGPT_BROWSER_INFER_CLI='/path/to/chatgpt-browser-infer'
+# Explicit custom backends still win:
+export MARKCUT_ITT_CLI='my-image-backend --prompt "{prompt}" {input}'
+export MARKCUT_VTT_CLI='my-video-backend --prompt "{prompt}" {input}'
+```
+
 ## Architecture

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "3.2.5",
+  "version": "3.2.7",
   "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
   "bin": {
     "markcut": "bin/markcut"
@@ -22,6 +22,7 @@
     "render:demo": "node src/render/cli.mjs render src/demo-components.json",
     "templates": "node src/render/cli.mjs templates",
     "preview": "node src/render/cli.mjs preview",
+    "mcp": "node src/mcp/server.mjs",
     "verify": "node src/render/cli.mjs verify",
     "resolve": "node src/render/cli.mjs resolve",
     "render:pixelle": "remotion render examples/pixelle/index.tsx Root out/pixelle-asset-default.mp4 --props=./examples/pixelle/asset-default.json",
@@ -37,6 +38,7 @@
   },
   "dependencies": {
     "@babel/standalone": "^8.0.3",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@remotion/cli": "4.0.469",
     "@remotion/media-parser": "4.0.469",
     "@remotion/media-utils": "4.0.469",

package/src/config.mjs

@@ -1,3 +1,5 @@
+import { fileURLToPath } from "node:url";
+
 /**
  * Default CLI templates and constants for the markcut pipeline.
  *
@@ -96,7 +98,8 @@ export const DEFAULT_EDIT_CLI = args.cliOverrides.editCli || process.env.MARKCUT
 export const DEFAULT_TTI_CLI = args.cliOverrides.tti || process.env.MARKCUT_TTI_CLI || 'uvx --from mflux mflux-generate-flux2 --model flux2-klein-4b --steps 2 --prompt "{input}" --output "{output}" --seed {seed}';
 /** Text-to-video CLI. Override via --ttv flag or MARKCUT_TTV_CLI env var. */
 export const DEFAULT_TTV_CLI = args.cliOverrides.ttv || process.env.MARKCUT_TTV_CLI || '';
+const DEFAULT_VISION_INFER = fileURLToPath(new URL("./vision/default-infer.mjs", import.meta.url));
 /** Image-to-text CLI. Override via --itt flag or MARKCUT_ITT_CLI env var. */
-export const DEFAULT_ITT_CLI = args.cliOverrides.itt || process.env.MARKCUT_ITT_CLI || 'uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --image {input} --temperature 0.0 --thinking-mode disabled';;
-/** Video-to-text CLI. Override via --vtt flag or MARKCUT_VTT_CLI env var. */
-export const DEFAULT_VTT_CLI = args.cliOverrides.vtt || process.env.MARKCUT_VTT_CLI || 'uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/MiniCPM-V-4.6-bf16 --max-tokens 2048 --prompt "{prompt}" --video {input} --temperature 0.0 --processor-kwargs \'{"max_num_frames": 32, "stack_frames": 1, "max_slice_nums": 1, "use_image_id": false}\'';
+export const DEFAULT_ITT_CLI = args.cliOverrides.itt || process.env.MARKCUT_ITT_CLI || `node ${JSON.stringify(DEFAULT_VISION_INFER)} --prompt "{prompt}" {input}`;
+/** Video-to-text CLI. Override via --vtt flag or MARKCUT_VTT_CLI env var. Empty by default so Vision uses chronological frame extraction through ITT. */
+export const DEFAULT_VTT_CLI = args.cliOverrides.vtt || process.env.MARKCUT_VTT_CLI || '';

package/src/mcp/bridge.mjs

@@ -0,0 +1,15 @@
+export function buildPreviewBridgeScript(submitToolName) {
+  return `
+const feedback=document.getElementById('feedback'),status=document.getElementById('status'),article=document.querySelector('article'),pathLabel=document.querySelector('main>p code');
+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');}}
+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',{protocolVersion:'2026-01-26',capabilities:{},clientInfo:{name:'markcut-preview',version:'1'}});send({jsonrpc:'2.0',method:'ui/notifications/initialized'});status.textContent='Ready for review.';}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});send({jsonrpc:'2.0',method:'ui/message',params:{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

@@ -0,0 +1,77 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, extname } from "node:path";
+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.html";
+
+export function validateMarkdownPath(value) {
+  if (typeof value !== "string" || !isAbsolute(value)) {
+    throw new Error("path must be an absolute filesystem path");
+  }
+  if (extname(value).toLowerCase() !== ".md") {
+    throw new Error("path must point to a Markdown file (.md)");
+  }
+  return value;
+}
+
+export async function readMarkdownPreview(path) {
+  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)}`);
+  }
+}
+
+export function reviewResult(decision, feedback = "") {
+  if (decision === "approved") return { decision };
+  if (decision === "changes_requested") {
+    const normalized = typeof feedback === "string" ? feedback.trim() : "";
+    if (!normalized) throw new Error("feedback is required when requesting changes");
+    return { decision, feedback: normalized };
+  }
+  throw new Error(`unsupported review decision: ${String(decision)}`);
+}
+
+export function reviewMessage(result) {
+  const normalized = reviewResult(result?.decision, result?.feedback);
+  return {
+    jsonrpc: "2.0",
+    method: "ui/message",
+    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);
+  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>
+<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

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  TOOL_NAME, SUBMIT_TOOL_NAME, RESOURCE_URI, buildPreviewHtml, readMarkdownPreview, reviewResult,
+} from "./preview.mjs";
+
+const server = new Server(
+  { name: "markcut", version: "3.2.0" },
+  { capabilities: { tools: {}, resources: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [{
+    name: TOOL_NAME,
+    description: "Ask a human to review a Markdown file and return an approval or requested changes.",
+    inputSchema: {
+      type: "object", properties: { path: { type: "string", description: "Absolute path to a .md file" } },
+      required: ["path"], additionalProperties: false,
+    },
+    _meta: { "ui/resourceUri": RESOURCE_URI, ui: { resourceUri: RESOURCE_URI } },
+  }, {
+    name: SUBMIT_TOOL_NAME,
+    description: "Submit the review decision from the Markdown preview UI.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        decision: { type: "string", enum: ["approved", "changes_requested"] },
+        feedback: { type: "string" },
+      },
+      required: ["decision"], additionalProperties: false,
+    },
+    _meta: { ui: { visibility: ["app"] } },
+  }],
+}));
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [{ uri: RESOURCE_URI, name: "MarkCut Markdown review", mimeType: "text/html;profile=mcp-app" }],
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => ({
+  contents: [{ uri: RESOURCE_URI, mimeType: "text/html;profile=mcp-app", text: buildPreviewHtml({ path: "", markdown: "" }) }],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  try {
+    const input = request.params.arguments ?? {};
+    if (request.params.name === SUBMIT_TOOL_NAME) {
+      const decision = reviewResult(input.decision, input.feedback);
+      return { content: [{ type: "text", text: JSON.stringify(decision) }], structuredContent: decision };
+    }
+    if (request.params.name !== TOOL_NAME) throw new Error(`unknown tool: ${request.params.name}`);
+    const { path, markdown } = await readMarkdownPreview(input.path);
+    return {
+      content: [{ type: "text", text: `Markdown ready for review: ${path}` }],
+      structuredContent: { path, markdown, resourceUri: RESOURCE_URI },
+      _meta: {
+        "ui/resourceUri": RESOURCE_URI,
+        ui: { resourceUri: RESOURCE_URI, props: { path, markdown } },
+      },
+    };
+  } catch (error) {
+    return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+  }
+});
+
+await server.connect(new StdioServerTransport());

package/src/vision/cli.mjs

@@ -395,7 +395,8 @@ function extractVideoFrames(videoPath, intervalSeconds = DEFAULT_VTT_SAMPLE_INTE
   catch (e) { try { rmSync(tmpDir, { recursive: true, force: true }); } catch {} throw new Error(`Frame extraction failed: ${e.message}`); }
   const frames = readdirSync(tmpDir).filter((f) => f.startsWith(baseName) && f.endsWith(".jpg")).sort().map((f) => join(tmpDir, f));
   if (frames.length === 0) { try { rmSync(tmpDir, { recursive: true, force: true }); } catch {} throw new Error("No frames extracted from video"); }
-  return { frames, cleanup: () => { try { rmSync(tmpDir, { recursive: true, force: true }); } catch {} } };
+  const timing = frames.map((frame, i) => ({ frame, seconds: ((i + 0.5) * Math.max(duration || 5, 1)) / frames.length }));
+  return { frames, timing, cleanup: () => { try { rmSync(tmpDir, { recursive: true, force: true }); } catch {} } };
 }
 
 function runVTT(videoPath, promptText, vttCli, ittCli, sampleInterval = DEFAULT_VTT_SAMPLE_INTERVAL) {
@@ -416,7 +417,11 @@ function runVTT(videoPath, promptText, vttCli, ittCli, sampleInterval = DEFAULT_
   let extracted;
   try { extracted = extractVideoFrames(videoPath, sampleInterval); }
   catch (e) { emitWarn(`  ${e.message}`); return ""; }
-  const result = runITT(extracted.frames, promptText, ittCli);
+  const timingContext = extracted.timing
+    .map((item, i) => `Frame ${i + 1}: approximately ${item.seconds.toFixed(1)}s`)
+    .join("\n");
+  const framePrompt = `${promptText}\n\nThe attached frames are ordered chronologically. Approximate timing:\n${timingContext}`;
+  const result = runITT(extracted.frames, framePrompt, ittCli);
   extracted.cleanup();
   return result;
 }

package/src/vision/default-infer.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const LOCAL_MODEL = process.env.MARKCUT_LOCAL_VISION_MODEL || "mlx-community/MiniCPM-V-4.6-bf16";
+
+function parseArgs(argv) {
+  let prompt = "";
+  const inputs = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--prompt") prompt = argv[++i] || "";
+    else if (arg === "--input") inputs.push(argv[++i]);
+    else if (arg && !arg.startsWith("--")) inputs.push(arg.startsWith("@") ? arg.slice(1) : arg);
+  }
+  return { prompt, inputs: inputs.filter(Boolean) };
+}
+
+function which(name) {
+  if (!name) return "";
+  const candidates = name.includes("/") ? [name] : (process.env.PATH || "").split(":").filter(Boolean).map(dir => join(dir, name));
+  for (const candidate of candidates) {
+    try { accessSync(candidate, constants.X_OK); return candidate; } catch {}
+  }
+  return "";
+}
+
+function run(command, args, options = {}) {
+  const r = spawnSync(command, args, { encoding: "utf8", timeout: options.timeout || 600_000, env: process.env });
+  return { ok: r.status === 0, stdout: (r.stdout || "").trim(), stderr: (r.stderr || "").trim(), status: r.status };
+}
+
+function tryBrowser(prompt, inputs) {
+  const explicit = process.env.MARKCUT_CHATGPT_BROWSER_INFER_CLI || "";
+  const command = explicit || which("chatgpt-browser-infer");
+  if (!command) return { ok: false, reason: "browser-infer-unavailable" };
+  const args = ["--prompt", prompt];
+  for (const input of inputs) args.push("--file", input);
+  const r = run(command, args, { timeout: Number(process.env.MARKCUT_CHATGPT_VISION_TIMEOUT_MS) || 600_000 });
+  return r.ok && r.stdout ? { ok: true, output: r.stdout } : { ok: false, reason: r.stderr || `browser-infer-exit-${r.status}` };
+}
+
+function tryCodex(prompt, inputs) {
+  const codex = which("codex");
+  if (!codex) return { ok: false, reason: "codex-unavailable" };
+  const profiles = (process.env.MARKCUT_CODEX_VISION_PROFILES || "zai,default").split(",").map(s => s.trim()).filter(Boolean);
+  const errors = [];
+  for (const profile of profiles) {
+    const dir = mkdtempSync(join(tmpdir(), "markcut-codex-vision-"));
+    const output = join(dir, "result.txt");
+    const args = ["exec", "--ephemeral", "--skip-git-repo-check"];
+    if (profile !== "default") args.push("-p", profile);
+    if (inputs.length) args.push("-i", ...inputs);
+    args.push("-o", output, prompt);
+    const r = run(codex, args, { timeout: Number(process.env.MARKCUT_CODEX_VISION_TIMEOUT_MS) || 600_000 });
+    let text = "";
+    if (existsSync(output)) text = readFileSync(output, "utf8").trim();
+    rmSync(dir, { recursive: true, force: true });
+    if (r.ok && text) return { ok: true, output: text };
+    errors.push(`${profile}:${r.stderr || `exit-${r.status}`}`);
+  }
+  return { ok: false, reason: errors.join("; ") || "codex-failed" };
+}
+
+function tryLocal(prompt, inputs) {
+  const uvx = which("uvx");
+  if (!uvx) return { ok: false, reason: "uvx-unavailable" };
+  const args = ["--from", "mlx-vlm", "mlx_vlm.generate", "--model", LOCAL_MODEL, "--max-tokens", "2048", "--prompt", prompt, "--image", ...inputs, "--temperature", "0.0", "--thinking-mode", "disabled"];
+  const r = run(uvx, args, { timeout: Number(process.env.MARKCUT_LOCAL_VISION_TIMEOUT_MS) || 600_000 });
+  return r.ok && r.stdout ? { ok: true, output: r.stdout } : { ok: false, reason: r.stderr || `local-vlm-exit-${r.status}` };
+}
+
+export function infer({ prompt, inputs }) {
+  if (!prompt) throw new Error("--prompt is required");
+  if (!inputs?.length) throw new Error("at least one image input is required");
+
+  const attempts = [
+    ["browser-chatgpt", () => tryBrowser(prompt, inputs)],
+    ["codex", () => tryCodex(prompt, inputs)],
+    ["local-vlm", () => tryLocal(prompt, inputs)],
+  ];
+  const failures = [];
+  for (const [name, fn] of attempts) {
+    const result = fn();
+    if (result.ok) return result.output;
+    failures.push(`${name}: ${result.reason}`);
+  }
+  throw new Error(`all vision backends failed (${failures.join(" | ")})`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    const { prompt, inputs } = parseArgs(process.argv.slice(2));
+    process.stdout.write(infer({ prompt, inputs }) + "\n");
+  } catch (error) {
+    process.stderr.write(`${error?.message || error}\n`);
+    process.exit(1);
+  }
+}

package/tests/mcp-preview.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+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 { buildPreviewBridgeScript } from "../src/mcp/bridge.mjs";
+
+describe("MarkCut MCP Markdown preview", () => {
+  it("requires an absolute .md path", () => {
+    expect(() => validateMarkdownPath("notes.md")).toThrow(/absolute/);
+    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.");
+    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");
+  });
+
+  it("returns approved", () => {
+    expect(reviewResult("approved")).toEqual({ decision: "approved" });
+  });
+
+  it("requires non-empty feedback for requested changes", () => {
+    expect(() => reviewResult("changes_requested", "  ")).toThrow(/feedback is required/);
+    expect(reviewResult("changes_requested", " Fix the title ")).toEqual({
+      decision: "changes_requested", feedback: "Fix the title",
+    });
+  });
+
+  it("formats decisions as an MCP Apps ui/message notification", () => {
+    expect(reviewMessage({ decision: "approved" })).toEqual({
+      jsonrpc: "2.0",
+      method: "ui/message",
+      params: { role: "user", content: [{ type: "text", text: '{"decision":"approved"}' }] },
+    });
+    expect(reviewMessage({ decision: "changes_requested", feedback: "Fix the title" }).params.content[0].text)
+      .toBe('{"decision":"changes_requested","feedback":"Fix the title"}');
+  });
+
+  it("performs the MCP Apps handshake and awaits a successful submit", async () => {
+    const harness = createBridgeHarness();
+    harness.run();
+    expect(harness.messages[0]).toMatchObject({ id: 1, method: "ui/initialize" });
+    harness.respond({ id: 1, result: { protocolVersion: "2026-01-26" } });
+    await tick();
+    expect(harness.messages[1]).toMatchObject({ method: "ui/notifications/initialized" });
+
+    harness.elements.approve.onclick();
+    expect(harness.messages[2]).toMatchObject({ id: 2, method: "tools/call" });
+    expect(harness.messages).not.toContainEqual(expect.objectContaining({ method: "ui/message" }));
+    harness.respond({ id: 2, result: { structuredContent: { decision: "approved" } } });
+    await tick();
+    expect(harness.messages[3]).toMatchObject({ method: "ui/message" });
+    expect(new Set(harness.messages.filter((message) => "id" in message).map((message) => message.id)).size).toBe(2);
+  });
+
+  it("surfaces submit errors without sending a decision message and rejects invalid bridge messages", async () => {
+    const harness = createBridgeHarness();
+    harness.run();
+    harness.dispatch({ source: {}, data: { jsonrpc: "2.0", id: 1, result: {} } });
+    expect(harness.elements.status.textContent).toBe("");
+    harness.respond({ id: 1, result: {} });
+    await tick();
+    harness.elements.changes.onclick();
+    expect(harness.elements.status.textContent).toBe("Feedback is required.");
+    harness.elements.feedback.value = "Fix the title";
+    harness.elements.changes.onclick();
+    harness.respond({ id: 2, error: { message: "submit failed" } });
+    await tick();
+    expect(harness.elements.status.textContent).toBe("submit failed");
+    expect(harness.messages.some((message) => message.method === "ui/message")).toBe(false);
+  });
+});
+
+function tick() {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+function createBridgeHarness() {
+  const messages: any[] = [];
+  const listeners: ((event: any) => void)[] = [];
+  const element = (value = "") => ({ value, textContent: "", innerHTML: "", onclick: undefined as (() => void) | undefined, focus() {} });
+  const elements = {
+    feedback: element(),
+    status: element(),
+    article: 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; },
+  };
+  const window = { parent, addEventListener(_type: string, listener: (event: any) => void) { listeners.push(listener); } };
+  const context = vm.createContext({ window, document });
+  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 } }); },
+  };
+}

package/tests/vision-default-infer.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const ROOT = resolve(fileURLToPath(import.meta.url), "..", "..");
+const HELPER = join(ROOT, "src", "vision", "default-infer.mjs");
+const tempDirs: string[] = [];
+
+function tempBin() {
+  const dir = mkdtempSync(join(tmpdir(), "markcut-vision-test-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function script(dir: string, name: string, body: string) {
+  const path = join(dir, name);
+  writeFileSync(path, `#!/bin/sh\n${body}\n`);
+  chmodSync(path, 0o755);
+  return path;
+}
+
+function runHelper(bin: string) {
+  return spawnSync(process.execPath, [HELPER, "--prompt", "describe", "/tmp/a.jpg"], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      PATH: `${bin}:/bin:/usr/bin`,
+      MARKCUT_CHATGPT_BROWSER_INFER_CLI: "",
+      MARKCUT_CODEX_VISION_PROFILES: "zai,default",
+    },
+  });
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("default vision inference priority", () => {
+  it("uses Browser ChatGPT first", () => {
+    const bin = tempBin();
+    script(bin, "chatgpt-browser-infer", 'echo browser-result');
+    script(bin, "codex", 'echo codex-should-not-run >&2; exit 9');
+    script(bin, "uvx", 'echo local-should-not-run >&2; exit 9');
+    const r = runHelper(bin);
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toBe("browser-result");
+  });
+
+  it("falls back to Codex after Browser ChatGPT failure", () => {
+    const bin = tempBin();
+    script(bin, "chatgpt-browser-infer", 'exit 2');
+    script(bin, "codex", 'out=""; while [ "$#" -gt 0 ]; do if [ "$1" = "-o" ]; then out="$2"; shift 2; else shift; fi; done; echo codex-result > "$out"');
+    script(bin, "uvx", 'echo local-should-not-run >&2; exit 9');
+    const r = runHelper(bin);
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toBe("codex-result");
+  });
+
+  it("uses local VLM only after Browser ChatGPT and Codex fail", () => {
+    const bin = tempBin();
+    script(bin, "chatgpt-browser-infer", 'exit 2');
+    script(bin, "codex", 'exit 3');
+    script(bin, "uvx", 'echo local-result');
+    const r = runHelper(bin);
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toBe("local-result");
+  });
+
+  it("config defaults ITT to the policy helper and VTT to frame-based ITT", () => {
+    const code = 'import("./src/config.mjs").then(m => console.log(JSON.stringify({itt:m.DEFAULT_ITT_CLI,vtt:m.DEFAULT_VTT_CLI})))';
+    const env = { ...process.env } as Record<string, string>;
+    delete env.MARKCUT_ITT_CLI;
+    delete env.MARKCUT_VTT_CLI;
+    const r = spawnSync(process.execPath, ["--input-type=module", "-e", code], { cwd: ROOT, encoding: "utf8", env });
+    expect(r.status).toBe(0);
+    const value = JSON.parse(r.stdout.trim());
+    expect(value.itt).toContain("default-infer.mjs");
+    expect(value.vtt).toBe("");
+  });
+});