@lalalic/markcut 3.2.14 → 3.2.15

package/.gitattributes

@@ -0,0 +1 @@
+src/mcp/remotion-app.bundle.js -whitespace linguist-generated=true

package/docs/evidence-markcut-neutral-preview.md

@@ -0,0 +1,83 @@
+# Markcut neutral immutable multi-preview: implementation and evidence
+
+Recorded 2026-10-12 UTC. Source: this Markcut-only checkout. This report does **not** claim complete acceptance: real application-host review delivery and independent external review remain **BLOCKED**.
+
+## Scope, architecture and fixes
+
+- Previously `ensureVideoPreview` killed the existing player on each different path and returned the shared `http://127.0.0.1:4571/` URL. Now a single loopback 4571 gateway maintains distinct `/p/<UUID>/` URLs, assigns each immutable revision an SHA-256 content hash, starts up to six existing CLI player subprocesses on 4580–4598 and proxies player HTML, JS, APIs, and assets without changing the original CLI implementation.
+- Each content-hash revision gets a frozen sibling Markdown snapshot. Real E2E exposed mutable generated scene IDs in `/api/video-data`, even for unchanged Markdown; the manager now pins the compiled JSON response at preview creation. It does not use the original Markdown path for playback after snapshotting. Relative external assets are resolved by existing player behavior and may change outside the Markdown snapshot; *complete external-media immutability* is not guaranteed.
+- Duplicate same-file/concurrent requests reuse a single content-hash in-flight Promise and active revision. At most six active revisions may exist; capacity errors are explicit. Each revision uses one subprocess, so the bound is six subprocesses, **not** one render subprocess.
+- Input must be an absolute existing readable `.md` file (realpath, regular-file check, <=1MiB). Snapshots use exclusive file creation; existing snapshots must be regular, non-symlink files with the same bytes. Gateway accepts only loopback connections, rejects foreign-Origin browser requests and proxies known revisions only; it must not be exposed to an untrusted network. As with existing CLI semantics, any local user authorized to call the MCP tool can preview readable absolute files.
+- Gateway fails rather than adopting or killing unrelated services already occupying 4571. On MCP normal exit, SIGINT/SIGTERM, or stdin close, owned process group's termination stops the gateway and descendants. Snapshots and revision compiler dirs are removed on graceful gateway shutdown; an abrupt SIGKILL/crash can leave snapshot/cache artifacts. Restart is **ephemeral**: old preview URLs return HTTP 404 and a new invocation creates a new UUID. **Historical URL persistence across server restart is explicitly NOT advertised.**
+- Review UI uses **one authoritative outbound host event request**, `ui/message`, carrying neutral `decision`, `feedback` (required for changes), `previewId`, `revisionId`, and `contentHash`. Duplicate clicks are blocked in the UI. The legacy standalone `markcut.preview.submit` tool remains as side-effect-free validation and does not deliver host review events. No Relay job/task identifiers, database APIs, or Relay state changes are present in Markcut.
+
+## Commands and actual test evidence
+
+```sh
+npm ci --no-audit --no-fund
+node --check src/mcp/managed-player.mjs
+node --check src/mcp/preview.mjs
+node --check src/mcp/bridge.mjs
+node --check src/mcp/server.mjs
+npm test -- --run tests/mcp-preview.test.ts
+node scripts/verify-mcp-preview.mjs
+npm run typecheck
+npm test
+```
+
+- `npm ci`: PASS, 462 packages installed.
+- Focused MCP tests: **PASS 8/8**, including the single `ui/message` path, revision identity, duplicate-click prevention and failure handling. VM harness is *not* real host proof.
+- Real MCP + HTTP: **PASS 14/14** (last run exit 0). Full original machine outputs, IDs, URLs, content hashes, process listings and assertions in `docs/evidence-markcut-real-e2e.json`. The script launches a real MCP stdio server and two real Markdown player instances; it does not mock network or tool calls. Actual A-v1 UUID `5cdb7daa-332f-4e44-b319-88b1635175b1`, B-v1 UUID `d251d006-0956-464b-b1d3-b2b677a67334`, A-v2 UUID `4d64c6ae-1af9-4122-8fa1-ac943a611cae`. A-v1: `http://127.0.0.1:4571/p/5cdb7daa-332f-4e44-b319-88b1635175b1/`; B-v1: `http://127.0.0.1:4571/p/d251d006-0956-464b-b1d3-b2b677a67334/`; A-v2: `http://127.0.0.1:4571/p/4d64c6ae-1af9-4122-8fa1-ac943a611cae/`. A-v1 SHA256 `1f612ea3c2796d617df80e31a3890b27d6b093399395eff5759e0b8d79dfd07b`; B-v1 SHA256 `d48c6a5da387d62cf15acecf0f34c6b3c4b3666b756cba418192445f7158c64b`; A-v2 SHA256 `9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5`.
+- Real player calls returned HTTP 200, `{"ready":true}`, `/api/video-data` with distinct `Alpha v1` vs `Beta v1` source identity; HTML and `player.js` both HTTP 200. A-v1 compiled response remained *byte-identical* after A-v2; B-v1 retained its content. Twelve parallel repeated requests yielded one instance. Six-slot test observed one manager plus six player subprocesses (seven active), after shutdown zero remaining. Conflict test preserved foreign port owner. After restart, old A-v1 URL returned HTTP 404. Cross-origin unauthorized request returned 403.
+- `npm run typecheck`: **FAIL** due to existing unrelated type errors including `src/descriptive/resolve.test.ts` implicit anys, missing `dirname`, and `src/player/components/LabelControls.tsx` possibly-undefined errors. No TypeScript project source files were modified in this task. This has not been independently confirmed against a pristine baseline.
+- `npm test`: **PENDING at report creation**, running long Remotion integration tests (see final run status below). Do not interpret the focused test pass as a full-suite pass.
+
+### Acceptance decision matrix
+
+| Scenario | Result | Evidence / limitation |
+|---|---|---|
+| Two independent concurrently live Markdown video previews | PASS | Real MCP+HTTP A/B; different URLs/scene content |
+| Immutable historical revision within process lifetime | PASS | Real A-v2, A-v1 compiled JSON byte-identical |
+| Revisit A and B; repeated same path | PASS | Real HTTP + reused UUID |
+| Concurrent repeated calls; bounded children | PASS | 12 parallel requests → one revision; six slots max |
+| Invalid paths and safe snapshot access | PASS | Real MCP invalid cases; safe regular-file snapshots |
+| Port collision | PASS | Foreign service not terminated or adopted |
+| Graceful cleanup and process leak check | PASS | Six child processes + manager → zero after close |
+| Restart and historical URL semantics | PASS | Old URL 404 (persistence NOT advertised) |
+| Standalone MCP; original CLI interface preserved | PASS for stdio MCP; CLI code unchanged | Real client and unmodified CLI source; no separate legacy CLI playback smoke test |
+| Generic event-only UI contract (single path) | PASS unit test | No duplicate `tools/call`; neutral identity and feedback |
+| Generic event delivery **from real application host** | **BLOCKED** | Actual host event not observed; see manual verification |
+| Independent specialist review | **BLOCKED** | Must be scheduled by Relay owner; no independent reviewer run here |
+| Full test suite and typecheck | **See test status** | Typecheck errors recorded above |
+
+### Reproducible real application-host review verification (required before accepting this objective)
+
+1. Install/configure the MCP Apps-capable *real application host* to launch `node src/mcp/server.mjs` from this checkout (not a mock harness); enable transport/host debug logs.
+2. Call the real `markcut.preview` tool with `{"path":"/absolute/path/to/A.md"}` and open its embedded player UI. Verify the preview identity, readiness, and distinct revision URL.
+3. Click **Approve** **once** and inspect host-inbound RPC: exactly one `ui/message` request containing one serialized user text message with `decision:"approved"`, `previewId`, `revisionId`, and `contentHash`. Verify host turns it into exactly one user-visible review event; inspect events/turn logs, **not** just client success UI.
+4. Open a new revision, enter feedback, click **Request changes** and verify exactly one host event with `decision:"changes_requested"` and the exact feedback. Double-click should not duplicate; reject empty feedback. Neither path should emit `tools/call markcut.preview.submit`; neither event should have `jobId`/`taskId`.
+5. If `ui/message` is unsupported or not delivered by the host, capture RPC rejection or absent event and keep **BLOCKED**. Never infer host delivery from a VM/unit test or HTTP success.
+
+### Residual limitations
+
+- The resource lifecycle intentionally limits simultaneous preview revisions to six and requires stopping/restarting the MCP-managed server to free all slots; no per-preview close/reclaim control.
+- URLs and gateway state do not persist across service restart. Live snapshot content and pinned compiled JSON are stable, but media files read outside the snapshot may change.
+- Abrupt crashes and SIGKILL may leave generated cache/snapshots in input folders; normal termination cleans managed revision files.
+- Child preview backend ports 4580–4598 use the existing player server and are loopback-accessible directly; this is a local trusted-host tool, not a network multi-tenant security boundary.
+- Independent review and real host event are required acceptance gates and remain BLOCKED, regardless of successful localhost E2E.
+
+## Final full-suite result (supersedes earlier pending status)
+
+- `npm test` — **FAIL**, exit code 1. **454 passed, 11 failed, 2 skipped** (16 files: 3 failed, 13 passed); runtime 386.27s. The focused MCP test suite remains 8/8 PASS and real MCP+HTTP test suite 14/14 PASS.
+- Nine failures originate in `tests/render.test.ts`: audio track rendering, audio extraction, full-feature audio, combined feature renders, STT, parallel audio/image/subtitle, and video trimming. One failure is `src/descriptive/compiler.test.ts` expecting unique generated IDs, and one is `src/descriptive/markdown.test.ts` expecting an empty standalone script to throw. No source in these test areas was modified during the Markcut preview work; baseline equivalence is unverified.
+- Raw stderr and stdout: local Neo shell job `1791827301578-0896f7bff8-markcut-relevant-full-test`, `~/Library/Application Support/NeoY/core/jobs/1791827301578-0896f7bff8-markcut-relevant-full-test.{stderr,stdout}.log`.
+- Final acceptance of full regression and independent review remains **BLOCKED/FAIL**; the passing focused/real preview checks do not override it.
+
+## Fresh validation, execution attempt 2 (2026-10-12 14:53 America/Toronto)
+
+- `node scripts/verify-mcp-preview.mjs > /tmp/markcut-postfix-e2e.log 2>&1`: PASS (exit 0), real MCP + HTTP. Latest raw results committed in `docs/evidence-markcut-real-e2e.json`.
+- `npm test -- --run tests/mcp-preview.test.ts`: PASS (8/8).
+- `node --check src/mcp/managed-player.mjs`: PASS.
+- Concurrent child-port reservation hardened: one candidate port cannot be issued twice during asynchronous snapshot creation, and reservation released on exit/failure/shutdown.
+- Full suite previously FAILED (454 pass, 11 fail, 2 skip); typecheck previously FAILED; see original report for exact errors. These results are NOT superseded by focused checks.
+- Actual external MCP application host `ui/message` delivery: BLOCKED (no observed host-inbound event). Independent review: BLOCKED pending Relay-managed reviewer.

package/docs/evidence-markcut-real-e2e.json

@@ -0,0 +1,267 @@
+{
+  "timestamp": "2026-10-13T16:43:56.983Z",
+  "dir": "/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S",
+  "checks": [
+    {
+      "label": "A-v1 and B-v1 parallel real MCP calls",
+      "status": "PASS",
+      "detail": {
+        "A": "http://127.0.0.1:4571/p/cfdd7ccf-8dc6-4359-93da-d19f57bb77fe/",
+        "B": "http://127.0.0.1:4571/p/619e0d46-19d9-4fba-b682-6746a5f62060/"
+      }
+    },
+    {
+      "label": "HTTP readiness and identity A/B",
+      "status": "PASS",
+      "detail": {
+        "AIdentity": "Alpha v1",
+        "BIdentity": "Beta v1"
+      }
+    },
+    {
+      "label": "HTTP player HTML and bundled JavaScript per revision",
+      "status": "PASS",
+      "detail": ""
+    },
+    {
+      "label": "revisit both URLs",
+      "status": "PASS",
+      "detail": ""
+    },
+    {
+      "label": "repeat identical path deduplicates",
+      "status": "PASS",
+      "detail": "cfdd7ccf-8dc6-4359-93da-d19f57bb77fe"
+    },
+    {
+      "label": "A-v2 revision, immutable A-v1",
+      "status": "PASS",
+      "detail": {
+        "A1": "http://127.0.0.1:4571/p/cfdd7ccf-8dc6-4359-93da-d19f57bb77fe/",
+        "A2": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/"
+      }
+    },
+    {
+      "label": "parallel repeat calls",
+      "status": "PASS",
+      "detail": {
+        "calls": 12,
+        "instances": 1
+      }
+    },
+    {
+      "label": "invalid paths rejected by actual MCP",
+      "status": "PASS",
+      "detail": ""
+    },
+    {
+      "label": "cross-origin browser request rejected",
+      "status": "PASS",
+      "detail": ""
+    },
+    {
+      "label": "bounded six revisions and graceful seventh refusal",
+      "status": "PASS",
+      "detail": "6 active slots maximum"
+    },
+    {
+      "label": "cleanup manager and child processes",
+      "status": "PASS",
+      "detail": ""
+    },
+    {
+      "label": "foreign process on 4571 is not killed or reused",
+      "status": "PASS",
+      "detail": ""
+    },
+    {
+      "label": "restart expires old URLs (no historical persistence advertised)",
+      "status": "PASS",
+      "detail": {
+        "old": "http://127.0.0.1:4571/p/cfdd7ccf-8dc6-4359-93da-d19f57bb77fe/",
+        "oldStatus": 404,
+        "new": "http://127.0.0.1:4571/p/75f9c9fa-4965-4585-adc3-c06ed5798540/"
+      }
+    },
+    {
+      "label": "restart cleanup",
+      "status": "PASS",
+      "detail": ""
+    }
+  ],
+  "previews": [
+    {
+      "id": "cfdd7ccf-8dc6-4359-93da-d19f57bb77fe",
+      "revisionId": "cfdd7ccf-8dc6-4359-93da-d19f57bb77fe",
+      "contentHash": "1f612ea3c2796d617df80e31a3890b27d6b093399395eff5759e0b8d79dfd07b",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/cfdd7ccf-8dc6-4359-93da-d19f57bb77fe/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/1f612ea3c2796d617df80e31a3890b27d6b093399395eff5759e0b8d79dfd07b"
+    },
+    {
+      "id": "619e0d46-19d9-4fba-b682-6746a5f62060",
+      "revisionId": "619e0d46-19d9-4fba-b682-6746a5f62060",
+      "contentHash": "d48c6a5da387d62cf15acecf0f34c6b3c4b3666b756cba418192445f7158c64b",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/B.md",
+      "previewUrl": "http://127.0.0.1:4571/p/619e0d46-19d9-4fba-b682-6746a5f62060/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/d48c6a5da387d62cf15acecf0f34c6b3c4b3666b756cba418192445f7158c64b"
+    },
+    {
+      "id": "cfdd7ccf-8dc6-4359-93da-d19f57bb77fe",
+      "revisionId": "cfdd7ccf-8dc6-4359-93da-d19f57bb77fe",
+      "contentHash": "1f612ea3c2796d617df80e31a3890b27d6b093399395eff5759e0b8d79dfd07b",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/cfdd7ccf-8dc6-4359-93da-d19f57bb77fe/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/1f612ea3c2796d617df80e31a3890b27d6b093399395eff5759e0b8d79dfd07b"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "revisionId": "bf57e7e0-5dd6-4605-a6a9-13950be26ecc",
+      "contentHash": "9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/A.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bf57e7e0-5dd6-4605-a6a9-13950be26ecc/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9a0fe26791bed4f8aa7d0d75b9badeee025acc2784a0628e23bcd99d5aa5b6c5"
+    },
+    {
+      "id": "bad49c87-ac78-4923-a053-129a5c898925",
+      "revisionId": "bad49c87-ac78-4923-a053-129a5c898925",
+      "contentHash": "383b5cbc87c3faa165c604858360cadd038e00abd457307f570018fd536d2466",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/extra0.md",
+      "previewUrl": "http://127.0.0.1:4571/p/bad49c87-ac78-4923-a053-129a5c898925/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/383b5cbc87c3faa165c604858360cadd038e00abd457307f570018fd536d2466"
+    },
+    {
+      "id": "b2000092-cd9a-4ca5-a8ae-66c3a0473656",
+      "revisionId": "b2000092-cd9a-4ca5-a8ae-66c3a0473656",
+      "contentHash": "8f21105b4b452cb0f94626b35ddc5c95636b70a847abe35b28c601cf471261e0",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/extra1.md",
+      "previewUrl": "http://127.0.0.1:4571/p/b2000092-cd9a-4ca5-a8ae-66c3a0473656/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/8f21105b4b452cb0f94626b35ddc5c95636b70a847abe35b28c601cf471261e0"
+    },
+    {
+      "id": "5f1c58c6-e635-4630-929d-fbec0b162607",
+      "revisionId": "5f1c58c6-e635-4630-929d-fbec0b162607",
+      "contentHash": "9103393b1898e5a18c68c371adf7d2342def8eb43ebbf55f508714a22c881c75",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/extra2.md",
+      "previewUrl": "http://127.0.0.1:4571/p/5f1c58c6-e635-4630-929d-fbec0b162607/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/9103393b1898e5a18c68c371adf7d2342def8eb43ebbf55f508714a22c881c75"
+    },
+    {
+      "id": "75f9c9fa-4965-4585-adc3-c06ed5798540",
+      "revisionId": "75f9c9fa-4965-4585-adc3-c06ed5798540",
+      "contentHash": "d48c6a5da387d62cf15acecf0f34c6b3c4b3666b756cba418192445f7158c64b",
+      "path": "/private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/B.md",
+      "previewUrl": "http://127.0.0.1:4571/p/75f9c9fa-4965-4585-adc3-c06ed5798540/",
+      "resourceUri": "ui://markcut/video-preview-v3.html/d48c6a5da387d62cf15acecf0f34c6b3c4b3666b756cba418192445f7158c64b"
+    }
+  ],
+  "processes": {
+    "active": [
+      "29155 29154 /opt/homebrew/Cellar/node/25.6.0/bin/node /Users/chengli/Workspace/.worktrees/orchestrator/markcut-pr17-current/src/mcp/managed-player.mjs",
+      "29156 29155 /opt/homebrew/Cellar/node/25.6.0/bin/node /Users/chengli/Workspace/.worktrees/orchestrator/markcut-pr17-current/src/player/server.mjs /private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/.markcut-preview-aa3f8b91210d4b7e2be35610da5ccf2c9327a913d9ff1757743e7a663f50340a.md --port=4580",
+      "29157 29155 /opt/homebrew/Cellar/node/25.6.0/bin/node /Users/chengli/Workspace/.worktrees/orchestrator/markcut-pr17-current/src/player/server.mjs /private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/.markcut-preview-1bdc848d2672b02acbcf513394af7a3f17c41644515e16658a7773edb153c2fc.md --port=4581",
+      "29187 29155 /opt/homebrew/Cellar/node/25.6.0/bin/node /Users/chengli/Workspace/.worktrees/orchestrator/markcut-pr17-current/src/player/server.mjs /private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/.markcut-preview-002bc32e4c460e35384669cc42d21e27731cd4aeaf212c3c219391aa04e5ba27.md --port=4582",
+      "29196 29155 /opt/homebrew/Cellar/node/25.6.0/bin/node /Users/chengli/Workspace/.worktrees/orchestrator/markcut-pr17-current/src/player/server.mjs /private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/.markcut-preview-51f8390c693223212f57d2c66df81bd7ea3ede26e9f28e0606dff57c933fc9b4.md --port=4583",
+      "29214 29155 /opt/homebrew/Cellar/node/25.6.0/bin/node /Users/chengli/Workspace/.worktrees/orchestrator/markcut-pr17-current/src/player/server.mjs /private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/.markcut-preview-6bb4dea906864d49de4a8d3208b7de4a9f58e09e2745cc6e983dd4fbe4a55fd7.md --port=4584",
+      "29302 29155 /opt/homebrew/Cellar/node/25.6.0/bin/node /Users/chengli/Workspace/.worktrees/orchestrator/markcut-pr17-current/src/player/server.mjs /private/var/folders/pr/rymvcpd54mzdg4kv34r3ht300000gn/T/markcut-real-e2e-Ychg1S/.markcut-preview-d6777c6b00501eff0cb6968cc749914b457ecc8be820b0d3937221cd08d59e28.md --port=4585"
+    ],
+    "afterClose": []
+  },
+  "completedAt": "2026-10-13T16:44:03.536Z"
+}

package/docs/mcp-static-preview.md

@@ -0,0 +1,57 @@
+# Markcut MCP Static Preview Architecture
+
+**Compile-and-release**: markcut.preview compiles Markdown, publishes an immutable JSON and media snapshot to NeoY File Server, and returns. It does not spawn a persistent Player Manager or per-Revision Player. Native CLI preview remains separate.
+
+## Files
+- Keep only current story.md, directory.md and video.md in a Vlog run. Story/directory are not necessarily Markcut video DSL.
+- Latest compiled stream: <run>/.markcut/<basename>/default/compiled.json
+- General immutable cache: <run>/.markcut/cache/<hash>.json
+- Per-video index: <run>/.markcut/<basename>/default/cache-index.json
+- NeoY HTTPS published resources: /files/_neoy/markcut/cache/<hash>.json, /generated/<hash> for frozen local media, and /player/<bundle-hash>.js for the shared MCP player.
+
+## Lifecycle
+- Input fingerprint covers absolute source path, Markdown, audio and referenced local media metadata. Repeating identical input reuses the cache.
+- Compile with a deterministic seed so parsing does not modify the source Markdown.
+- Publish media and immutable JSON before atomically updating the latest compiled file.
+- Retain latest plus nine older successful compiled results per Video. Compilation errors leave the previous latest intact.
+- Local media files are snapshotted and older retained previews can play, seek and show maps without a local preview process.
+- Old Preview review buttons become read-only; review submissions check the current published hash. Human/Relay review authorization remains separate.
+- Source files are latest-only, not historically versioned. No user-facing History UI.
+- External HTTPS media are not frozen; local media snapshots provide exact replay where required.
+
+## Verification
+Run focused Vitest tests and node scripts/verify-mcp-preview.mjs, then independently inspect the real ChatGPT hosted iframe with Browser Workspace. A passing compiler, a compiled tool result, and a working hosted MCP player are distinct gates. Do not approve automatically.
+
+
+## Asynchronous compilation and in-app progress (v21)
+
+markcut.preview validates the Markdown source, writes a transient operation record,
+spawns a detached compiler worker, and returns immediately with operationId,
+operationUrl, state=compiling, path and resourceUri.
+
+The worker publishes its status through NeoY File Server under
+/files/_neoy/markcut/operations/<uuid>.json. It reports actual stages:
+checking-cache, parsing-markdown, resolving-assets-and-generating-media,
+compiling-scenes, freezing-preview-assets and publishing-static-preview.
+The iframe shows the current stage and elapsed seconds, without a fabricated percent.
+
+Ready status includes a compiledUrl. Failed status includes an error. The iframe
+polls once per second and hides playback and review controls until the immutable
+compiled JSON is available. The compiler then exits, with no long-lived manager.
+
+Status files older than 24 hours are opportunistically pruned during new operations.
+The existing immutable compiled cache keeps up to ten results per Video.
+Source hashes are checked at worker start and again before publishing.
+
+The real hosted ChatGPT iframe was observed while an isolated 30-second MCP probe
+still reported compiling. That validation establishes early mounting, not a
+production video or Google Maps pixel-level verification.
+
+
+## Current hosted Player (v24)
+
+The immutable MCP player shares the native Remotion player and scene navigator. The header contains Markcut/title, optional browser-TTS toggle, and version. The human may Send feedback with scene/time context or Approve a specific revision. These review decisions use MCP Apps `ui/message`; the agent performs all Markdown changes and repeats `markcut.preview` to show a new revision. Host end-to-end continuation is not yet production-verified.
+
+During compilation, Google Maps route/cinematic scenes are optionally rendered by Remotion to MP4 and published as immutable generated media. On successful render the compiled stream references video nodes, and the public JSON omits the Google Maps API key. If no key is available or rendering fails, the original live Map component is retained. The compiler's launch environment must supply `GOOGLE_MAPS_API_KEY`; the NeoY MCP entrypoint is `scripts/launch-mcp.sh` which loads the login environment. This is separate from the local CLI preview.
+
+Player Browser TTS is a **playback-only** mode: it uses existing VTT text for speech and captions, defaulting on when VTT exists. Turning it off restores generated audio. STT is not used in this mode; compilation-time TTS is currently unchanged.

package/examples/mcp-preview-review/README.md

@@ -0,0 +1,6 @@
+# MCP Preview manual regression fixtures
+
+Synthetic A/B scenes, v4 HTTPS WAV/MP4/SRT and multi-revision review examples.
+For local preview, call markcut.preview with an absolute Markdown path.
+For public-preview URL tests, mount this directory as markcut-review with neoy.setup.
+Review and playback verification is manual; fixture availability is not approval.

package/examples/mcp-preview-review/video-a-v1.md

@@ -0,0 +1,9 @@
+# video
+seed:355483143
+width:640 height:480 fps:30 layout:series
+## Opening_Long
+- component duration:2 jsx:"<div style={{fontSize:64}}>A — Long opening for manual review</div>"
+## Canal_View
+- component duration:2 jsx:"<div style={{fontSize:64}}>A — Canal view</div>"
+## Background_Title
+- component duration:2 jsx:"<div style={{fontSize:64}}>A — Autumn along the canal</div>"

package/examples/mcp-preview-review/video-a-v2.md

@@ -0,0 +1,9 @@
+# video
+seed:355483143
+width:640 height:480 fps:30 layout:series
+## Opening-Long
+- component duration:2 jsx:"<div style={{fontSize:64}}>A — Long opening for manual review</div>"
+## Canal-View
+- component duration:2 jsx:"<div style={{fontSize:64}}>A — Canal view</div>"
+## Background-Title
+- component duration:2 jsx:"<div style={{fontSize:64}}>A — Autumn along the canal</div>"

package/examples/mcp-preview-review/video-a-v3.md

@@ -0,0 +1,9 @@
+# video
+seed:2449698215
+width:640 height:480 fps:30 layout:series
+## Opening-Blue
+- component duration:2 jsx:"<div style={{background:'#174EA6',color:'#FFFFFF',width:'100%',height:'100%',display:'flex',alignItems:'center',justifyContent:'center',fontSize:52,fontWeight:'bold'}}>PREVIEW A - OPENING</div>"
+## Canal-View
+- component duration:2 jsx:"<div style={{background:'#008577',width:'100%',height:'100%',display:'flex',alignItems:'center',justifyContent:'center'}}><img src='data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20640%20480%22%3E%3Crect%20width%3D%22640%22%20height%3D%22480%22%20fill%3D%22%23b5e1f2%22%2F%3E%3Ccircle%20cx%3D%22505%22%20cy%3D%22105%22%20r%3D%2254%22%20fill%3D%22%23ffd36a%22%2F%3E%3Cpath%20d%3D%22M0%20285L155%20115L295%20283L430%20155L640%20320V480H0Z%22%20fill%3D%22%23488398%22%2F%3E%3Cpath%20d%3D%22M0%20339L160%20213L322%20370L492%20240L640%20353V480H0Z%22%20fill%3D%22%232b6479%22%2F%3E%3Cpath%20d%3D%22M0%20370Q155%20330%20320%20390T640%20365V480H0Z%22%20fill%3D%22%231c8596%22%2F%3E%3Cpath%20d%3D%22M0%20420Q180%20389%20320%20425T640%20411%22%20fill%3D%22none%22%20stroke%3D%22%23a6e4e2%22%20stroke-width%3D%2210%22%2F%3E%3C%2Fsvg%3E' alt='Mountain lake illustration' style={{width:'100%',height:'100%',objectFit:'cover'}} /></div>"
+## Background-Title
+- component duration:2 jsx:"<div style={{background:'#733BBC',color:'#FFFFFF',width:'100%',height:'100%',display:'flex',alignItems:'center',justifyContent:'center',fontSize:44}}>A - AUTUMN TITLE</div>"

package/examples/mcp-preview-review/video-a-v4.md

@@ -0,0 +1,13 @@
+# video
+seed:1758416490
+width:640 height:480 fps:30 layout:series
+subtitle:"https://neoy.qili2.com/files/markcut-review/video-a-v4.srt"
+
+## Opening-Blue
+- component duration:2 jsx:"<div style={{background:'#174EA6',color:'#FFFFFF',width:'100%',height:'100%',display:'flex',alignItems:'center',justifyContent:'center',fontSize:36,fontWeight:'bold'}}>PREVIEW A - REMOTE URL TEST</div>"
+
+## Remote-Video
+- component duration:2 jsx:"<video src='https://neoy.qili2.com/files/markcut-review/video-a-v4.mp4' autoPlay muted loop playsInline style={{width:'100%',height:'100%',objectFit:'cover'}} />"
+
+## Background-Title
+- component duration:2 jsx:"<div style={{background:'#733BBC',color:'#FFFFFF',width:'100%',height:'100%',display:'flex',alignItems:'center',justifyContent:'center',fontSize:34}}>REMOTE AUDIO + VIDEO + SRT</div>"

package/examples/mcp-preview-review/video-a-v4.srt

@@ -0,0 +1,11 @@
+1
+00:00:00,000 --> 00:00:02,000
+Opening: remote media test
+
+2
+00:00:02,000 --> 00:00:04,000
+Video scene from NeoY URL
+
+3
+00:00:04,000 --> 00:00:06,000
+Audio and transcript complete

package/examples/mcp-preview-review/video-a-v4.vtt

@@ -0,0 +1,10 @@
+WEBVTT
+
+00:00:00.000 --> 00:00:02.000
+Opening: remote media test
+
+00:00:02.000 --> 00:00:04.000
+Video scene from NeoY URL
+
+00:00:04.000 --> 00:00:06.000
+Audio and transcript complete

package/examples/mcp-preview-review/video-b-v1.md

@@ -0,0 +1,6 @@
+# video
+width:640 height:480 fps:30 layout:series
+## Mountain_B
+- component duration:2 jsx:"<div style={{fontSize:64}}>B — Independent mountain preview</div>"
+## Mountain_End
+- component duration:2 jsx:"<div style={{fontSize:64}}>B — Must stay independent from A</div>"

package/examples/mcp-preview-review/video-b-v2.md

@@ -0,0 +1,6 @@
+# video
+width:640 height:480 fps:30 layout:series
+## Mountain-B
+- component duration:2 jsx:"<div style={{fontSize:64}}>B — Independent mountain preview</div>"
+## Mountain-End
+- component duration:2 jsx:"<div style={{fontSize:64}}>B — Must stay independent from A</div>"

package/examples/mcp-preview-review/video-b-v3.md

@@ -0,0 +1,6 @@
+# video
+width:640 height:480 fps:30 layout:series
+## Mountain-Orange
+- component duration:2 jsx:"<div style={{background:'#BD4B12',color:'#FFFFFF',width:'100%',height:'100%',display:'flex',alignItems:'center',justifyContent:'center',fontSize:52,fontWeight:'bold'}}>preview b - mountain</div>"
+## Mountain-End
+- component duration:2 jsx:"<div style={{background:'#27442B',color:'#FFFFFF',width:'100%',height:'100%',display:'flex',alignItems:'center',justifyContent:'center',fontSize:50}}>b - independent</div>"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
   "bin": {
     "markcut": "bin/markcut"
@@ -23,6 +23,7 @@
     "templates": "node src/render/cli.mjs templates",
     "preview": "node src/render/cli.mjs preview",
     "mcp": "node src/mcp/server.mjs",
+    "build:mcp": "scripts/build-mcp-preview.sh",
     "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",
@@ -31,7 +32,7 @@
     "test": "vitest run --config tests/vitest.config.ts",
     "test:integration": "vitest run --config tests/vitest.config.ts tests/render.test.ts",
     "test:watch": "vitest --config tests/vitest.config.ts",
-    "build": "scripts/build-pipeline.sh && scripts/build-player.sh",
+    "build": "scripts/build-pipeline.sh && scripts/build-player.sh && scripts/build-mcp-preview.sh",
     "vision": "node src/render/cli.mjs vision",
     "markcut": "bin/markcut",
     "push": "GIT_SSH_COMMAND=\"ssh -i ~/.ssh/id_ed25519_1 -o IdentitiesOnly=yes\" git push"

package/scripts/build-mcp-preview.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/.."
+./node_modules/.bin/esbuild src/mcp/remotion-app.tsx \
+  --bundle --minify --format=iife --platform=browser --target=es2020 \
+  --define:process.env.NODE_ENV='"production"' \
+  --outfile=src/mcp/remotion-app.bundle.js

package/scripts/launch-mcp.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# NeoY stdio entrypoint: load the user's login environment so the compiler
+# receives GOOGLE_MAPS_API_KEY without embedding it in MCP config or JSON.
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+exec /bin/zsh -lc 'exec node "$1"' _ "$ROOT/src/mcp/server.mjs"