The VS Code of video editing, built for agents.
TypeScript
Integrate @diffusionstudio/dapi into CLI and desktop applications
konstantin-paulus4d94b87881d9
diff --git a/apps/cli/package.json b/apps/cli/package.jsonindex 994710b0..76346cd6 100644--- a/apps/cli/package.json+++ b/apps/cli/package.json@@ -7,8 +7,7 @@"dapi": "./dist/index.js"},"exports": {- "./protocol": "./src/protocol.ts",- "./channels": "./src/cli-channels.ts"+ "./protocol": "./src/protocol.ts"},"scripts": {"build": "esbuild src/index.ts --bundle --platform=node --format=cjs --external:esbuild --external:@babel/core --external:@babel/preset-typescript --external:babel-preset-solid --external:bufferutil --external:utf-8-validate --outfile=dist/index.js && chmod +x dist/index.js",@@ -24,7 +23,8 @@"babel-preset-solid": "^1.9.12","commander": "^14.0.3","esbuild": "^0.28.1",- "ws": "^8.18.3"+ "ws": "^8.18.3",+ "@diffusionstudio/dapi": "*"},"devDependencies": {"@types/babel__core": "^7.20.5",diff --git a/apps/cli/src/cli-channels.ts b/apps/cli/src/cli-channels.tsdeleted file mode 100644index adecc9ca..00000000--- a/apps/cli/src/cli-channels.ts+++ /dev/null@@ -1,194 +0,0 @@-/* This Source Code Form is subject to the terms of the Mozilla Public- * License, v. 2.0. If a copy of the MPL was not distributed with this- * file, You can obtain one at http://mozilla.org/MPL/2.0/. */--// Wire-level channel for the CLI handshake. Each CLI command hosts a-// short-lived WebSocket server; main's only job is to relay the connect-// info to the renderer, which then dials the CLI directly. Main never sees-// request payloads.-export const CLI_WIRE = {- CONNECT: "cli:connect",-} as const;--// Sent by the CLI to main over the unix socket, relayed verbatim to the-// renderer. The token guards the loopback WebSocket server against other-// local processes racing to connect first.-export type CliHandshake = { port: number; token: string };--export type CliHandshakeReply = { ok: true } | { ok: false; error: string };--// One tRPC request/reply pair per WebSocket connection. `path` is the-// dot-joined procedure path in the renderer's router (e.g. "media.frame");-// procedure inputs and outputs are typed end-to-end via the AppRouter type,-// so the wire envelope stays untyped.-export type CliRequest = {- path: string;- input: unknown;-};--export type CliReply =- | { ok: true; data: unknown }- | { ok: false; error: string };--export type AssetRef = { path: string };--export type MediaProbeRequest = AssetRef;--export type FrameQuality = "small" | "medium" | "large" | "fullres";-export type MediaFrameRequest = AssetRef & {- times?: number[];- count?: number;- start?: number;- end?: number;- quality?: FrameQuality;- auto?: boolean;- combine?: boolean;- perSheet?: number;-};--/** Beyond this the cells get too small to be worth the tokens; use `filmstrip`. */-export const MAX_FRAMES_PER_SHEET = 12;--/**- * One written image: a single frame stamped with its timecode, or a contact- * sheet stamped with the span it covers (`0f-08s10f`).- */-export type TimecodedImage = { timecode: string; base64: string };--export type MediaFrameResult = TimecodedImage[];--export type CaptureRequest = {- id: string;- frames?: number[];- combine?: boolean;- perSheet?: number;-};--export type CaptureResult = TimecodedImage[];--export type MediaTranscribeRequest = AssetRef;-export type TranscriptWord = { text: string; start: number; end: number };-export type TranscriptSegment = { text: string; words: TranscriptWord[] };-export type MediaTranscribeResult = { segments: TranscriptSegment[] };--export type MediaFilmstripRequest = AssetRef & { start?: number; end?: number; scale?: number };-export type MediaFilmstripResult = { base64: string };--export type MediaWaveformRequest = AssetRef & { start?: number; end?: number; scale?: number };-export type MediaWaveformResult = {- base64: string;- silences: Array<{ start: number; end: number }>;-};--export type MediaListenRequest = AssetRef & { prompt?: string; start?: number; end?: number; stripVideo?: boolean };-export type MediaListenResult = { result?: string; start?: number; end?: number };--export type CheckRequest = { id: string };--export type CheckIssueCode =- | "black-frames"- | "no-visuals"- | "never-visible"- | "zero-duration"- | "transparent"- | "source-error";--/**- * One structural finding. `ranges` (where present) are seconds relative to- * the checked node's start — the same clock `capture --time` uses.- */-export type CheckIssue = {- code: CheckIssueCode;- severity: "error" | "warning";- message: string;- /** Source stamp of the offending node; absent when the issue is about the subtree as a whole. */- node?: string;- ranges?: Array<{ start: number; end: number }>;-};--export type CheckResult = {- stats: {- /** Nodes in the subtree, the checked node included. */- nodes: number;- byKind: Record<string, number>;- /** Deepest nesting level below the checked node (0 = no children). */- depth: number;- /** Seconds the checked node plays (its workarea, when one is set). */- duration: number;- };- issues: CheckIssue[];-};--export type ExportFormat = "mp4" | "webm" | "ogg" | "mov";--// The settings shape mirrors the scene's `diffusion.export.<id>` entry in the-// project's package.json (see the web app's engine/project-config), spelled-// out here so the wire seam stays dependency-free. Codecs are strings on the-// wire; the app validates them against what the encoder accepts.-export type ExportVideoSettings = {- enabled?: boolean;- codec?: string;- bitrate?: number;- fps?: number;- resolution?: number;-};--export type ExportAudioSettings = {- enabled?: boolean;- codec?: string;- sampleRate?: number;- bitrate?: number;-};--export type ExportSettings = {- format?: ExportFormat;- video?: ExportVideoSettings;- audio?: ExportAudioSettings;-};--/**- * `path` is the absolute output file, whose extension picks the container;- * omitted, the app writes `exports/<id>.<format>` in the project folder.- * Everything else — codecs, bitrates, resolution — is read from the scene's- * export entry in the project's package.json.- */-export type ExportRequest = { id: string; path?: string };--/**- * `config` echoes the settings the export was made with — the package.json- * entry (or the defaults), with the container the extension resolved to — so- * a caller sees what its config edit actually did. `width`/`height` are the- * encoded pixel size (0×0 for an audio-only export); `duration` is seconds.- */-export type ExportResult = {- path: string;- width: number;- height: number;- duration: number;- size: number;- config: ExportSettings;-};--export type GeneratedAsset = { id: string; name: string; type: string };--export type ModelsRequest = { type?: "image" | "video" | "audio" };--export type ModelInfo = {- type: "image" | "video" | "audio";- id: string;- name: string;- durations?: string[];- aspectRatios?: string[];- features?: Array<"start-frame" | "end-frame" | "audio">;-};--export type VoiceInfo = { id: string; label: string; description: string };--export type ScreenshotResult = { base64: string; width: number; height: number };--export type LogLevel = "debug" | "info" | "warning" | "error";--export type LogEntry = { ts: number; level: LogLevel; message: string; source: string };--export type LogsRequest = { tail?: number; level?: LogLevel };-diff --git a/apps/cli/src/cli-client.ts b/apps/cli/src/cli-client.tsindex fc125a02..6554862f 100644--- a/apps/cli/src/cli-client.ts+++ b/apps/cli/src/cli-client.ts@@ -9,7 +9,7 @@ import { WebSocketServer } from "ws";import { createTRPCClient, TRPCClientError } from "@trpc/client";import type { TRPCLink } from "@trpc/client";import { observable } from "@trpc/server/observable";-import { SOCKET_PATH } from "./protocol";+import { SOCKET_PATH } from "@diffusionstudio/dapi/socket";import type { CliHandshake, CliHandshakeReply, CliReply, CliRequest } from "./protocol";import type { AppRouter } from "../../web/src/context/dapi";diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.tsindex 184dac9b..e8e74f82 100644--- a/apps/cli/src/index.ts+++ b/apps/cli/src/index.ts@@ -15,8 +15,8 @@ import { editor, errnoCode, EXPORT_TIMEOUT_MS, GENERATE_TIMEOUT_MS, waitForCliSoimport { listLocalFonts } from "./fonts";import { buildIssueBody, createIssue } from "./report";import { fetchVideo } from "./ytdlp";-import { MAX_FRAMES_PER_SHEET } from "./protocol";-import type { AssetRef, FrameQuality, LogEntry, LogLevel, TimecodedImage } from "./protocol";+import { MAX_FRAMES_PER_SHEET } from "@diffusionstudio/dapi";+import type { FrameQuality, LogEntry, LogLevel, TimecodedImage } from "@diffusionstudio/dapi";// Long-running commands (renders, AI generation) override the default 60s.const GENERATE = { context: { timeoutMs: GENERATE_TIMEOUT_MS } };@@ -129,7 +129,7 @@ async function mediaFrame(ref: string, opts: MediaFrameOptions): Promise<void> {* anything else — a URL, or a library path (`b-roll/clip.mp4`) — is passed* through for the app to resolve. Library paths need an open project.*/-function resolveAssetRef(ref: string): AssetRef {+function resolveAssetRef(ref: string): { path: string } {const absPath = isAbsolute(ref) ? ref : resolve(process.cwd(), ref);if (existsSync(absPath)) return { path: absPath };if (isAbsolute(ref)) {diff --git a/apps/cli/src/protocol.ts b/apps/cli/src/protocol.tsindex d4d60007..9119d703 100644--- a/apps/cli/src/protocol.ts+++ b/apps/cli/src/protocol.ts@@ -2,10 +2,34 @@* License, v. 2.0. If a copy of the MPL was not distributed with this* file, You can obtain one at http://mozilla.org/MPL/2.0/. */-// Public wire protocol consumed by both the CLI binary and any host that-// embeds the CLI socket server (the Diffusion Studio desktop app). Importing-// from `@diffusionstudio/cli/protocol` is the OSS-friendly seam: this module has no-// dependency on proprietary code, so the package stays extractable into its-// own repo.-export * from "./cli-channels";-export * from "./cli-socket-path";+// The transport between the CLI and the app, and nothing else: the tool+// catalog and every request and result type live in @diffusionstudio/dapi.+// Free of Node built-ins so the renderer can import it; the socket path is+// in @diffusionstudio/dapi/socket.+//+// Each CLI command hosts a short-lived WebSocket server; main's only job is+// to relay the connect info to the renderer, which then dials the CLI+// directly. Main never sees request payloads.+export const CLI_WIRE = {+ CONNECT: "cli:connect",+} as const;++// Sent by the CLI to main over the unix socket, relayed verbatim to the+// renderer. The token guards the loopback WebSocket server against other+// local processes racing to connect first.+export type CliHandshake = { port: number; token: string };++export type CliHandshakeReply = { ok: true } | { ok: false; error: string };++// One tRPC request/reply pair per WebSocket connection. `path` is the+// dot-joined procedure path in the renderer's router (e.g. "media.frame");+// procedure inputs and outputs are typed end-to-end via the AppRouter type,+// so the wire envelope stays untyped.+export type CliRequest = {+ path: string;+ input: unknown;+};++export type CliReply =+ | { ok: true; data: unknown }+ | { ok: false; error: string };diff --git a/apps/desktop/package.json b/apps/desktop/package.jsonindex 20c0d2ba..56a49222 100644--- a/apps/desktop/package.json+++ b/apps/desktop/package.json@@ -44,6 +44,7 @@"nanoid": "^6.0.1","ts-morph": "^28.0.0","update-electron-app": "^3.0.0",- "yaml": "^2.9.0"+ "yaml": "^2.9.0",+ "@diffusionstudio/dapi": "*"}}diff --git a/apps/desktop/src/cli-server.ts b/apps/desktop/src/cli-server.tsindex c78cf301..457cb750 100644--- a/apps/desktop/src/cli-server.ts+++ b/apps/desktop/src/cli-server.ts@@ -6,7 +6,8 @@ import { existsSync, unlinkSync } from "node:fs";import { createServer } from "node:net";import type { Server, Socket } from "node:net";import { app, BrowserWindow } from "electron";-import { CLI_WIRE, SOCKET_PATH } from "@diffusionstudio/cli/protocol";+import { CLI_WIRE } from "@diffusionstudio/cli/protocol";+import { SOCKET_PATH } from "@diffusionstudio/dapi/socket";import type { CliHandshake, CliHandshakeReply } from "@diffusionstudio/cli/protocol";import { mainBridge } from "./main-manager";import { MAIN_CHANNELS } from "./main-channels";diff --git a/apps/desktop/src/main-channels.ts b/apps/desktop/src/main-channels.tsindex 5df8bb83..9fd04403 100644--- a/apps/desktop/src/main-channels.ts+++ b/apps/desktop/src/main-channels.ts@@ -9,7 +9,7 @@//// CLI traffic uses a separate wire pair (CLI_WIRE in @diffusionstudio/cli/protocol);// main forwards it opaquely without inspecting channel names.-import type { LogEntry, ScreenshotResult } from "@diffusionstudio/cli/protocol";+import type { LogEntry, ScreenshotResult } from "@diffusionstudio/dapi";import type { SourceEdit, WriteResult } from "./edit";export const MAIN_WIRE = {diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.tsindex b965b054..ad16a026 100644--- a/apps/desktop/src/main.ts+++ b/apps/desktop/src/main.ts@@ -42,7 +42,7 @@ import {writeProject,} from "./projects";import type { DeepLinkChannel } from "./main-channels";-import type { LogEntry } from "@diffusionstudio/cli/protocol";+import type { LogEntry } from "@diffusionstudio/dapi";const DEV_URL = "http://localhost:5173";const AUTH_PROTOCOL = "diffusion";diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.tsindex 688361ec..60e10afe 100644--- a/apps/desktop/src/preload.ts+++ b/apps/desktop/src/preload.ts@@ -4,7 +4,7 @@import { contextBridge, ipcRenderer, webUtils } from "electron";import { MAIN_WIRE } from "./main-channels";-import { CLI_WIRE } from "@diffusionstudio/cli/channels";+import { CLI_WIRE } from "@diffusionstudio/cli/protocol";import type { IpcRendererEvent } from "electron";diff --git a/apps/web/package.json b/apps/web/package.jsonindex 619eba2a..a60ab03c 100644--- a/apps/web/package.json+++ b/apps/web/package.json@@ -42,7 +42,8 @@"stats.js": "^0.17.0","tailwind-merge": "^3.4.0","typegpu": "^0.11.9",- "zod": "^4.2.1"+ "zod": "^4.2.1",+ "@diffusionstudio/dapi": "*"},"devDependencies": {"@eslint/js": "^9.39.2",diff --git a/apps/web/src/context/dapi/capture.ts b/apps/web/src/context/dapi/capture.tsindex 28034ae0..375e7bae 100644--- a/apps/web/src/context/dapi/capture.ts+++ b/apps/web/src/context/dapi/capture.ts@@ -16,7 +16,7 @@ import { getParentNode, isScene, Source } from "@diffusionstudio/runtime";import { createCapture } from "@/engine/capture";import { resolveNode } from "./nodes";-import type { CaptureRequest, CaptureResult, TimecodedImage } from "@diffusionstudio/cli/channels";+import type { CaptureRequest, CaptureResult, TimecodedImage } from "@diffusionstudio/dapi";import type { EditorSession } from "./session";// Ceiling on the height a sheet cell renders a node at.diff --git a/apps/web/src/context/dapi/check.ts b/apps/web/src/context/dapi/check.tsindex 15a59505..0aabb6df 100644--- a/apps/web/src/context/dapi/check.ts+++ b/apps/web/src/context/dapi/check.ts@@ -10,7 +10,7 @@ import {import { resolveNode } from "./nodes";-import type { CheckIssue, CheckRequest, CheckResult } from "@diffusionstudio/cli/channels";+import type { CheckIssue, CheckRequest, CheckResult } from "@diffusionstudio/dapi";import type { Entity } from "koota";import type { EditorSession } from "./session";diff --git a/apps/web/src/context/dapi/export.ts b/apps/web/src/context/dapi/export.tsindex a2a6536e..c4e96e85 100644--- a/apps/web/src/context/dapi/export.ts+++ b/apps/web/src/context/dapi/export.ts@@ -18,7 +18,7 @@ import { mainBridge } from "@/lib/ipc";import { MAIN_CHANNELS } from "@desktop/main-channels";import { resolveNode } from "./nodes";-import type { ExportRequest, ExportResult, ExportSettings } from "@diffusionstudio/cli/channels";+import type { ExportRequest, ExportResult, ExportSettings } from "@diffusionstudio/dapi";import type { ContainerFormat, ExportConfig } from "@/engine/project-config";import type { EditorSession } from "./session";diff --git a/apps/web/src/context/dapi/logs.ts b/apps/web/src/context/dapi/logs.tsindex e70d29e5..e45d2389 100644--- a/apps/web/src/context/dapi/logs.ts+++ b/apps/web/src/context/dapi/logs.ts@@ -4,7 +4,7 @@import { mainBridge } from "@/lib/ipc";import { MAIN_CHANNELS } from "@desktop/main-channels";-import type { LogsRequest, LogLevel } from "@diffusionstudio/cli/channels";+import type { LogsRequest, LogLevel } from "@diffusionstudio/dapi";const LEVEL_RANK: Record<LogLevel, number> = { debug: 0, info: 1, warning: 2, error: 3 };diff --git a/apps/web/src/context/dapi/media.ts b/apps/web/src/context/dapi/media.tsindex 74cab872..09c643f9 100644--- a/apps/web/src/context/dapi/media.ts+++ b/apps/web/src/context/dapi/media.ts@@ -16,7 +16,7 @@ import { createProjectFS } from '@/projects/fs';import type { Accessor } from 'solid-js';import type { Asset } from '@diffusionstudio/assets';import type { EditorSession } from './session';-import type { MediaListenRequest, MediaListenResult, MediaFrameRequest, MediaFrameResult, TimecodedImage, MediaProbeRequest, MediaTranscribeRequest, MediaTranscribeResult, MediaFilmstripRequest, MediaFilmstripResult, MediaWaveformRequest, MediaWaveformResult, TranscriptSegment } from "@diffusionstudio/cli/channels";+import type { MediaListenRequest, MediaListenResult, MediaFrameRequest, MediaFrameResult, TimecodedImage, MediaProbeRequest, MediaTranscribeRequest, MediaTranscribeResult, MediaFilmstripRequest, MediaFilmstripResult, MediaWaveformRequest, MediaWaveformResult, TranscriptSegment } from "@diffusionstudio/dapi";type ResolveAsset = (path: string) => Promise<Asset>;diff --git a/apps/web/src/context/dapi/models.ts b/apps/web/src/context/dapi/models.tsindex 9a63257e..2b5b07f5 100644--- a/apps/web/src/context/dapi/models.ts+++ b/apps/web/src/context/dapi/models.ts@@ -7,7 +7,7 @@ import {PROMPT_INPUT_VIDEO_MODEL_OPTIONS,PROMPT_INPUT_AUDIO_MODEL_OPTIONS,} from "@/components/genai/config";-import type { ModelsRequest, ModelInfo } from "@diffusionstudio/cli/channels";+import type { ModelsRequest, ModelInfo } from "@diffusionstudio/dapi";export function handleModels() {return async (req: ModelsRequest) => {diff --git a/apps/web/src/lib/ipc.ts b/apps/web/src/lib/ipc.tsindex 98b61761..54447eaf 100644--- a/apps/web/src/lib/ipc.ts+++ b/apps/web/src/lib/ipc.ts@@ -12,8 +12,8 @@ import type {MainRequestChannel,MainRequestMap,} from "@desktop/main-channels";-import { CLI_WIRE } from "@diffusionstudio/cli/channels";-import type { CliHandshake, CliReply, CliRequest } from "@diffusionstudio/cli/channels";+import { CLI_WIRE } from "@diffusionstudio/cli/protocol";+import type { CliHandshake, CliReply, CliRequest } from "@diffusionstudio/cli/protocol";type EventHandler<C extends MainEventChannel> = (data: MainEventMap[C]) => void;diff --git a/docs/mcp-server.md b/docs/mcp-server.mdnew file mode 100644index 00000000..5b93ba17--- /dev/null+++ b/docs/mcp-server.md@@ -0,0 +1,216 @@+# Design: an MCP server in the app, with the CLI as its client++| | |+| --- | --- |+| Status | Proposal |+| Branch | `mcp-support` |+| Date | 2026-09-02 |+| Scope | `apps/desktop`, `apps/web`, `apps/cli`, a new `packages/dapi`, the editor skill and `reference/` |++## Summary++Today every `dapi` command is a client of nothing and a server of something: the CLI process opens its own WebSocket server, asks the Electron main process over a unix socket to tell the renderer about it, and the renderer dials back and answers one tRPC call. This document proposes the ordinary direction instead. The app hosts one persistent [MCP](https://modelcontextprotocol.io) server in the Electron main process. Agents connect to it directly. The `dapi` binary shrinks to a launcher, a stdio-to-socket pipe for agents, and a thin human-facing client. The tool handlers stay exactly where they are, in the renderer, because that is where the project world, the engine, WebCodecs and WebGPU live.++The point is not MCP for its own sake. The point is that the API gets one definition instead of three, the app becomes reachable without an admin-prompt install step, long operations get progress and cancellation, and the CLI stops needing to match the app's version.++## Goals++- One definition of the API: tool names, input schemas, descriptions and result shapes, owned by the app and served to clients at runtime.+- Agents reach the app with a one-line registration and no PATH install.+- Long operations (export, generation, `listen`) report progress and can be cancelled, without client-side timeouts.+- The CLI binary stays useful for humans, scripts and CI, and no longer has to be built against a specific router type.+- Keep the renderer handlers and their behaviour. This is a transport and surface change, not a rewrite of `capture`, `check`, `export` or the media handlers.++## Non-goals++- A network-reachable server. Everything stays on the local machine, for the local user.+- Changing the web (browser-only) app. It has no `window.desktop` and no CLI today; that stays true.+- Moving media decoding or rendering into the main process.+- Multi-window routing. One window answers, as today.++## The system today++```mermaid+sequenceDiagram+ participant CLI as dapi (per command)+ participant Main as Electron main+ participant R as Renderer+ CLI->>CLI: start WebSocket server on 127.0.0.1:random+ CLI->>Main: unix socket: {port, token}+ Main->>R: IPC cli:connect {port, token}+ Main-->>CLI: {ok: true}+ R->>CLI: ws://127.0.0.1:port?token=…+ CLI->>R: {path: "media.frame", input}+ R->>R: tRPC caller → handler+ R-->>CLI: {ok, data}+ CLI->>CLI: write PNGs, print JSON, exit+```++The pieces, for reference:++- `apps/cli/src/cli-client.ts` hosts the per-command WebSocket server and wraps it in a tRPC link typed against `AppRouter` from `apps/web`.+- `apps/cli/src/index.ts` is a commander program: every command re-describes its arguments and options in help text, validates them, calls the typed client, and formats the result.+- `apps/cli/src/cli-channels.ts` hand-writes the wire types for every request and result.+- `apps/desktop/src/cli-server.ts` listens on `SOCKET_PATH`, waits for the renderer to finish loading, relays the handshake, and switches the app into headless mode on the first connection.+- `apps/web/src/lib/ipc.ts` (`CliBridge`) receives the handshake, dials the CLI, dispatches one request to whichever registered router owns the path, and holds requests that arrive while no router is mounted.+- `apps/web/src/context/dapi/api.tsx` builds the tRPC router over the handlers in the same folder. Inputs are cast, not validated (`apps/web/src/lib/cli-rpc.ts`).++### What is wrong with it++1. **The direction is inverted.** The client hosts the server. That forces the three-hop handshake, a random port, a token to guard it, and a fresh server per call. Main exists in the path only to pass along a port number.+2. **Three descriptions of one API.** Commander help text, the tRPC router's inferred types, and the hand-written wire types all describe the same procedures and can drift. The editor skill tells agents to treat `dapi --help` as authoritative, so the help text is effectively the public schema, maintained by hand.+3. **Version coupling.** The CLI is compiled against one `AppRouter`. A CLI symlinked from a different app build than the one running is silently wrong at the type level and possibly at runtime. The wire has no runtime validation.+4. **No progress, no cancellation.** The client picks a timeout per call (60 s, 10 min for generation, 1 h for export) and there is no way to stop an export once started.+5. **Install friction.** Nothing works until `/usr/local/bin/dapi` exists, which needs the macOS admin prompt in `apps/desktop/src/cli-install.ts`. Every agent session begins by checking that.+6. **Local commands live in the wrong process.** `fonts`, `fetch` (yt-dlp) and `report` run in the CLI process and are unavailable to anything that is not the CLI.++## Proposed architecture++```mermaid+sequenceDiagram+ participant Agent as Agent (Claude Code, …)+ participant Proxy as dapi mcp (stdio pipe)+ participant Main as Electron main: MCP server+ participant R as Renderer: tool handlers+ Agent->>Proxy: spawn; JSON-RPC over stdio+ Proxy->>Main: connect unix socket (launch app if absent)+ Proxy->>Main: bytes, unchanged+ Main->>Main: initialize, tools/list from catalog+ Agent->>Main: tools/call capture {id, times}+ Main->>R: IPC dapi:call {callId, tool, input}+ R-->>Main: IPC dapi:progress {callId, …} (optional)+ R-->>Main: IPC dapi:reply {callId, ok, data}+ Main->>Main: write PNGs, build content blocks+ Main-->>Agent: result {content, structuredContent}+```++Four parts.++### 1. `packages/dapi`: the tool catalog++A new workspace package, `@diffusionstudio/dapi`, that main, the renderer and the CLI all import. It replaces `apps/cli/src/cli-channels.ts` and the `./protocol` and `./channels` exports of the CLI package.++It exports one catalog: for every tool, its name, description, a zod input schema, a zod output schema for the structured result, and where it runs (`renderer` or `main`). The descriptions are the text agents read in `tools/list`, so the long, careful command descriptions currently in `apps/cli/src/index.ts` move here verbatim. The package's main export is free of Node built-ins so the renderer can import it; the `SOCKET_PATH` constant sits behind `@diffusionstudio/dapi/socket`. The IPC envelope types for the main-to-renderer call channel join the package in step 3, when something uses them.++zod is already a dependency of `apps/web`, and the MCP TypeScript SDK takes zod schemas directly, so there is no separate JSON Schema to maintain.++Tools, mapped from today's commands:++| Tool | Today | Runs in | Notes |+| --- | --- | --- | --- |+| `open` | `dapi open <dir>` | renderer | Opens or creates a project and navigates to it. Launching the app is the proxy's job, see part 3. |+| `context` | `dapi context` | renderer | |+| `capture` | `dapi capture` | renderer | Result handling in part 2. |+| `check` | `dapi check` | renderer | |+| `export` | `dapi export` | renderer | Progress and cancellation. |+| `models`, `voices`, `whoami` | same | renderer | |+| `logs` | `dapi logs` | main | Main owns the log buffer already; the renderer handler only forwards to it. |+| `screenshot` | `dapi screenshot` | renderer | |+| `media_probe`, `media_grab`, `media_transcribe`, `media_filmstrip`, `media_waveform`, `media_listen` | `dapi media …` | renderer | `grab` keeps its frame cap and `uncapped` flag as inputs. |+| `fonts` | `dapi fonts` | main | Moves from the CLI process to main. Same code. |+| `fetch` | `dapi fetch` | main | yt-dlp passthrough. Progress goes to MCP progress notifications instead of inherited stderr. |+| `report` | `dapi report` | main | Files the GitHub issue with diagnostics that main already holds. |++Argument parsing that exists today only to turn strings into numbers (`--time "45f"`, `--count`, `--per-sheet`) becomes schema: times are accepted as the same strings and parsed by `parseTime` from `@diffusionstudio/jsx` inside the schema's transform, so the CLI and the agent get identical validation and identical error messages.++### 2. Main process: the server++`apps/desktop/src/cli-server.ts` is replaced by `mcp-server.ts`. It still listens on `SOCKET_PATH` (`/tmp/diffusion-studio.sock` on macOS and Linux, `\\.\pipe\diffusion-studio` on Windows), still cleans up a stale socket file on start, and still enables headless mode on the first connection. What changes is what it speaks.++**Framing.** Each accepted socket carries newline-delimited JSON-RPC, exactly the MCP stdio framing. The SDK exports the `ReadBuffer` and `serializeMessage` helpers used by its stdio transport, so the socket transport is a short class around them. One `McpServer` instance per connection, because the SDK binds one server to one transport. Several agents can be connected at once; each gets its own session.++**Authentication.** None beyond the socket. On macOS the socket lives in the per-user temp directory; on Linux `/tmp` is shared, so the file is created with mode `0600`. The token that guards today's WebSocket server exists only because that server listens on TCP; it is not needed.++**Registration.** On startup main iterates the catalog and calls `registerTool` for each entry. A `main` tool calls its handler directly. A `renderer` tool forwards:++```ts+// apps/desktop/src/mcp-server.ts, sketch+for (const tool of catalog) {+ server.registerTool(tool.name, {+ description: tool.description,+ inputSchema: tool.input,+ outputSchema: tool.output,+ }, async (input, extra) => {+ const data = tool.runsIn === "main"+ ? await mainHandlers[tool.name](input, extra)+ : await callRenderer(tool.name, input, extra); // IPC, below+ return present(tool, data); // content + structuredContent+ });+}+```++**Main-to-renderer calls.** The current bridge (`apps/desktop/src/main-manager.ts` and `MainBridge` in `apps/web/src/lib/ipc.ts`) carries requests from the renderer to main and events from main to the renderer. It has no request in the other direction, so this adds one, with three IPC messages:++- `dapi:call` from main: `{ callId, tool, input }`+- `dapi:progress` from renderer: `{ callId, progress, total?, message? }`+- `dapi:reply` from renderer: `{ callId, ok, data | error }`+- `dapi:cancel` from main: `{ callId }`++Main keeps a map of in-flight calls. Before sending it waits for the renderer to finish loading, which `waitForRendererReady` already does. In the renderer, `CliBridge` loses its WebSocket code and keeps its dispatch and hold-until-a-handler-registers logic, now fed by `dapi:call`. The renderer registers a plain `Record<toolName, handler>` instead of a tRPC router; each handler receives the already-validated input, an `AbortSignal`, and a `report(progress)` callback. tRPC and its `cli-rpc.ts` helpers go away.++**Progress and cancellation.** When the client passes a `progressToken`, main turns `dapi:progress` into `notifications/progress`. When the client sends `notifications/cancelled`, main sends `dapi:cancel` and the handler's `AbortSignal` fires. Client-side timeouts disappear; the client decides how long it is willing to wait. `export` reports encoded frames; `media_listen` and generation-backed work report whatever stage they are in; the others report nothing and that is fine.++**Results.** Every tool returns `structuredContent` matching its output schema, plus a text block with the same JSON so clients that ignore structured content still get it. Tools that produce images (`capture`, `media_grab`, `media_filmstrip`, `media_waveform`, `screenshot`) keep today's behaviour of writing PNGs to an output directory (an `output` input, defaulting to a fresh directory under the temp dir) and returning the paths. In addition, they inline `image` content blocks when the result is small: at most four images and none over about a megabyte. A contact sheet of a few positions therefore arrives in the agent's context immediately, while an uncapped hundred-frame grab arrives as a directory the agent reads selectively, which is the behaviour the current CLI was designed for.++This does mean main sees payloads, which the current design deliberately avoids. The cost is one structured-clone copy over Electron IPC per call. Frame data crosses as `Uint8Array` rather than base64 strings to keep that copy cheap; base64 encoding happens once, in main, only for the blocks that are inlined.++**Resources.** Two things agents poll today are better as MCP resources: `dapi://context` (what `context` returns, so a client can subscribe to changes) and `dapi://logs`. The per-project authoring reference the app writes into each project, which `AGENTS.md` points at, can be listed as a resource too, so an agent can read it without knowing the path. None of this is required for the cut-over; it is listed because it is cheap once the server exists.++### 3. The `dapi` binary++`apps/cli` stays, and stays bundled with the app, but its job changes.++**`dapi mcp`** is the entry point agents register. It is a byte pipe: `process.stdin` to the socket, the socket to `process.stdout`, no JSON parsing. If the socket is absent or refused and the platform is macOS, it launches the app in the background with `open -g -a "Diffusion Studio" --args --hidden`, then retries the connection for up to 30 s, which is the existing `launchApp` and `waitForCliSocket` logic. The proxy needs no SDK dependency, and because it never interprets messages, any app version works with any proxy version. Registration is one line:++```bash+claude mcp add dapi -- dapi mcp+```++or the equivalent `.mcp.json` entry. Because the app bundle ships the binary at a known path under `Contents/Resources/cli/bin/dapi`, the app can also offer that registration itself in place of today's "install CLI" button, without a PATH symlink and without the admin prompt. The symlink install stays available for people who want `dapi` in a shell.++**`dapi open [dir]`** keeps its meaning: launch or surface the app, then call the `open` tool.++**`dapi call <tool> [--json '{…}']`** is the generic client for scripts and debugging. It uses the SDK client over the socket, prints `structuredContent` as JSON on stdout, and writes any inlined images to disk.++**Named wrappers** survive for the commands people type by hand in a shell or in CI: `capture`, `check`, `export`, `context`, `media probe`, `media grab`, at least. They are thin: they build the input object and call `call`. Their help text is generated from the catalog's descriptions, so `dapi <cmd> --help` and `tools/list` say the same thing because they are the same string. Commands nobody types by hand (`voices`, `models`, `whoami`, `screenshot`, `logs`) are reachable through `call` and need no wrapper unless one is missed.++Removed from the CLI package: `cli-client.ts`, `cli-channels.ts`, the tRPC and `ws` dependencies, and `fonts.ts`, `ytdlp.ts` and `report.ts`, which move to main.++### 4. Skill and reference docs++`apps/desktop/skills/editor/SKILL.md` currently says the CLI is self-describing via `--help`. It changes to name the MCP tools and to say that `tools/list` is authoritative, with a short fallback paragraph for environments without MCP (use `dapi call`). The per-command files in `reference/` become per-tool, and their option tables are generated from the catalog so they cannot drift either. `reference/README.md` loses the sentence about "every command talks to the running app over a local socket" and gains one about the server.++## Behaviour that must not change++- **Headless mode** switches on at the first connection, as now.+- **Requests during a project switch** are held and answered once the editor remounts. The queue moves from the renderer's `CliBridge` to being fed by IPC, but the semantics stay.+- **Asset resolution** for `media_*` tools keeps the rule in `createAssetResolver`: library paths need an open project, absolute paths and URLs work without one.+- **Sign-in gating** for `media_listen` and generation stays in the handler.+- **Error text.** Handlers throw with messages written for an agent to read (`No project open — run open first`). Main returns those as `isError` tool results, not JSON-RPC errors, so the agent sees the sentence.++## Migration++The CLI ships inside the app bundle, so there is no compatibility window to maintain between old CLIs and new apps. This can land as one feature branch in ordered steps, each of which builds and type-checks on its own.++1. **Catalog.** Create `packages/dapi` with the tool catalog, `Time`, and `DapiError`, plus tests. Point the renderer handlers' request and result types at it. Delete `apps/cli/src/cli-channels.ts`; `apps/cli/src/protocol.ts` keeps only the handshake and envelope types of the current transport. No behaviour change. *Landed on `mcp-support`.*+2. **Renderer.** Replace the tRPC router in `api.tsx` with a handler map keyed by tool name, validated by the catalog schemas, with `AbortSignal` and progress plumbed in. Replace the WebSocket half of `CliBridge` with the `dapi:call` IPC handling. At this step the old CLI stops working; that is expected.+3. **Main.** Add `mcp-server.ts` with the socket transport, catalog registration, the in-flight map, result presentation, and the `logs`, `fonts`, `fetch` and `report` handlers. Delete `cli-server.ts`. Verify with the MCP Inspector against the socket.+4. **CLI.** Rewrite `apps/cli` as `mcp`, `open`, `call` and the wrappers. Drop tRPC and `ws`. Update `cli-install.ts` and the settings UI to offer MCP registration.+5. **Docs.** Update the skill and regenerate `reference/`. Update the installation reference the skill points to.+6. **Cleanup.** Remove `CLI_WIRE`, the handshake types, and the `./protocol` and `./channels` exports from the CLI package.++## Open questions++- **Inline image thresholds.** Four images and about a megabyte each is a starting point. It should be tuned against what a contact sheet at the default sizes actually weighs.+- **Windows launch.** `open -a` is macOS-only today and the proposal keeps that. Windows and Linux users get a clear "launch the app first" error, as they do now. Worth fixing, not in scope here.+- **HTTP transport later.** Streamable HTTP on loopback would let clients that cannot spawn a process connect. It needs a discovery file for the port and brings back the token. Not needed while every client we care about can run `dapi mcp`.+- **Should `open` launch the app?** The tool cannot launch its own host, so launching stays in the proxy. The alternative, a separate tiny launcher binary, adds a second thing to install for no gain.+- **Concurrency limits.** Today two `dapi` processes can run two captures at once and the renderer copes. With one server that is unchanged, but it becomes easy for an agent to fire several exports in parallel. A per-tool concurrency cap in main is cheap if it turns out to matter.++## Alternatives considered++**Keep tRPC, invert the transport, add `dapi mcp` as a wrapper.** Main hosts a persistent WebSocket server speaking the current envelope; the CLI adds a stdio MCP server that wraps the existing typed client. Least code changed, and it fixes the inverted direction. It keeps the three API descriptions and adds a fourth (the MCP tool schemas in the CLI), and the CLI stays version-coupled to the app. Rejected for that reason.++**MCP over Streamable HTTP only.** Standard, works for clients that cannot spawn processes, and the SDK ships the transport. It needs a fixed or discovered port, a token, and CORS thinking. The socket transport is smaller and the proxy covers every current client; HTTP can be added beside it later.++**Run the MCP server in the renderer.** Keeps main out of the payload path. The renderer cannot listen on a socket, so main would have to be a byte pipe into the page, and progress, cancellation and the hold-until-ready queue would all live in page code that reloads on project switch. The main-process server is simpler and more robust.diff --git a/package-lock.json b/package-lock.jsonindex d48abb1a..f16d06a3 100644--- a/package-lock.json+++ b/package-lock.json@@ -24,6 +24,7 @@"dependencies": {"@babel/core": "^7.29.7","@babel/preset-typescript": "^7.27.1",+ "@diffusionstudio/dapi": "*","@trpc/client": "^11.18.0","@trpc/server": "^11.18.0","babel-preset-solid": "^1.9.12",@@ -49,6 +50,7 @@"@babel/core": "^7.29.7","@babel/preset-typescript": "^7.27.1","@diffusionstudio/cli": "*",+ "@diffusionstudio/dapi": "*","@diffusionstudio/jsx": "*","babel-preset-solid": "^1.9.12","esbuild": "^0.28.1",@@ -94,6 +96,7 @@"@diffusionstudio/api-contract": "^0.1.0","@diffusionstudio/assets": "*","@diffusionstudio/cli": "*",+ "@diffusionstudio/dapi": "*","@diffusionstudio/encoder": "*","@diffusionstudio/jsx": "*","@diffusionstudio/koota-solid": "*",@@ -623,6 +626,10 @@"resolved": "apps/cli","link": true},+ "node_modules/@diffusionstudio/dapi": {+ "resolved": "packages/dapi",+ "link": true+ },"node_modules/@diffusionstudio/desktop": {"resolved": "apps/desktop","link": true@@ -3535,6 +3542,13 @@"solid-js": "^1.8.6"}},+ "node_modules/@standard-schema/spec": {+ "version": "1.1.0",+ "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",+ "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",+ "dev": true,+ "license": "MIT"+ },"node_modules/@supabase/auth-js": {"version": "2.109.0","resolved": "https://registry.npmjs.org/@supabase/auth-js/-/auth-js-2.109.0.tgz",@@ -4077,6 +4091,17 @@"@types/responselike": "^1.0.0"}},+ "node_modules/@types/chai": {+ "version": "5.2.3",+ "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",+ "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@types/deep-eql": "*",+ "assertion-error": "^2.0.1"+ }+ },"node_modules/@types/chrome": {"version": "0.1.43","resolved": "https://registry.npmjs.org/@types/chrome/-/chrome-0.1.43.tgz",@@ -4088,6 +4113,13 @@"@types/har-format": "*"}},+ "node_modules/@types/deep-eql": {+ "version": "4.0.2",+ "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",+ "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",+ "dev": true,+ "license": "MIT"+ },"node_modules/@types/dom-mediacapture-transform": {"version": "0.1.11","resolved": "https://registry.npmjs.org/@types/dom-mediacapture-transform/-/dom-mediacapture-transform-0.1.11.tgz",@@ -4502,6 +4534,119 @@"url": "https://opencollective.com/eslint"}},+ "node_modules/@vitest/expect": {+ "version": "4.1.11",+ "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.11.tgz",+ "integrity": "sha512-VX2x5vNJXET47KAFzwERI+KRMtTTCSWTfSMKsW7JsUsXV4psq++e3DvZpuTDOpHcxytiDs6p2nhVb2tVDiiUYw==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@standard-schema/spec": "^1.1.0",+ "@types/chai": "^5.2.2",+ "@vitest/spy": "4.1.11",+ "@vitest/utils": "4.1.11",+ "chai": "^6.2.2",+ "tinyrainbow": "^3.1.0"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/@vitest/mocker": {+ "version": "4.1.11",+ "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.11.tgz",+ "integrity": "sha512-2XJVD55d1o5AZous5CCGKS74g/riOj9odEt2bQpCVZeblHyHdnMeFl4jl0XjU21stf4mbjUkew2eXQZt65g5CQ==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@vitest/spy": "4.1.11",+ "estree-walker": "^3.0.3",+ "magic-string": "^0.30.21"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ },+ "peerDependencies": {+ "msw": "^2.4.9",+ "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"+ },+ "peerDependenciesMeta": {+ "msw": {+ "optional": true+ },+ "vite": {+ "optional": true+ }+ }+ },+ "node_modules/@vitest/pretty-format": {+ "version": "4.1.11",+ "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.11.tgz",+ "integrity": "sha512-yiZzPbGTS9Sr/JpFl8zHrcIkAofNbFV6k21vIgQN/cY/oxZeXhJv5sc/MBJ5jFKWmWs+oJHw0UXLZjmf931+Vw==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "tinyrainbow": "^3.1.0"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/@vitest/runner": {+ "version": "4.1.11",+ "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.11.tgz",+ "integrity": "sha512-LztvUgdwMNJMIkj3hQnnxiC2Xy1zNxq928W/xhjCLaNCzqTZOudjwbQf6v9IntZGPw132i2Lq2rgTRZHD3JHNw==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@vitest/utils": "4.1.11",+ "pathe": "^2.0.3"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/@vitest/snapshot": {+ "version": "4.1.11",+ "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.11.tgz",+ "integrity": "sha512-pN7ikn1ON7h8ee4gIAp4AzyK+zBtJPzVbqOgu5LCEh4VaJVbPQcgYQYJIMGQPXVeJJq1fnfazis7a5pFNPahog==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@vitest/pretty-format": "4.1.11",+ "@vitest/utils": "4.1.11",+ "magic-string": "^0.30.21",+ "pathe": "^2.0.3"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/@vitest/spy": {+ "version": "4.1.11",+ "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.11.tgz",+ "integrity": "sha512-apNa/prQy2qCeywhnixOHPRCgGNhvg7T4Dapfl1GahLp/R+uhBm5cPyFoNVyqsNd2h1nJxL6BqqdIjiABL60YA==",+ "dev": true,+ "license": "MIT",+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/@vitest/utils": {+ "version": "4.1.11",+ "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.11.tgz",+ "integrity": "sha512-zTCVGpyFsGWBhllOyKlTw/vnr6D9qxsfSDyfbyZmTyjHw5N/VuvzHpHoQjm2ZJzn4RJgx5w4r7V0er69CmLgPQ==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@vitest/pretty-format": "4.1.11",+ "convert-source-map": "^2.0.0",+ "tinyrainbow": "^3.1.0"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },"node_modules/@vscode/sudo-prompt": {"version": "9.3.2","resolved": "https://registry.npmjs.org/@vscode/sudo-prompt/-/sudo-prompt-9.3.2.tgz",@@ -4951,6 +5096,16 @@"dev": true,"license": "Python-2.0"},+ "node_modules/assertion-error": {+ "version": "2.0.1",+ "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",+ "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=12"+ }+ },"node_modules/ast-kit": {"version": "2.2.0","resolved": "https://registry.npmjs.org/ast-kit/-/ast-kit-2.2.0.tgz",@@ -5451,6 +5606,16 @@],"license": "CC-BY-4.0"},+ "node_modules/chai": {+ "version": "6.2.2",+ "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",+ "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=18"+ }+ },"node_modules/chalk": {"version": "4.1.2","resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz",@@ -6701,6 +6866,16 @@"node": ">=4.0"}},+ "node_modules/estree-walker": {+ "version": "3.0.3",+ "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",+ "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@types/estree": "^1.0.0"+ }+ },"node_modules/esutils": {"version": "2.0.3","resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz",@@ -6840,6 +7015,16 @@"which": "bin/which"}},+ "node_modules/expect-type": {+ "version": "1.4.0",+ "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz",+ "integrity": "sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==",+ "dev": true,+ "license": "Apache-2.0",+ "engines": {+ "node": ">=12.0.0"+ }+ },"node_modules/exponential-backoff": {"version": "3.1.3","resolved": "https://registry.npmjs.org/exponential-backoff/-/exponential-backoff-3.1.3.tgz",@@ -8340,6 +8525,7 @@"os": ["android"],+ "peer": true,"engines": {"node": ">= 12.0.0"},@@ -8361,6 +8547,7 @@"os": ["darwin"],+ "peer": true,"engines": {"node": ">= 12.0.0"},@@ -8382,6 +8569,7 @@"os": ["darwin"],+ "peer": true,"engines": {"node": ">= 12.0.0"},@@ -8403,6 +8591,7 @@"os": ["freebsd"],+ "peer": true,"engines": {"node": ">= 12.0.0"},@@ -8424,6 +8613,7 @@"os": ["linux"],+ "peer": true,"engines": {"node": ">= 12.0.0"},@@ -8445,6 +8635,7 @@"os": ["linux"],+ "peer": true,"engines": {"node": ">= 12.0.0"},@@ -8466,6 +8657,7 @@"os": ["linux"],+ "peer": true,"engines": {"node": ">= 12.0.0"},@@ -8487,6 +8679,7 @@"os": ["linux"],+ "peer": true,"engines": {"node": ">= 12.0.0"},@@ -8508,6 +8701,7 @@"os": ["linux"],+ "peer": true,"engines": {"node": ">= 12.0.0"},@@ -8529,6 +8723,7 @@"os": ["win32"],+ "peer": true,"engines": {"node": ">= 12.0.0"},@@ -8550,6 +8745,7 @@"os": ["win32"],+ "peer": true,"engines": {"node": ">= 12.0.0"},@@ -9505,6 +9701,20 @@"node": ">= 0.4"}},+ "node_modules/obug": {+ "version": "2.1.4",+ "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.4.tgz",+ "integrity": "sha512-4a+OsYv9UktOJKE+l1A4OufDgdRF9PifWj+tJnHURo/P+WOxpG4GzUFL9qCalmWauao6ogiG+QvnCovwPoyAWA==",+ "dev": true,+ "funding": [+ "https://github.com/sponsors/sxzz",+ "https://opencollective.com/debug"+ ],+ "license": "MIT",+ "engines": {+ "node": ">=12.20.0"+ }+ },"node_modules/once": {"version": "1.4.0","resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",@@ -10759,6 +10969,13 @@"node": ">=8"}},+ "node_modules/siginfo": {+ "version": "2.0.0",+ "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",+ "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",+ "dev": true,+ "license": "ISC"+ },"node_modules/signal-exit": {"version": "4.1.0","resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",@@ -11003,12 +11220,26 @@"node": "^12.13.0 || ^14.15.0 || >=16.0.0"}},+ "node_modules/stackback": {+ "version": "0.0.2",+ "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",+ "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",+ "dev": true,+ "license": "MIT"+ },"node_modules/stats.js": {"version": "0.17.0","resolved": "https://registry.npmjs.org/stats.js/-/stats.js-0.17.0.tgz","integrity": "sha512-hNKz8phvYLPEcRkeG1rsGmV5ChMjKDAWU7/OJJdDErPBNChQXxCo3WZurGpnWc6gZhAzEPFad1aVgyOANH1sMw==","license": "MIT"},+ "node_modules/std-env": {+ "version": "4.2.0",+ "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.2.0.tgz",+ "integrity": "sha512-oCUKSupKTHX53EyjDtuZQ64pjLJ6yYCtpmEw0goYxtjG9KpbRe8KAsl2tBUGU9DyMcJ0RwJ8GqJAFzMXcXW1Rw==",+ "dev": true,+ "license": "MIT"+ },"node_modules/stream-buffers": {"version": "2.2.0","resolved": "https://registry.npmjs.org/stream-buffers/-/stream-buffers-2.2.0.tgz",@@ -11317,6 +11548,13 @@"dev": true,"license": "MIT"},+ "node_modules/tinybench": {+ "version": "2.9.0",+ "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",+ "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",+ "dev": true,+ "license": "MIT"+ },"node_modules/tinyest": {"version": "0.3.2","resolved": "https://registry.npmjs.org/tinyest/-/tinyest-0.3.2.tgz",@@ -11339,6 +11577,16 @@"node": ">=12.20.0"}},+ "node_modules/tinyexec": {+ "version": "1.3.0",+ "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.0.tgz",+ "integrity": "sha512-QKAl9m8gWWGHV8jZcPeym6j+XULi6tOf1mT83WYJ4Lk2ytW/uwAWkrP0uFsdoYMdueVJ0qs26wZ+23xeB4ibNQ==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=18"+ }+ },"node_modules/tinyglobby": {"version": "0.2.17","resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",@@ -11384,6 +11632,16 @@"url": "https://github.com/sponsors/jonschlinkert"}},+ "node_modules/tinyrainbow": {+ "version": "3.1.1",+ "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.1.tgz",+ "integrity": "sha512-yau8yJdTt989Mm0Bd/236QnzEiPf2xLLTqUZRUJOo/3CB078LSwzei343DgtJVmfJKJE3TMINY1u42SQsP6mXw==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=14.0.0"+ }+ },"node_modules/tmp": {"version": "0.0.33","resolved": "https://registry.npmjs.org/tmp/-/tmp-0.0.33.tgz",@@ -11992,6 +12250,109 @@}}},+ "node_modules/vitest": {+ "version": "4.1.11",+ "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.11.tgz",+ "integrity": "sha512-fhACrNXUidIbGSBr5FlbuBkO7VWC1ZyLl0DO4CU2DrQoAPxX84Ysxs+HeGQpii5lZWV1Q4gBZTTu49mF+A6Edw==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@vitest/expect": "4.1.11",+ "@vitest/mocker": "4.1.11",+ "@vitest/pretty-format": "4.1.11",+ "@vitest/runner": "4.1.11",+ "@vitest/snapshot": "4.1.11",+ "@vitest/spy": "4.1.11",+ "@vitest/utils": "4.1.11",+ "es-module-lexer": "^2.0.0",+ "expect-type": "^1.3.0",+ "magic-string": "^0.30.21",+ "obug": "^2.1.1",+ "pathe": "^2.0.3",+ "picomatch": "^4.0.3",+ "std-env": "^4.0.0-rc.1",+ "tinybench": "^2.9.0",+ "tinyexec": "^1.0.2",+ "tinyglobby": "^0.2.15",+ "tinyrainbow": "^3.1.0",+ "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",+ "why-is-node-running": "^2.3.0"+ },+ "bin": {+ "vitest": "vitest.mjs"+ },+ "engines": {+ "node": "^20.0.0 || ^22.0.0 || >=24.0.0"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ },+ "peerDependencies": {+ "@edge-runtime/vm": "*",+ "@opentelemetry/api": "^1.9.0",+ "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",+ "@vitest/browser-playwright": "4.1.11",+ "@vitest/browser-preview": "4.1.11",+ "@vitest/browser-webdriverio": "4.1.11",+ "@vitest/coverage-istanbul": "4.1.11",+ "@vitest/coverage-v8": "4.1.11",+ "@vitest/ui": "4.1.11",+ "happy-dom": "*",+ "jsdom": "*",+ "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"+ },+ "peerDependenciesMeta": {+ "@edge-runtime/vm": {+ "optional": true+ },+ "@opentelemetry/api": {+ "optional": true+ },+ "@types/node": {+ "optional": true+ },+ "@vitest/browser-playwright": {+ "optional": true+ },+ "@vitest/browser-preview": {+ "optional": true+ },+ "@vitest/browser-webdriverio": {+ "optional": true+ },+ "@vitest/coverage-istanbul": {+ "optional": true+ },+ "@vitest/coverage-v8": {+ "optional": true+ },+ "@vitest/ui": {+ "optional": true+ },+ "happy-dom": {+ "optional": true+ },+ "jsdom": {+ "optional": true+ },+ "vite": {+ "optional": false+ }+ }+ },+ "node_modules/vitest/node_modules/picomatch": {+ "version": "4.0.7",+ "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz",+ "integrity": "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=12"+ },+ "funding": {+ "url": "https://github.com/sponsors/jonschlinkert"+ }+ },"node_modules/watchpack": {"version": "2.5.2","resolved": "https://registry.npmjs.org/watchpack/-/watchpack-2.5.2.tgz",@@ -12150,6 +12511,23 @@"node": ">= 8"}},+ "node_modules/why-is-node-running": {+ "version": "2.3.0",+ "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",+ "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "siginfo": "^2.0.0",+ "stackback": "0.0.2"+ },+ "bin": {+ "why-is-node-running": "cli.js"+ },+ "engines": {+ "node": ">=8"+ }+ },"node_modules/word-wrap": {"version": "1.2.5","resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.5.tgz",@@ -12407,6 +12785,20 @@"typescript": "~5.9.3"}},+ "packages/dapi": {+ "name": "@diffusionstudio/dapi",+ "version": "0.1.0",+ "license": "MPL-2.0",+ "dependencies": {+ "@diffusionstudio/jsx": "*",+ "zod": "^4.4.3"+ },+ "devDependencies": {+ "@types/node": "^24.10.1",+ "typescript": "~5.9.3",+ "vitest": "^4.0.0"+ }+ },"packages/encoder": {"name": "@diffusionstudio/encoder","version": "0.1.0",diff --git a/packages/dapi/README.md b/packages/dapi/README.mdnew file mode 100644index 00000000..207f8dd9--- /dev/null+++ b/packages/dapi/README.md@@ -0,0 +1,15 @@+# @diffusionstudio/dapi++The tool catalog behind `dapi`: one entry per tool with its name, description, and zod input and output schemas. The app registers the catalog with its MCP server, the renderer validates incoming calls against it, and the CLI derives its commands and help text from it, so the API is described exactly once.++```ts+import { catalog, toolByName, Time } from "@diffusionstudio/dapi";+import type { ToolArgs, ToolResult } from "@diffusionstudio/dapi";++const grab = toolByName("media_grab");+const args: ToolArgs<"media_grab"> = grab.input.parse({ path: "/clip.mp4", times: ["45f", "1:10"] });+```++The main export is free of Node built-ins so the renderer can import it. `@diffusionstudio/dapi/socket` exports the socket path and pulls in `node:os`; only Node processes import it.++Design: [docs/mcp-server.md](../../docs/mcp-server.md).diff --git a/packages/dapi/package.json b/packages/dapi/package.jsonnew file mode 100644index 00000000..6a10c94e--- /dev/null+++ b/packages/dapi/package.json@@ -0,0 +1,30 @@+{+ "name": "@diffusionstudio/dapi",+ "version": "0.1.0",+ "description": "The dapi tool catalog: every tool the Diffusion Studio app exposes to agents and the CLI, as a name, a description, and zod input/output schemas. The one definition the app serves, the CLI derives its commands from, and the renderer validates against. Depends on zod and the Time parser only; the socket path lives behind the Node-only `./socket` export.",+ "license": "MPL-2.0",+ "type": "module",+ "sideEffects": false,+ "exports": {+ ".": "./src/index.ts",+ "./socket": "./src/socket.ts"+ },+ "scripts": {+ "check": "tsc --noEmit",+ "test": "vitest run"+ },+ "keywords": [+ "dapi",+ "mcp",+ "zod"+ ],+ "dependencies": {+ "@diffusionstudio/jsx": "*",+ "zod": "^4.4.3"+ },+ "devDependencies": {+ "@types/node": "^24.10.1",+ "typescript": "~5.9.3",+ "vitest": "^4.0.0"+ }+}diff --git a/packages/dapi/src/catalog.test.ts b/packages/dapi/src/catalog.test.tsnew file mode 100644index 00000000..cba7fd8e--- /dev/null+++ b/packages/dapi/src/catalog.test.ts@@ -0,0 +1,42 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { describe, expect, it } from "vitest";+import { z } from "zod";+import { catalog, isToolName, toolByName } from "./catalog";++describe("catalog", () => {+ it("has unique MCP-legal names", () => {+ const names = catalog.map((tool) => tool.name);+ expect(new Set(names).size).toBe(names.length);+ for (const name of names) expect(name).toMatch(/^[a-z][a-z0-9_]{0,63}$/);+ });++ it("describes every tool for an agent, not just a label", () => {+ for (const tool of catalog) {+ expect(tool.title.length, tool.name).toBeGreaterThan(0);+ expect(tool.description.length, tool.name).toBeGreaterThan(40);+ }+ });++ it("takes an object as every tool's input, as MCP requires", () => {+ for (const tool of catalog) {+ expect(tool.input, tool.name).toBeInstanceOf(z.ZodObject);+ }+ });++ it("converts every schema to JSON Schema without throwing", () => {+ for (const tool of catalog) {+ expect(() => z.toJSONSchema(tool.input, { io: "input" }), `${tool.name} input`).not.toThrow();+ expect(() => z.toJSONSchema(tool.output), `${tool.name} output`).not.toThrow();+ }+ });++ it("looks tools up by name", () => {+ expect(toolByName("capture").runsIn).toBe("renderer");+ expect(toolByName("fonts").runsIn).toBe("main");+ expect(isToolName("media_grab")).toBe(true);+ expect(isToolName("media.frame")).toBe(false);+ });+});diff --git a/packages/dapi/src/catalog.ts b/packages/dapi/src/catalog.tsnew file mode 100644index 00000000..0db7d724--- /dev/null+++ b/packages/dapi/src/catalog.ts@@ -0,0 +1,76 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import type { z } from "zod";+import type { Tool } from "./tool";++import { open } from "./tools/open";+import { context } from "./tools/context";+import { capture } from "./tools/capture";+import { check } from "./tools/check";+import { exportScene } from "./tools/export";+import { models } from "./tools/models";+import { voices } from "./tools/voices";+import { whoami } from "./tools/whoami";+import { logs } from "./tools/logs";+import { screenshot } from "./tools/screenshot";+import { mediaProbe } from "./tools/media-probe";+import { mediaGrab } from "./tools/media-grab";+import { mediaTranscribe } from "./tools/media-transcribe";+import { mediaFilmstrip } from "./tools/media-filmstrip";+import { mediaWaveform } from "./tools/media-waveform";+import { mediaListen } from "./tools/media-listen";+import { fonts } from "./tools/fonts";+import { fetchVideo } from "./tools/fetch";+import { report } from "./tools/report";++/**+ * Every tool, in the order a listing shows them: the project loop first+ * (open, look, capture, check, export), then media inspection, then the+ * app and machine utilities.+ */+export const catalog = [+ open,+ context,+ capture,+ check,+ exportScene,+ mediaProbe,+ mediaGrab,+ mediaTranscribe,+ mediaFilmstrip,+ mediaWaveform,+ mediaListen,+ models,+ voices,+ whoami,+ logs,+ screenshot,+ fonts,+ fetchVideo,+ report,+] as const;++export type AnyTool = (typeof catalog)[number];+export type ToolName = AnyTool["name"];+export type ToolByName<N extends ToolName> = Extract<AnyTool, { name: N }>;++/** What a caller sends: times as strings or numbers, defaults omitted. */+export type ToolInput<N extends ToolName> = z.input<ToolByName<N>["input"]>;+/** What a handler receives: parsed, defaults applied. */+export type ToolArgs<N extends ToolName> = z.output<ToolByName<N>["input"]>;+export type ToolResult<N extends ToolName> = z.output<ToolByName<N>["output"]>;++const byName = new Map<string, AnyTool>(catalog.map((tool) => [tool.name, tool]));++export function toolByName<N extends ToolName>(name: N): ToolByName<N> {+ return byName.get(name) as ToolByName<N>;+}++export function isToolName(name: string): name is ToolName {+ return byName.has(name);+}++/** The catalog as the generic `Tool` shape, for code that iterates it. */+export const tools: readonly Tool[] = catalog;diff --git a/packages/dapi/src/errors.ts b/packages/dapi/src/errors.tsnew file mode 100644index 00000000..750784a0--- /dev/null+++ b/packages/dapi/src/errors.ts@@ -0,0 +1,42 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++/**+ * Why a tool call failed, for callers that branch on it: the MCP server maps+ * every code to an `isError` result, the CLI maps it to an exit code, and an+ * agent reads the message. The message is the part written for people.+ */+export type DapiErrorCode =+ /** The tool needs an open project and none is. */+ | "no-project"+ /** No node, asset, or file matches the given id or path. */+ | "not-found"+ /** The id matches several nodes; the caller must disambiguate. */+ | "ambiguous"+ /** The target exists but is the wrong kind, e.g. a clip where a scene is required. */+ | "wrong-kind"+ /** The input failed validation beyond what the schema expresses. */+ | "invalid-input"+ /** A single-slot resource (the export renderer) is in use. */+ | "busy"+ /** The tool needs a signed-in account. */+ | "sign-in-required"+ /** The platform or an external binary (yt-dlp, gh, osascript) cannot do it. */+ | "unsupported"+ /** The caller or the app canceled the operation. */+ | "canceled";++export class DapiError extends Error {+ readonly code: DapiErrorCode;++ constructor(code: DapiErrorCode, message: string, options?: { cause?: unknown }) {+ super(message, options);+ this.name = "DapiError";+ this.code = code;+ }+}++export function isDapiError(value: unknown): value is DapiError {+ return value instanceof DapiError;+}diff --git a/packages/dapi/src/index.ts b/packages/dapi/src/index.tsnew file mode 100644index 00000000..d6ab997b--- /dev/null+++ b/packages/dapi/src/index.ts@@ -0,0 +1,79 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++// Free of Node built-ins on purpose: the renderer imports this. The socket+// path, which needs node:os, lives in `@diffusionstudio/dapi/socket`.++import type { z } from "zod";++export { defineTool } from "./tool";+export type { Tool, RunsIn } from "./tool";++export { catalog, tools, toolByName, isToolName } from "./catalog";+export type { AnyTool, ToolName, ToolByName, ToolInput, ToolArgs, ToolResult } from "./catalog";++export { Time, NonNegativeTime, TIME_FORMS } from "./time";+export type { TimeInput } from "./time";++export { DapiError, isDapiError } from "./errors";+export type { DapiErrorCode } from "./errors";++export { MAX_FRAMES_PER_SHEET } from "./schemas";+export { FRAME_CAP } from "./tools/media-grab";+export { ISSUE_LOG_TAIL } from "./tools/report";++// Named request and result types, for handlers that spell out their+// signature. Each is the parsed (output) side of the tool's schema.+import type { LogEntry as LogEntrySchema, LogLevel as LogLevelSchema, TimecodedImage as TimecodedImageSchema } from "./schemas";+import type { GenerationRow as GenerationRowType } from "./tools/context";+import type { CheckIssue as CheckIssueSchema, CheckIssueCode as CheckIssueCodeSchema } from "./tools/check";+import type { ExportFormat as ExportFormatSchema, ExportSettings as ExportSettingsSchema } from "./tools/export";+import type { ModelInfo as ModelInfoSchema } from "./tools/models";+import type { VoiceInfo as VoiceInfoSchema } from "./tools/voices";+import type { FrameQuality as FrameQualitySchema } from "./tools/media-grab";+import type { TranscriptSegment as TranscriptSegmentSchema, TranscriptWord as TranscriptWordSchema } from "./tools/media-transcribe";+import type { FontFamily as FontFamilySchema } from "./tools/fonts";+import type { ToolArgs, ToolResult } from "./catalog";++export type LogLevel = z.output<typeof LogLevelSchema>;+export type LogEntry = z.output<typeof LogEntrySchema>;+export type TimecodedImage = z.output<typeof TimecodedImageSchema>;+export type GenerationRow = GenerationRowType;+export type CheckIssueCode = z.output<typeof CheckIssueCodeSchema>;+export type CheckIssue = z.output<typeof CheckIssueSchema>;+export type ExportFormat = z.output<typeof ExportFormatSchema>;+export type ExportSettings = z.output<typeof ExportSettingsSchema>;+export type ModelInfo = z.output<typeof ModelInfoSchema>;+export type VoiceInfo = z.output<typeof VoiceInfoSchema>;+export type FrameQuality = z.output<typeof FrameQualitySchema>;+export type TranscriptWord = z.output<typeof TranscriptWordSchema>;+export type TranscriptSegment = z.output<typeof TranscriptSegmentSchema>;+export type FontFamily = z.output<typeof FontFamilySchema>;++export type OpenRequest = ToolArgs<"open">;+export type OpenResult = ToolResult<"open">;+export type ContextResult = ToolResult<"context">;+export type CaptureRequest = ToolArgs<"capture">;+export type CaptureResult = ToolResult<"capture">;+export type CheckRequest = ToolArgs<"check">;+export type CheckResult = ToolResult<"check">;+export type ExportRequest = ToolArgs<"export">;+export type ExportResult = ToolResult<"export">;+export type ModelsRequest = ToolArgs<"models">;+export type LogsRequest = ToolArgs<"logs">;+export type ScreenshotResult = ToolResult<"screenshot">;+export type MediaProbeRequest = ToolArgs<"media_probe">;+export type MediaFrameRequest = ToolArgs<"media_grab">;+export type MediaFrameResult = ToolResult<"media_grab">;+export type MediaTranscribeRequest = ToolArgs<"media_transcribe">;+export type MediaTranscribeResult = ToolResult<"media_transcribe">;+export type MediaFilmstripRequest = ToolArgs<"media_filmstrip">;+export type MediaFilmstripResult = ToolResult<"media_filmstrip">;+export type MediaWaveformRequest = ToolArgs<"media_waveform">;+export type MediaWaveformResult = ToolResult<"media_waveform">;+export type MediaListenRequest = ToolArgs<"media_listen">;+export type MediaListenResult = ToolResult<"media_listen">;+export type FontsRequest = ToolArgs<"fonts">;+export type FetchRequest = ToolArgs<"fetch">;+export type ReportRequest = ToolArgs<"report">;diff --git a/packages/dapi/src/schemas.ts b/packages/dapi/src/schemas.tsnew file mode 100644index 00000000..22ffad93--- /dev/null+++ b/packages/dapi/src/schemas.ts@@ -0,0 +1,97 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++// Building blocks several tools share. A tool file composes these; nothing+// here is a tool on its own.++import { z } from "zod";+import { NonNegativeTime } from "./time";++export const NodeId = z+ .string()+ .min(1)+ .describe("node id from the project's JSX, or `file:id` when two files use the same id");++export const SceneId = z+ .string()+ .min(1)+ .describe("scene id from the project's JSX, or `file:id` when two files use the same id");++export const AssetPath = z+ .string()+ .min(1)+ .describe(+ "absolute file path or URL (works with or without an open project), or a library path like `b-roll/clip.mp4` (needs an open project)",+ );++/** Beyond this the cells get too small to be worth the tokens; use `media_filmstrip`. */+export const MAX_FRAMES_PER_SHEET = 12;++/**+ * One written image: a single frame stamped with its timecode, or a contact+ * sheet stamped with the span it covers (`0f-08s10f`).+ */+export const TimecodedImage = z.object({+ timecode: z.string(),+ base64: z.string().describe("PNG bytes, base64"),+});++/**+ * How frames are laid out: merged into contact sheets (the default) or one+ * image each. `perSheet` only means something for sheets; `checkSheetOptions`+ * rejects it otherwise, so add it to any object that spreads these fields.+ */+export const sheetFields = {+ combine: z+ .boolean()+ .default(true)+ .describe("merge the images into contact sheets of up to 12 cells, each labelled with its timecode (default); false writes one image per position"),+ perSheet: z+ .int()+ .min(1)+ .max(MAX_FRAMES_PER_SHEET)+ .optional()+ .describe("positions per contact sheet, 1-12; fewer means a larger cell each (default: as many as fit)"),+};++export function checkSheetOptions(+ value: { combine: boolean; perSheet?: number | undefined },+ ctx: z.RefinementCtx,+): void {+ if (value.perSheet !== undefined && !value.combine) {+ ctx.addIssue({+ code: "custom",+ path: ["perSheet"],+ message: "perSheet lays out contact sheets; it cannot be combined with combine: false",+ });+ }+}++/** A `[start, end)` window in seconds; both optional, and start must precede end. */+export const windowFields = {+ start: NonNegativeTime.optional(),+ end: NonNegativeTime.optional(),+};++export function checkWindow(+ value: { start?: number | undefined; end?: number | undefined },+ ctx: z.RefinementCtx,+): void {+ if (value.start !== undefined && value.end !== undefined && value.start >= value.end) {+ ctx.addIssue({+ code: "custom",+ path: ["end"],+ message: `start (${value.start}s) must be less than end (${value.end}s)`,+ });+ }+}++export const LogLevel = z.enum(["debug", "info", "warning", "error"]);++export const LogEntry = z.object({+ ts: z.number().describe("unix time, milliseconds"),+ level: LogLevel,+ message: z.string(),+ source: z.string().describe("file:line the entry came from, or empty"),+});diff --git a/apps/cli/src/cli-socket-path.ts b/packages/dapi/src/socket.tssimilarity index 80%rename from apps/cli/src/cli-socket-path.tsrename to packages/dapi/src/socket.tsindex c0e535e6..d38ad1c9 100644--- a/apps/cli/src/cli-socket-path.ts+++ b/packages/dapi/src/socket.ts@@ -8,8 +8,8 @@ import { join } from "node:path";// One socket / named pipe per host. On macOS tmpdir is per-user; on Linux /tmp// is global but the socket file's owner-only mode 0600 keeps it isolated.//-// Kept separate from cli-channels so the renderer can import the channel-// registry and envelope types without pulling in node:os / node:path.+// Its own entry point (`@diffusionstudio/dapi/socket`) so the renderer can+// import the catalog without pulling in node:os / node:path.export const SOCKET_PATH =platform() === "win32"? "\\\\.\\pipe\\diffusion-studio"diff --git a/packages/dapi/src/time.test.ts b/packages/dapi/src/time.test.tsnew file mode 100644index 00000000..c3c299e9--- /dev/null+++ b/packages/dapi/src/time.test.ts@@ -0,0 +1,52 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { describe, expect, it } from "vitest";+import { NonNegativeTime, Time } from "./time";++describe("Time", () => {+ it.each([+ [1.5, 1.5],+ ["1.5", 1.5],+ ["45f", 1.5],+ ["-30f", -1],+ ["1:30", 90],+ ["01:02:03", 3723],+ ["-1", -1],+ [" 2 ", 2],+ ])("parses %j to %d seconds", (input, seconds) => {+ expect(Time.parse(input)).toBe(seconds);+ });++ it.each(["", "abc", "1:2:3:4", "1:x"])(+ "rejects %j with a message that names the accepted forms",+ (input) => {+ const result = Time.safeParse(input);+ expect(result.success).toBe(false);+ if (result.success) return;+ expect(result.error.issues[0]!.message).toMatch(/seconds \("1.5"\), frames \("45f"\), or "MM:SS"/);+ },+ );++ it("rejects other JSON types before trying to parse them", () => {+ expect(Time.safeParse(null).success).toBe(false);+ expect(Time.safeParse({ seconds: 1 }).success).toBe(false);+ expect(Time.safeParse(Number.NaN).success).toBe(false);+ expect(Time.safeParse(Number.POSITIVE_INFINITY).success).toBe(false);+ });+});++describe("NonNegativeTime", () => {+ it("accepts zero and positive times", () => {+ expect(NonNegativeTime.parse(0)).toBe(0);+ expect(NonNegativeTime.parse("0:10")).toBe(10);+ });++ it("rejects negative times after parsing them", () => {+ const result = NonNegativeTime.safeParse("-1f");+ expect(result.success).toBe(false);+ if (result.success) return;+ expect(result.error.issues[0]!.message).toMatch(/non-negative/);+ });+});diff --git a/packages/dapi/src/time.ts b/packages/dapi/src/time.tsnew file mode 100644index 00000000..31a6c5a0--- /dev/null+++ b/packages/dapi/src/time.ts@@ -0,0 +1,30 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { parseTime } from "@diffusionstudio/jsx";++export const TIME_FORMS = `seconds ("1.5"), frames ("45f"), or "MM:SS"`;++/**+ * A point in time as agents and the CLI write it — a number of seconds, a+ * frame count like "45f", or a clock string like "1:30" — parsed to seconds.+ * Negative values are allowed; wrap with `nonNegative` where they are not.+ */+export const Time = z+ .union([z.number(), z.string()])+ .transform((value, ctx) => {+ const seconds = parseTime(value);+ if (seconds === undefined) {+ ctx.addIssue({ code: "custom", message: `expected a time — ${TIME_FORMS} (got "${value}")` });+ return z.NEVER;+ }+ return seconds;+ });++export const NonNegativeTime = Time.refine((seconds) => seconds >= 0, {+ error: `expected a non-negative time — ${TIME_FORMS}`,+});++export type TimeInput = z.input<typeof Time>;diff --git a/packages/dapi/src/tool.ts b/packages/dapi/src/tool.tsnew file mode 100644index 00000000..7c4f1818--- /dev/null+++ b/packages/dapi/src/tool.ts@@ -0,0 +1,36 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import type { z } from "zod";++/**+ * Which process answers the tool. Renderer tools need the open project's+ * world, the engine, or browser media APIs; main tools need the file system+ * or a child process and run without a window.+ */+export type RunsIn = "renderer" | "main";++export interface Tool<+ Name extends string = string,+ Input extends z.ZodObject = z.ZodObject,+ Output extends z.ZodType = z.ZodType,+> {+ /** MCP tool name: `[a-z0-9_]`, unique across the catalog. */+ readonly name: Name;+ /** Short human label, a few words. */+ readonly title: string;+ /** What the tool does, for an agent choosing between tools. */+ readonly description: string;+ /** Always an object: MCP tool arguments are a JSON object by definition. */+ readonly input: Input;+ readonly output: Output;+ readonly runsIn: RunsIn;+}++/** Identity with inference: keeps the literal name and the exact schema types. */+export function defineTool<const Name extends string, Input extends z.ZodObject, Output extends z.ZodType>(+ tool: Tool<Name, Input, Output>,+): Tool<Name, Input, Output> {+ return tool;+}diff --git a/packages/dapi/src/tools/capture.ts b/packages/dapi/src/tools/capture.tsnew file mode 100644index 00000000..56328380--- /dev/null+++ b/packages/dapi/src/tools/capture.ts@@ -0,0 +1,26 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";+import { checkSheetOptions, SceneId, sheetFields, TimecodedImage } from "../schemas";++export const capture = defineTool({+ name: "capture",+ title: "Capture frames",+ description:+ "Render single frames of a scene to PNGs — each frame is the frame an export of that scene would encode, drawn offscreen at the scene's own size. By default the positions are merged into contact sheets: up to 12 per image, each cell labelled with its timecode (`08s10f`, zero segments dropped) and rendered as large as fits, so a few positions arrive as one high-resolution picture instead of a directory to open one by one (combine: false writes a PNG per position, at 720p height). The tool for checking composition (\"what plays at time T\": layout, overlaps, text, timing) and for verifying frames before an export. Scenes only — a single element renders inside its scene, so capture the scene at the times it plays. For a video asset's own full-resolution pixels use media_grab.",+ input: z+ .object({+ id: SceneId,+ frames: z+ .array(z.int().nonnegative())+ .optional()+ .describe("positions to capture as frame numbers relative to the export's first frame, the workarea's start (default: [0])"),+ ...sheetFields,+ })+ .superRefine(checkSheetOptions),+ output: z.array(TimecodedImage),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/check.ts b/packages/dapi/src/tools/check.tsnew file mode 100644index 00000000..74fe81d6--- /dev/null+++ b/packages/dapi/src/tools/check.ts@@ -0,0 +1,49 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";+import { NodeId } from "../schemas";++export const CheckIssueCode = z.enum([+ "black-frames",+ "no-visuals",+ "never-visible",+ "zero-duration",+ "transparent",+ "source-error",+]);++/**+ * One structural finding. `ranges` (where present) are seconds relative to+ * the checked node's start — the same clock `capture` positions use.+ */+export const CheckIssue = z.object({+ code: CheckIssueCode,+ severity: z.enum(["error", "warning"]),+ message: z.string(),+ node: z+ .string()+ .optional()+ .describe("source stamp of the offending node; absent when the issue is about the subtree as a whole"),+ ranges: z.array(z.object({ start: z.number(), end: z.number() })).optional(),+});++export const check = defineTool({+ name: "check",+ title: "Check structure",+ description:+ "Check a node's subtree for obvious structural mistakes, without rendering (local analysis, no credits): spans where no visual is scheduled (likely black frames), children that never become visible, zero-duration or fully transparent nodes, and assets that failed to load or generate — plus subtree stats (node count by kind, nesting depth, played duration). Times in issue ranges are seconds relative to the node's start — for a scene whose workarea starts at 0, the same clock capture uses. Structural only: a scheduled clip can still render black (dark footage, content smaller than the canvas), so confirm suspicious spans visually with capture.",+ input: z.object({ id: NodeId }),+ output: z.object({+ stats: z.object({+ nodes: z.int().describe("nodes in the subtree, the checked node included"),+ byKind: z.record(z.string(), z.int()),+ depth: z.int().describe("deepest nesting level below the checked node (0 = no children)"),+ duration: z.number().describe("seconds the checked node plays (its workarea, when one is set)"),+ }),+ issues: z.array(CheckIssue),+ }),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/context.ts b/packages/dapi/src/tools/context.tsnew file mode 100644index 00000000..c6b40ba8--- /dev/null+++ b/packages/dapi/src/tools/context.ts@@ -0,0 +1,54 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";++const GenerationRow = z.object({+ element: z+ .string()+ .nullable()+ .describe("the element's source stamp, `<file>:<key or position>`; null for an entity no element produced"),+ name: z.string().nullable(),+ state: z.enum(["generating", "failed", "done"]),+ error: z.string().optional().describe("what the generation failed with, on failed rows"),+ asset: z+ .string()+ .optional()+ .describe("the library path the generation landed as, on done rows — ready for media_probe and its siblings"),+});++/**+ * What the project's source cannot say: the JSX already holds the scenes,+ * the selection, and the work area, so the report is only the folders, the+ * playhead, the fonts actually registered, and where generations stand.+ */+export const context = defineTool({+ name: "context",+ title: "App context",+ description:+ "Report the current app context: the application root folder (always reported), the folder of the project the app has open (null when none is), where its playhead sits in seconds, the registered font families, and where its `generate.*` declarations stand. Poll it to wait for generations without blocking.",+ input: z.object({}),+ output: z.union([+ z.object({+ rootDir: z.string().describe("folder projects live under"),+ projectDir: z.null(),+ }),+ z.object({+ rootDir: z.string().describe("folder projects live under"),+ projectDir: z.string().describe("absolute path of the open project"),+ currentTime: z+ .number()+ .nullable()+ .describe("playhead in seconds, the unit the source places clips in; null when no scene is active"),+ fontFamilies: z+ .array(z.string())+ .describe("families registered in the world drawing the project; the editor default is always among them"),+ generations: z.array(GenerationRow),+ }),+ ]),+ runsIn: "renderer",+});++export type GenerationRow = z.output<typeof GenerationRow>;diff --git a/packages/dapi/src/tools/export.ts b/packages/dapi/src/tools/export.tsnew file mode 100644index 00000000..cf5cfc72--- /dev/null+++ b/packages/dapi/src/tools/export.ts@@ -0,0 +1,61 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";+import { SceneId } from "../schemas";++export const ExportFormat = z.enum(["mp4", "webm", "ogg", "mov"]);++// The settings shape mirrors the scene's `diffusion.export.<id>` entry in the+// project's package.json (see the web app's engine/project-config). Codecs+// are strings on the wire; the app validates them against what the encoder+// accepts.+export const ExportSettings = z.object({+ format: ExportFormat.optional(),+ video: z+ .object({+ enabled: z.boolean().optional(),+ codec: z.string().optional(),+ bitrate: z.number().optional(),+ fps: z.number().optional(),+ resolution: z.number().optional(),+ })+ .optional(),+ audio: z+ .object({+ enabled: z.boolean().optional(),+ codec: z.string().optional(),+ sampleRate: z.number().optional(),+ bitrate: z.number().optional(),+ })+ .optional(),+});++export const exportScene = defineTool({+ name: "export",+ title: "Export scene",+ description:+ "Encode a scene to a video file — the same render the app's export runs, covering the scene's workarea. Settings come from the scene's `diffusion.export.<id>` entry in the project's package.json (the entry the app's export panel writes); a scene without one exports with the defaults (1080p H.264 MP4, AAC audio). The output path's extension picks the container, overriding the configured format. Returns the written path and the settings used. One export runs at a time; progress shows in the app. Only export when asked to: capture is the tool for checking a composition.",+ input: z.object({+ id: SceneId,+ path: z+ .string()+ .optional()+ .describe(+ "absolute output file path, ffmpeg-style; its extension picks the container (default: exports/<id>.<format> in the project folder)",+ ),+ }),+ output: z.object({+ path: z.string(),+ width: z.number().describe("encoded pixel width; 0 for an audio-only export"),+ height: z.number().describe("encoded pixel height; 0 for an audio-only export"),+ duration: z.number().describe("seconds"),+ size: z.number().describe("bytes"),+ config: ExportSettings.describe(+ "the settings the export was made with — the package.json entry (or the defaults), with the container the extension resolved to",+ ),+ }),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/fetch.ts b/packages/dapi/src/tools/fetch.tsnew file mode 100644index 00000000..b628c542--- /dev/null+++ b/packages/dapi/src/tools/fetch.ts@@ -0,0 +1,22 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";++export const fetchVideo = defineTool({+ name: "fetch",+ title: "Fetch video",+ description:+ "Download a video with yt-dlp (installed separately). Writes files to disk only and returns their paths (a single URL can yield several, e.g. a playlist).",+ input: z.object({+ url: z.string().min(1).describe("video or page URL to download"),+ output: z.string().optional().describe("output file path or directory (yt-dlp -o template; default: yt-dlp's default)"),+ format: z.string().optional().describe('yt-dlp format selector (default: prefer mp4), e.g. "bv*+ba/b"'),+ audio: z.boolean().optional().describe("extract audio only (yt-dlp -x)"),+ raw: z.array(z.string()).optional().describe('raw yt-dlp flags passed through, e.g. ["--sponsorblock-remove", "all"]'),+ }),+ output: z.object({ paths: z.array(z.string()) }),+ runsIn: "main",+});diff --git a/packages/dapi/src/tools/fonts.ts b/packages/dapi/src/tools/fonts.tsnew file mode 100644index 00000000..4936dbfe--- /dev/null+++ b/packages/dapi/src/tools/fonts.ts@@ -0,0 +1,34 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";++const FontStyle = z.enum(["normal", "italic"]);++export const FontFamily = z.object({+ family: z.string(),+ variants: z.array(+ z.object({+ weight: z.string().describe("CSS weight, 100-900"),+ style: FontStyle,+ source: z.string().describe("CSS `local()` source list"),+ }),+ ),+});++export const fonts = defineTool({+ name: "fonts",+ title: "Local fonts",+ description:+ "List the local fonts available on this machine (macOS only). These family names are valid `fontFamily` values on <text>; each family lists its variants.",+ input: z.object({+ family: z.string().optional().describe("filter to families whose name contains this (case-insensitive)"),+ weights: z.array(z.string()).optional().describe('filter to variants with the given CSS weights, e.g. ["400", "700"]'),+ style: FontStyle.optional().describe("filter to variants with the given style"),+ limit: z.int().min(1).optional().describe("return at most this many families"),+ }),+ output: z.array(FontFamily),+ runsIn: "main",+});diff --git a/packages/dapi/src/tools/logs.ts b/packages/dapi/src/tools/logs.tsnew file mode 100644index 00000000..d959265b--- /dev/null+++ b/packages/dapi/src/tools/logs.ts@@ -0,0 +1,20 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";+import { LogEntry, LogLevel } from "../schemas";++export const logs = defineTool({+ name: "logs",+ title: "App logs",+ description:+ "Recent console output from the running app (what the devtools console shows: page logs, worker logs, uncaught errors), oldest first. The app buffers the last 2000 entries across reloads and project switches, so this replaces relaunching with ELECTRON_ENABLE_LOGGING=1 when debugging renderer-side behavior.",+ input: z.object({+ tail: z.int().min(1).optional().describe("return only the last n entries"),+ level: LogLevel.optional().describe("minimum level to include"),+ }),+ output: z.array(LogEntry),+ runsIn: "main",+});diff --git a/packages/dapi/src/tools/media-filmstrip.ts b/packages/dapi/src/tools/media-filmstrip.tsnew file mode 100644index 00000000..1de24cc2--- /dev/null+++ b/packages/dapi/src/tools/media-filmstrip.ts@@ -0,0 +1,27 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";+import { AssetPath, checkWindow, windowFields } from "../schemas";++/** The window and scale that filmstrip and waveform share. */+export const previewFields = {+ ...windowFields,+ scale: z+ .number()+ .positive()+ .optional()+ .describe("scale factor for the thumbnails; smaller fits more rows and columns, larger fits fewer (default: 1)"),+};++export const mediaFilmstrip = defineTool({+ name: "media_filmstrip",+ title: "Filmstrip preview",+ description:+ "Render a grid of thumbnails sampled across the timeline to a PNG (local render, no credits), each row stamped with an HH:MM:SS:FF ruler. A fast, token-efficient video track preview; narrow the window to zoom into a region of interest. Video only (use media_waveform for audio).",+ input: z.object({ path: AssetPath, ...previewFields }).superRefine(checkWindow),+ output: z.looseObject({ base64: z.string().describe("PNG bytes, base64") }),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/media-grab.ts b/packages/dapi/src/tools/media-grab.tsnew file mode 100644index 00000000..16df6aa2--- /dev/null+++ b/packages/dapi/src/tools/media-grab.ts@@ -0,0 +1,74 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";+import { AssetPath, checkSheetOptions, checkWindow, sheetFields, TimecodedImage, windowFields } from "../schemas";+import { Time } from "../time";++export const FrameQuality = z.enum(["small", "medium", "large", "fullres"]);++/** Guardrail against accidentally decoding a huge number of frames; `uncapped` lifts it. */+export const FRAME_CAP = 100;++export const mediaGrab = defineTool({+ name: "media_grab",+ title: "Grab frames",+ description:+ "Decode frames of a video file and write them as PNGs (local render, no credits). By default the frames are merged into contact sheets: up to 12 per image, each cell labelled with its timecode (`08s10f`, zero segments dropped) and drawn as large as fits, so a handful of frames arrives as one high-resolution picture instead of a directory to open one by one (combine: false writes a PNG per frame). Grabs the asset's own pixels, unlike capture which renders the composited node. The recommended tool for understanding a video at the frame level; past ~12 frames prefer media_filmstrip.",+ input: z+ .object({+ path: AssetPath,+ times: z+ .array(Time)+ .optional()+ .describe(+ 'timestamps to grab — seconds ("1.5"), frames ("45f"), or "MM:SS"; negatives count back from the end, so -1 is one second before the end and -1f one frame before it (default: [0])',+ ),+ count: z+ .int()+ .min(1)+ .optional()+ .describe("instead of times, grab this many frames evenly spaced across the clip (or across the start/end window)"),+ auto: z+ .boolean()+ .optional()+ .describe(+ "scan the clip at 2fps and keep a frame each time the footage settles into a new visual state (transitions are waited out, so picks stay sharp); returns at most count frames (default cap: 30), static footage like screen recordings returns far fewer; requires WebGPU",+ ),+ ...windowFields,+ quality: FrameQuality.optional().describe(+ "frame resolution: small (384x384), medium (768x768), large (1536x1536), or fullres (native); default: as large as the sheet cell allows, or small with combine: false",+ ),+ ...sheetFields,+ uncapped: z+ .boolean()+ .optional()+ .describe(`lift the ${FRAME_CAP}-frame safety cap (grabbing many frames is slow and token-heavy)`),+ })+ .superRefine((value, ctx) => {+ if (value.times !== undefined && value.count !== undefined) {+ ctx.addIssue({ code: "custom", path: ["count"], message: "pass either times or count, not both" });+ }+ if (value.auto && value.times !== undefined) {+ ctx.addIssue({ code: "custom", path: ["times"], message: "auto picks its own timestamps; it cannot be combined with times" });+ }+ const windowed = value.start !== undefined || value.end !== undefined;+ if (windowed && value.count === undefined && !value.auto) {+ ctx.addIssue({ code: "custom", path: ["start"], message: "start and end only apply together with count or auto" });+ }+ checkWindow(value, ctx);+ const requested = value.count ?? value.times?.length ?? 1;+ if (!value.uncapped && requested > FRAME_CAP) {+ ctx.addIssue({+ code: "custom",+ path: [value.count !== undefined ? "count" : "times"],+ message: `grabbing ${requested} frames exceeds the ${FRAME_CAP}-frame cap; pass uncapped: true to override`,+ });+ }+ checkSheetOptions(value, ctx);+ }),+ output: z.array(TimecodedImage),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/media-listen.ts b/packages/dapi/src/tools/media-listen.tsnew file mode 100644index 00000000..c1d13e4d--- /dev/null+++ b/packages/dapi/src/tools/media-listen.ts@@ -0,0 +1,36 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";+import { AssetPath, checkWindow, windowFields } from "../schemas";++export const mediaListen = defineTool({+ name: "media_listen",+ title: "Listen to audio",+ description:+ "Prompt a multimodal model for a semantic analysis of an audio track and return its answer. Shines on audio semantics (the name of the music playing, who is speaking, the spoken content with second-granularity timestamps). Accepts an audio file or a video; by default only the audio track is analyzed. Needs a signed-in account.",+ input: z+ .object({+ path: AssetPath,+ prompt: z.string().optional().describe("question or instruction to guide the analysis"),+ start: windowFields.start.describe(+ "start of the segment to analyze (default: 0); timestamps in the analysis are relative to this point",+ ),+ end: windowFields.end.describe("end of the segment to analyze (default: media duration)"),+ stripVideo: z+ .boolean()+ .optional()+ .describe(+ "for a video asset, analyze the audio track only (default); false keeps the video so the model also reads what is on screen (expensive: uploads the full video)",+ ),+ })+ .superRefine(checkWindow),+ output: z.object({+ result: z.string().optional(),+ start: z.number().optional(),+ end: z.number().optional(),+ }),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/media-probe.ts b/packages/dapi/src/tools/media-probe.tsnew file mode 100644index 00000000..af6d0eec--- /dev/null+++ b/packages/dapi/src/tools/media-probe.ts@@ -0,0 +1,39 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";+import { AssetPath } from "../schemas";++const Track = z.looseObject({+ id: z.number(),+ type: z.string(),+ codec: z.string().nullable(),+ language: z.string(),+ firstTimestamp: z.number(),+ duration: z.number(),+});++export const mediaProbe = defineTool({+ name: "media_probe",+ title: "Probe media",+ description:+ "Read the container and per-track technical metadata of a media file (local read, no credits): container format, duration, tags, and each track's codec params, without decoding. Commonly useful for a quick technical read, e.g. checking codec compatibility or duration before cutting. Packet stats (fps, bitrate) are estimated from a leading sample; images and transcripts report file-level info only.",+ input: z.object({ path: AssetPath }),+ output: z.looseObject({+ id: z.string(),+ name: z.string(),+ path: z.string(),+ type: z.string(),+ mimeType: z.string().optional(),+ size: z.number().describe("bytes"),+ width: z.number().optional(),+ height: z.number().optional(),+ format: z.string().nullable().describe("container name; null when the file could not be read as media"),+ duration: z.number().optional().describe("seconds"),+ tags: z.record(z.string(), z.unknown()).optional(),+ tracks: z.array(Track),+ }),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/media-transcribe.ts b/packages/dapi/src/tools/media-transcribe.tsnew file mode 100644index 00000000..c80917ea--- /dev/null+++ b/packages/dapi/src/tools/media-transcribe.ts@@ -0,0 +1,28 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";+import { AssetPath } from "../schemas";++export const TranscriptWord = z.object({+ text: z.string(),+ start: z.number().describe("seconds"),+ end: z.number().describe("seconds"),+});++export const TranscriptSegment = z.object({+ text: z.string(),+ words: z.array(TranscriptWord),+});++export const mediaTranscribe = defineTool({+ name: "media_transcribe",+ title: "Transcribe speech",+ description:+ "Transcribe the speech in a video or audio file and return the timed transcript, with word-level start/end times in seconds. Commonly useful for footage with speakers (talking head, interview), where the word times let you cut on a line. A transcript marks only speech; the gaps are not necessarily silent (music, score, applause).",+ input: z.object({ path: AssetPath }),+ output: z.object({ segments: z.array(TranscriptSegment) }),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/media-waveform.ts b/packages/dapi/src/tools/media-waveform.tsnew file mode 100644index 00000000..61a17c45--- /dev/null+++ b/packages/dapi/src/tools/media-waveform.ts@@ -0,0 +1,21 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";+import { AssetPath, checkWindow } from "../schemas";+import { previewFields } from "./media-filmstrip";++export const mediaWaveform = defineTool({+ name: "media_waveform",+ title: "Waveform preview",+ description:+ "Render the audio track of a video or audio file as a waveform PNG (local render, no credits) with a timestamp ruler: loudness over time, with silent stretches highlighted in red. A fast, token-efficient audio track preview; the silent spans are also returned as second ranges.",+ input: z.object({ path: AssetPath, ...previewFields }).superRefine(checkWindow),+ output: z.looseObject({+ base64: z.string().describe("PNG bytes, base64"),+ silences: z.array(z.object({ start: z.number(), end: z.number() })).describe("seconds"),+ }),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/models.ts b/packages/dapi/src/tools/models.tsnew file mode 100644index 00000000..f4dade8e--- /dev/null+++ b/packages/dapi/src/tools/models.ts@@ -0,0 +1,29 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";++const ModelType = z.enum(["image", "video", "audio"]);++export const ModelInfo = z.object({+ type: ModelType,+ id: z.string(),+ name: z.string(),+ durations: z.array(z.string()).optional(),+ aspectRatios: z.array(z.string()).optional(),+ features: z.array(z.enum(["start-frame", "end-frame", "audio"])).optional(),+});++export const models = defineTool({+ name: "models",+ title: "Generation models",+ description:+ "List available AI generation models and their per-model constraints (durations, aspect ratios, features), for `generate.*` asset declarations in a project module.",+ input: z.object({+ type: ModelType.optional().describe("filter to one kind of model (default: all three)"),+ }),+ output: z.array(ModelInfo),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/open.ts b/packages/dapi/src/tools/open.tsnew file mode 100644index 00000000..523fbba3--- /dev/null+++ b/packages/dapi/src/tools/open.ts@@ -0,0 +1,22 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";++export const open = defineTool({+ name: "open",+ title: "Open project",+ description:+ "Open a folder as a project in the running app, creating the project files if the folder is not one yet, and show it in the editor. Returns the project's id, display name, and folder. Run this once before tools that need an open project (capture, check, export, context, and library paths in media tools).",+ input: z.object({+ dir: z.string().min(1).describe("absolute path of the project folder to open or create"),+ }),+ output: z.object({+ id: z.string().describe("package.json projectId; empty for a folder that predates ids"),+ name: z.string().describe("display name"),+ dir: z.string().describe("absolute path of the project folder"),+ }),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/report.ts b/packages/dapi/src/tools/report.tsnew file mode 100644index 00000000..6d0523c7--- /dev/null+++ b/packages/dapi/src/tools/report.ts@@ -0,0 +1,24 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";++/** Trailing app log entries attached to an issue by default. */+export const ISSUE_LOG_TAIL = 50;++export const report = defineTool({+ name: "report",+ title: "Report a bug",+ description:+ "Report a bug in dapi or the app itself. Files a GitHub issue on diffusionstudio/editor with diagnostics attached (dapi version, platform, recent app logs) and returns its URL. Submits immediately and publicly through the gh CLI, which must be installed and authenticated; there is no review step, so only report real defects and check the attached logs for anything private.",+ input: z.object({+ title: z.string().min(1).describe("one-line summary of the problem"),+ body: z.string().optional().describe("what happened, in markdown: expected vs actual, and anything the diagnostics won't show"),+ commands: z.array(z.string()).optional().describe("the dapi commands or tool calls that reproduce it, in order"),+ logs: z.int().min(0).optional().describe(`trailing app log entries to attach (0 to omit; default: ${ISSUE_LOG_TAIL})`),+ }),+ output: z.object({ url: z.string() }),+ runsIn: "main",+});diff --git a/packages/dapi/src/tools/screenshot.ts b/packages/dapi/src/tools/screenshot.tsnew file mode 100644index 00000000..c5f7b5ed--- /dev/null+++ b/packages/dapi/src/tools/screenshot.ts@@ -0,0 +1,20 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";++export const screenshot = defineTool({+ name: "screenshot",+ title: "Window screenshot",+ description:+ "Capture the entire application window as a PNG — the full UI as the user sees it (panels, timeline, asset library, canvas viewport), at the window's current size. The tool for checking what the app itself looks like; to render a node or scene cleanly for composition checks use capture instead.",+ input: z.object({}),+ output: z.object({+ base64: z.string().describe("PNG bytes, base64"),+ width: z.number(),+ height: z.number(),+ }),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/tools.test.ts b/packages/dapi/src/tools/tools.test.tsnew file mode 100644index 00000000..31aa8cb7--- /dev/null+++ b/packages/dapi/src/tools/tools.test.ts@@ -0,0 +1,110 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { describe, expect, it } from "vitest";+import { capture } from "./capture";+import { context } from "./context";+import { exportScene } from "./export";+import { logs } from "./logs";+import { mediaFilmstrip } from "./media-filmstrip";+import { mediaGrab } from "./media-grab";+import { mediaListen } from "./media-listen";++/** The messages of a failed parse, keyed by the path they point at. */+function issues(result: { success: boolean; error?: { issues: Array<{ path: PropertyKey[]; message: string }> } }) {+ expect(result.success).toBe(false);+ return Object.fromEntries((result.error?.issues ?? []).map((issue) => [issue.path.join("."), issue.message]));+}++describe("media_grab", () => {+ const input = mediaGrab.input;++ it("parses times in every form and applies the sheet default", () => {+ const args = input.parse({ path: "/clip.mp4", times: ["45f", "1:10", -1, "-2f"] });+ expect(args.times).toEqual([1.5, 70, -1, -2 / 30]);+ expect(args.combine).toBe(true);+ expect(args.perSheet).toBeUndefined();+ });++ it("rejects times together with count", () => {+ expect(issues(input.safeParse({ path: "/c.mp4", times: [1], count: 3 }))).toHaveProperty("count");+ });++ it("rejects auto together with times", () => {+ expect(issues(input.safeParse({ path: "/c.mp4", times: [1], auto: true }))).toHaveProperty("times");+ });++ it("requires count or auto for a window", () => {+ expect(issues(input.safeParse({ path: "/c.mp4", start: 1 }))).toHaveProperty("start");+ expect(input.safeParse({ path: "/c.mp4", start: 1, count: 2 }).success).toBe(true);+ expect(input.safeParse({ path: "/c.mp4", end: "0:10", auto: true }).success).toBe(true);+ });++ it("requires start before end", () => {+ const found = issues(input.safeParse({ path: "/c.mp4", start: 5, end: "2", count: 2 }));+ expect(found.end).toMatch(/start \(5s\) must be less than end \(2s\)/);+ });++ it("rejects negative window bounds but not negative times", () => {+ expect(issues(input.safeParse({ path: "/c.mp4", start: -1, count: 2 }))).toHaveProperty("start");+ expect(input.safeParse({ path: "/c.mp4", times: [-1] }).success).toBe(true);+ });++ it("caps the frame count unless uncapped", () => {+ expect(issues(input.safeParse({ path: "/c.mp4", count: 101 })).count).toMatch(/100-frame cap/);+ expect(input.safeParse({ path: "/c.mp4", count: 101, uncapped: true }).success).toBe(true);+ expect(input.safeParse({ path: "/c.mp4", count: 100 }).success).toBe(true);+ });++ it("rejects perSheet for separate images", () => {+ expect(issues(input.safeParse({ path: "/c.mp4", combine: false, perSheet: 4 }))).toHaveProperty("perSheet");+ expect(issues(input.safeParse({ path: "/c.mp4", perSheet: 13 }))).toHaveProperty("perSheet");+ expect(input.safeParse({ path: "/c.mp4", perSheet: 12 }).success).toBe(true);+ });+});++describe("capture", () => {+ it("takes non-negative integer frames", () => {+ expect(capture.input.parse({ id: "intro", frames: [0, 45] }).frames).toEqual([0, 45]);+ expect(capture.input.safeParse({ id: "intro", frames: [1.5] }).success).toBe(false);+ expect(capture.input.safeParse({ id: "intro", frames: [-1] }).success).toBe(false);+ });++ it("shares the sheet rule with media_grab", () => {+ expect(issues(capture.input.safeParse({ id: "intro", combine: false, perSheet: 2 }))).toHaveProperty("perSheet");+ });+});++describe("media_filmstrip and media_listen", () => {+ it("apply the window rule", () => {+ expect(issues(mediaFilmstrip.input.safeParse({ path: "/c.mp4", start: 3, end: 3 }))).toHaveProperty("end");+ expect(issues(mediaListen.input.safeParse({ path: "/c.mp4", start: "0:05", end: 4 }))).toHaveProperty("end");+ expect(mediaFilmstrip.input.safeParse({ path: "/c.mp4", scale: 0 }).success).toBe(false);+ });+});++describe("logs and export", () => {+ it("validate the small things the CLI used to check by hand", () => {+ expect(logs.input.safeParse({ tail: 0 }).success).toBe(false);+ expect(logs.input.safeParse({ tail: 5, level: "warning" }).success).toBe(true);+ expect(logs.input.safeParse({ level: "verbose" }).success).toBe(false);+ expect(exportScene.input.safeParse({ id: "" }).success).toBe(false);+ });+});++describe("context", () => {+ it("accepts both the closed and the open report", () => {+ expect(context.output.safeParse({ rootDir: "/p", projectDir: null }).success).toBe(true);+ expect(+ context.output.safeParse({+ rootDir: "/p",+ projectDir: "/p/a",+ currentTime: null,+ fontFamilies: ["Inter"],+ generations: [{ element: "index.tsx:3", name: null, state: "done", asset: "gen/a.mp4" }],+ }).success,+ ).toBe(true);+ expect(context.output.safeParse({ rootDir: "/p", projectDir: "/p/a" }).success).toBe(false);+ });+});diff --git a/packages/dapi/src/tools/voices.ts b/packages/dapi/src/tools/voices.tsnew file mode 100644index 00000000..233cc66a--- /dev/null+++ b/packages/dapi/src/tools/voices.ts@@ -0,0 +1,21 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";++export const VoiceInfo = z.object({+ id: z.string(),+ label: z.string(),+ description: z.string(),+});++export const voices = defineTool({+ name: "voices",+ title: "Speech voices",+ description: "List the speech voices available for `generate.voice` declarations in a project module.",+ input: z.object({}),+ output: z.array(VoiceInfo),+ runsIn: "renderer",+});diff --git a/packages/dapi/src/tools/whoami.ts b/packages/dapi/src/tools/whoami.tsnew file mode 100644index 00000000..d1ba3f9d--- /dev/null+++ b/packages/dapi/src/tools/whoami.ts@@ -0,0 +1,15 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++import { z } from "zod";+import { defineTool } from "../tool";++export const whoami = defineTool({+ name: "whoami",+ title: "Signed-in account",+ description: "Report the authenticated account, or null if signed out.",+ input: z.object({}),+ output: z.looseObject({ id: z.string(), email: z.string().optional() }).nullable(),+ runsIn: "renderer",+});diff --git a/packages/dapi/tsconfig.json b/packages/dapi/tsconfig.jsonnew file mode 100644index 00000000..6f6d8c8b--- /dev/null+++ b/packages/dapi/tsconfig.json@@ -0,0 +1,9 @@+{+ "extends": "../../tsconfig.base.json",+ "compilerOptions": {+ "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",+ "lib": ["es2024"],+ "types": ["node"]+ },+ "include": ["src"]+}