diff --git a/README.md b/README.md
index 027019a2..783a5253 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@ Download the desktop app, it walks you through setting everything up:
Motion graphics Video editing Clipping Video understanding and reasoning ` once, then edit the files. Saving recompiles the entry file and mounts it directly into the editor's ECS.
+A project is a folder of that JSX: `open` a folder once (`dapi open ` from a shell), then edit the files. Saving recompiles the entry file and mounts it directly into the editor's ECS.
Every element carries an `id`, which is how the write-back finds its target: a rect dragged on the canvas, a clip trimmed on the timeline, or a retyped line lands as a prop on the element that authored it.
@@ -176,7 +176,7 @@ Everything a mount produces stays a first-class editor node, so a person can pic
## Seeing and hearing the media
-Cutting footage requires understanding it. The CLI ships the inspection tools an agent needs to work with media it cannot watch:
+Cutting footage requires understanding it. The app exposes the inspection tools an agent needs to work with media it cannot watch — as MCP tools, and as the same commands in a shell:
```sh
dapi media probe clip.mp4 # container + codec metadata, like ffprobe
@@ -188,6 +188,8 @@ dapi media listen interview.mp4 -p "what is said in the intro?" # ask a multim
dapi capture intro -t 0 2 4 # the frames a render would produce, by scene id
```
+Each command is the MCP tool of the same name: `dapi media grab` is `media_grab`, `--per-sheet` is `perSheet`.
+
| Command | Purpose |
| --- | --- |
| `dapi open` | Launch the app and open (or create) a project folder, anywhere on disk |
@@ -199,15 +201,15 @@ dapi capture intro -t 0 2 4 # the frames a render w
| `dapi screenshot` / `dapi logs` | The app itself: capture the window, read recent console output |
| `dapi fetch` | Download a video from yt/tt/ig |
| `dapi whoami` | The authenticated account |
-| `dapi report` | Report a bug in the CLI or the app: diagnostics bundled, filed as a GitHub issue via `gh` |
+| `dapi report` | Report a bug in the tools or the app: diagnostics bundled, filed as a GitHub issue via `gh` |
-Conventions throughout: single results are one JSON value, collections are JSON Lines, errors go to stderr with exit code `1`. Everything is built to be piped, grepped, and driven by a program.
+Conventions throughout: every result is one JSON object, the same structured content the MCP tool returns; errors go to stderr with exit code `1`. Everything is built to be piped, grepped, and driven by a program.
## Documentation
-- [CLI reference](reference/README.md): every command, its options, and its output
-- [JSX reference](reference/jsx/README.md): the composition markup with elements, timing, paints, generative assets, and captions
-- [Examples](examples/README.md): runnable compositions, from basic scenes and generative assets to three.js and raw WebGPU
+- [Tool reference](knowledge/reference/tools/README.md): every tool and CLI command, its options, and its output
+- [JSX reference](knowledge/reference/jsx/README.md): the composition markup with elements, timing, paints, generative assets, and captions
+- [Examples](knowledge/examples/README.md): runnable compositions, from basic scenes and generative assets to three.js and raw WebGPU
## Repository layout
@@ -215,7 +217,7 @@ Conventions throughout: single results are one JSON value, collections are JSON
| --- | --- | --- |
| `apps/web` | `@diffusionstudio/web` | The editor UI (Solid + Vite) |
| `apps/desktop` | `@diffusionstudio/desktop` | Electron shell hosting the editor |
-| `apps/cli` | `@diffusionstudio/cli` | The `dapi` CLI |
+| `apps/cli` | `@diffusionstudio/cli` | The `dapi` CLI: a client of the app's MCP server, plus the `dapi mcp` stdio proxy |
| `packages/runtime` | `@diffusionstudio/runtime` | Headless editor runtime: the koota world, traits, actions, systems, media decoding, capture. No DOM, no Solid |
| `packages/reconciler` | `@diffusionstudio/reconciler` | Evaluates a compiled project bundle and reconciles its element tree onto runtime entities, via Solid's universal renderer |
| `packages/jsx` | `@diffusionstudio/jsx` | The authoring API: element vocabulary, types, and generated assets (`generate.*`) |
diff --git a/apps/cli/package.json b/apps/cli/package.json
index 994710b0..8e3ad53e 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -6,30 +6,21 @@
"bin": {
"dapi": "./dist/index.js"
},
- "exports": {
- "./protocol": "./src/protocol.ts",
- "./channels": "./src/cli-channels.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",
+ "build": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/index.js && chmod +x dist/index.js",
"check": "tsc --noEmit",
"symlink:remove": "rm -f /opt/homebrew/bin/dapi",
"symlink:create": "npm run build && ln -sf \"$PWD/dist/index.js\" /opt/homebrew/bin/dapi"
},
"dependencies": {
- "@babel/core": "^7.29.7",
- "@trpc/client": "^11.18.0",
- "@trpc/server": "^11.18.0",
- "@babel/preset-typescript": "^7.27.1",
- "babel-preset-solid": "^1.9.12",
+ "@diffusionstudio/dapi": "*",
+ "@modelcontextprotocol/sdk": "^1.30.0",
"commander": "^14.0.3",
- "esbuild": "^0.28.1",
- "ws": "^8.18.3"
+ "zod": "^4.4.3"
},
"devDependencies": {
- "@types/babel__core": "^7.20.5",
"@types/node": "^24.10.1",
- "@types/ws": "^8.18.1",
+ "esbuild": "^0.28.1",
"typescript": "~5.9.3"
}
}
diff --git a/apps/cli/src/cli-channels.ts b/apps/cli/src/cli-channels.ts
deleted file mode 100644
index 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;
- /** 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.` 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/.` 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.ts
index fc125a02..48a311d3 100644
--- a/apps/cli/src/cli-client.ts
+++ b/apps/cli/src/cli-client.ts
@@ -2,166 +2,109 @@
* 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 { execFile } from "node:child_process";
import { connect } from "node:net";
-import { randomBytes } from "node:crypto";
-import type { AddressInfo } from "node:net";
-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 type { CliHandshake, CliHandshakeReply, CliReply, CliRequest } from "./protocol";
-import type { AppRouter } from "../../web/src/context/dapi";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SOCKET_PATH, SocketTransport } from "@diffusionstudio/dapi/socket";
+import { version } from "../../../package.json";
-const DEFAULT_TIMEOUT_MS = 60000;
-export const GENERATE_TIMEOUT_MS = 600000;
-export const EXPORT_TIMEOUT_MS = 3600000;
+import type { Socket } from "node:net";
+import type { ToolInput, ToolName, ToolOutput } from "@diffusionstudio/dapi";
-// Asks the app (via the unix socket) to have the renderer dial our WebSocket
-// server. Main replies once the connect info has been delivered, so a
-// rejection here means the app is down or the renderer never became ready.
-function requestConnection(handshake: CliHandshake, timeoutMs: number): Promise {
- return new Promise((resolve, reject) => {
- const sock = connect(SOCKET_PATH);
- let buf = "";
- let settled = false;
- const settle = (fn: () => void) => {
- if (settled) return;
- settled = true;
- sock.destroy();
- fn();
- };
+export const APP_NAME = "Diffusion Studio";
- sock.setEncoding("utf8");
- sock.setTimeout(timeoutMs, () =>
- settle(() => reject(new Error("Timed out waiting for the app to accept the connection"))),
- );
- sock.on("connect", () => sock.end(JSON.stringify(handshake)));
- sock.on("data", (chunk) => {
- buf += chunk;
- });
- sock.on("end", () => {
- let reply: CliHandshakeReply;
- try {
- reply = JSON.parse(buf) as CliHandshakeReply;
- } catch (e) {
- settle(() => reject(e instanceof Error ? e : new Error(String(e))));
- return;
- }
- if (reply.ok) settle(resolve);
- else settle(() => reject(new Error(reply.error)));
- });
- sock.on("error", (err) => settle(() => reject(err)));
- });
-}
-
-async function transport(request: CliRequest, timeoutMs: number): Promise {
- const token = randomBytes(16).toString("hex");
- // Frame batches and other base64 replies can exceed ws's 100 MiB default,
- // so disable the payload cap; the server only lives for one request.
- const wss = new WebSocketServer({ host: "127.0.0.1", port: 0, maxPayload: 0 });
+// Renders, AI generation, and downloads outlive the 60s default.
+const TIMEOUTS: Record = {
+ export: 3_600_000,
+ capture: 600_000,
+ media_transcribe: 600_000,
+ media_listen: 600_000,
+ fetch: 600_000,
+};
+/**
+ * Calls one tool in the running app over an MCP session on its socket.
+ * Typed by the catalog: the input is what the tool's schema accepts, the
+ * output its structured content. One session per call; a command makes one
+ * or two, and the process exits when it settles.
+ */
+export async function call(name: N, input: ToolInput): Promise> {
+ const client = new Client({ name: "dapi", version });
try {
- const reply = await new Promise((resolve, reject) => {
- let settled = false;
- const timer = setTimeout(() => {
- settle(() => reject(new Error("Timed out waiting for response")));
- }, timeoutMs);
- const settle = (fn: () => void) => {
- if (settled) return;
- settled = true;
- clearTimeout(timer);
- fn();
- };
-
- wss.on("error", (err) => settle(() => reject(err)));
- wss.on("connection", (ws, req) => {
- const url = new URL(req.url ?? "/", "ws://127.0.0.1");
- if (url.searchParams.get("token") !== token) {
- ws.terminate();
- return;
- }
- ws.on("message", (raw) => {
- try {
- const parsed = JSON.parse(raw.toString()) as CliReply;
- settle(() => resolve(parsed));
- } catch (e) {
- settle(() => reject(e instanceof Error ? e : new Error(String(e))));
- }
- });
- ws.on("close", () =>
- settle(() => reject(new Error("App disconnected before replying"))),
- );
- ws.on("error", (err) => settle(() => reject(err)));
- ws.send(JSON.stringify(request));
- });
-
- wss.once("listening", () => {
- const { port } = wss.address() as AddressInfo;
- requestConnection({ port, token }, timeoutMs).catch((err) =>
- settle(() => reject(err instanceof Error ? err : new Error(String(err)))),
- );
- });
+ await client.connect(new SocketTransport(await openSocket()));
+ const result = await client.callTool({ name, arguments: input as Record }, undefined, {
+ timeout: TIMEOUTS[name] ?? 60_000,
});
+ if (result.isError) {
+ const text = (result.content as Array<{ type: string; text?: string }>)
+ .filter((block) => block.type === "text")
+ .map((block) => block.text)
+ .join("\n");
+ throw new Error(text || `${name} failed`);
+ }
+ return result.structuredContent as ToolOutput;
+ } finally {
+ await client.close().catch(() => {});
+ }
+}
- if (reply.ok) return reply.data;
- throw new Error(reply.error);
+/** Liveness: a round-trip through the app's MCP server. */
+export async function ping(): Promise {
+ const client = new Client({ name: "dapi", version });
+ try {
+ await client.connect(new SocketTransport(await openSocket()));
+ await client.ping();
} finally {
- // Tear down explicitly so no lingering handles keep the Node event loop
- // alive past `console.log(result)` and block the CLI from exiting.
- for (const client of wss.clients) client.terminate();
- wss.close();
+ await client.close().catch(() => {});
}
}
-// Terminating link: each operation runs over its own short-lived WebSocket
-// server that the renderer dials in to. Long-running procedures pass
-// { context: { timeoutMs } } at the call site.
-const cliLink: TRPCLink =
- () =>
- ({ op }) =>
- observable((observer) => {
- const timeoutMs =
- typeof op.context.timeoutMs === "number" ? op.context.timeoutMs : DEFAULT_TIMEOUT_MS;
- transport({ path: op.path, input: op.input }, timeoutMs)
- .then((data) => {
- observer.next({ result: { data } });
- observer.complete();
- })
- .catch((err) => observer.error(TRPCClientError.from(err as Error)));
- // No cancellation: the CLI process exits when the command settles.
- return () => {};
+// Connecting is where "the app is not running" shows up, as ENOENT (no
+// socket file) or ECONNREFUSED (a stale one); see `isAppDown`.
+export function openSocket(): Promise {
+ return new Promise((resolve, reject) => {
+ const socket = connect(SOCKET_PATH);
+ socket.once("connect", () => {
+ socket.off("error", reject);
+ resolve(socket);
});
+ socket.once("error", reject);
+ });
+}
-export const editor = createTRPCClient({ links: [cliLink] });
+export function isAppDown(e: unknown): boolean {
+ const code = (e as NodeJS.ErrnoException | undefined)?.code;
+ return code === "ENOENT" || code === "ECONNREFUSED";
+}
-// Transport failures surface as TRPCClientError wrapping the socket error;
-// unwrap to reach errno codes like ENOENT/ECONNREFUSED.
-export function errnoCode(e: unknown): string | undefined {
- if (!(e instanceof TRPCClientError)) return undefined;
- return (e.cause as NodeJS.ErrnoException | undefined)?.code;
+/**
+ * Launches the app, or surfaces the running instance: `open -a` on a running
+ * app only activates it, so this is safe to always run. macOS only; elsewhere
+ * it resolves false and the caller falls through to the socket.
+ */
+export function launchApp(background: boolean): Promise {
+ if (process.platform !== "darwin") return Promise.resolve(false);
+ const args = background ? ["-g", "-a", APP_NAME, "--args", "--hidden"] : ["-a", APP_NAME];
+ return new Promise((res) => execFile("open", args, (err) => res(!err)));
}
-// Bridges the cold-start gap after launching the app. Main only delivers the
-// handshake once the renderer has finished loading, and `ping` is answered
-// by the always-mounted app router, so a single round-trip proves the app is
-// fully up. The retry loop only handles the brief window before the handshake
-// socket itself binds (ENOENT/ECONNREFUSED).
-export async function waitForCliSocket(timeoutMs = 30000): Promise {
+/**
+ * Bridges the cold-start gap after launching the app: retries while the app
+ * looks down, until it answers a ping (a cold app binds the socket before
+ * its session is ready, so connecting alone proves nothing).
+ */
+export async function waitForApp(timeoutMs = 30000): Promise {
const start = Date.now();
let lastError: unknown = null;
while (Date.now() - start < timeoutMs) {
try {
- await editor.ping.query();
- return;
+ return await ping();
} catch (e) {
+ if (!isAppDown(e)) throw e;
lastError = e;
- const code = errnoCode(e);
- if (code !== "ENOENT" && code !== "ECONNREFUSED") throw e;
await new Promise((r) => setTimeout(r, 200));
}
}
- throw lastError instanceof Error
- ? lastError
- : new Error("Timed out waiting for the app to start");
+ const detail = lastError instanceof Error ? ` (${lastError.message})` : "";
+ throw new Error(`${APP_NAME} did not answer within ${Math.round(timeoutMs / 1000)}s of launching${detail}`);
}
diff --git a/apps/cli/src/cli-socket-path.ts b/apps/cli/src/cli-socket-path.ts
deleted file mode 100644
index c0e535e6..00000000
--- a/apps/cli/src/cli-socket-path.ts
+++ /dev/null
@@ -1,16 +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/. */
-
-import { platform, tmpdir } from "node:os";
-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.
-export const SOCKET_PATH =
- platform() === "win32"
- ? "\\\\.\\pipe\\diffusion-studio"
- : join(tmpdir(), "diffusion-studio.sock");
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 184dac9b..167c6cf9 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -3,602 +3,68 @@
* 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 { execFile } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
import { Command } from "commander";
+import { z } from "zod";
import { version } from "../../../package.json";
-import { parseTime, TIME_FPS } from "@diffusionstudio/jsx";
-import { editor, errnoCode, EXPORT_TIMEOUT_MS, GENERATE_TIMEOUT_MS, waitForCliSocket } from "./cli-client";
-import { 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";
-
-// Long-running commands (renders, AI generation) override the default 60s.
-const GENERATE = { context: { timeoutMs: GENERATE_TIMEOUT_MS } };
-const EXPORT = { context: { timeoutMs: EXPORT_TIMEOUT_MS } };
-
-const APP_NAME = "Diffusion Studio";
-
-function handleSocketError(e: unknown): never {
- const code = errnoCode(e);
- if (code === "ENOENT" || code === "ECONNREFUSED") {
- console.error(`${APP_NAME} is not running. Launch the app first, then retry.`);
- } else {
- console.error((e as Error).message);
- }
- process.exit(1);
-}
-
-const FRAME_QUALITIES: FrameQuality[] = ["small", "medium", "large", "fullres"];
-
-// Guardrail against accidentally decoding a huge number of frames; --uncapped lifts it.
-const FRAME_CAP = 100;
-
-type MediaFrameOptions = {
- time?: string[];
- count?: string;
- start?: string;
- end?: string;
- quality?: string;
- uncapped?: boolean;
- output?: string;
- auto?: boolean;
- separate?: boolean;
- perSheet?: string;
-};
-
-async function mediaFrame(ref: string, opts: MediaFrameOptions): Promise {
- if (opts.time !== undefined && opts.count !== undefined) {
- console.error("Pass either --time or --count, not both.");
- process.exit(1);
- }
- if (opts.auto && opts.time !== undefined) {
- console.error("--auto picks its own timestamps; it cannot be combined with --time.");
- process.exit(1);
- }
-
- let times: number[] | undefined;
- if (opts.time !== undefined) {
- times = opts.time.map((t) => parseTimeArg(t, "--time", true));
- }
-
- let count: number | undefined;
- if (opts.count !== undefined) {
- count = Number(opts.count);
- if (!Number.isInteger(count) || count < 1) {
- console.error(`--count must be a positive integer (got "${opts.count}")`);
- process.exit(1);
- }
- }
-
- const start = opts.start !== undefined ? parseTimeArg(opts.start, "--start") : undefined;
- const end = opts.end !== undefined ? parseTimeArg(opts.end, "--end") : undefined;
- if (start !== undefined && end !== undefined && start >= end) {
- console.error(`--start (${start}s) must be less than --end (${end}s).`);
- process.exit(1);
- }
- if ((start !== undefined || end !== undefined) && count === undefined && !opts.auto) {
- console.error("--start and --end only apply together with --count or --auto.");
- process.exit(1);
- }
-
- const requested = count ?? times?.length ?? 1;
- if (!opts.uncapped && requested > FRAME_CAP) {
- console.error(`Grabbing ${requested} frames exceeds the ${FRAME_CAP}-frame cap; pass --uncapped to override.`);
- process.exit(1);
- }
-
- let quality: FrameQuality | undefined;
- if (opts.quality !== undefined) {
- if (!FRAME_QUALITIES.includes(opts.quality as FrameQuality)) {
- console.error(`--quality must be one of ${FRAME_QUALITIES.join(", ")} (got "${opts.quality}")`);
- process.exit(1);
- }
- quality = opts.quality as FrameQuality;
- }
-
- const perSheet = parsePerSheet(opts.perSheet, opts.separate);
- const target = resolveAssetRef(ref);
- const dir = opts.output ?? join(tmpdir(), `dapi-grab-${randomUUID().slice(0, 8)}`);
- mkdirSync(dir, { recursive: true });
- try {
- const images = await editor.media.frame.query({
- ...target,
- times,
- count,
- start,
- end,
- quality,
- auto: opts.auto,
- combine: !opts.separate,
- perSheet,
- });
- writeImages(images, dir);
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-/**
- * A local file (or frames folder) that exists is sent as its absolute path;
- * 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 {
- const absPath = isAbsolute(ref) ? ref : resolve(process.cwd(), ref);
- if (existsSync(absPath)) return { path: absPath };
- if (isAbsolute(ref)) {
- console.error(`File not found: ${absPath}`);
- process.exit(1);
- }
- return { path: ref };
-}
-
-async function mediaProbe(ref: string): Promise {
- const target = resolveAssetRef(ref);
- const stop = startSpinner("Probing asset");
- try {
- const result = await editor.media.probe.query(target);
- stop();
- console.log(JSON.stringify(result));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
-}
-
-async function mediaTranscribe(ref: string): Promise {
- const target = resolveAssetRef(ref);
- const stop = startSpinner("Transcribing asset");
- try {
- const result = await editor.media.transcribe.query(target, GENERATE);
- stop();
- console.log(JSON.stringify(result));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
-}
-
-type MediaListenOptions = { prompt?: string; start?: string; end?: string; keepVideo?: boolean };
-
-async function mediaListen(ref: string, opts: MediaListenOptions): Promise {
- const start = opts.start !== undefined ? parseTimeArg(opts.start, "--start") : undefined;
- const end = opts.end !== undefined ? parseTimeArg(opts.end, "--end") : undefined;
- if (start !== undefined && end !== undefined && start >= end) {
- console.error(`--start (${start}s) must be less than --end (${end}s).`);
- process.exit(1);
- }
-
- const target = resolveAssetRef(ref);
- const stop = startSpinner("Analyzing asset");
- try {
- const result = await editor.media.listen.query(
- { ...target, prompt: opts.prompt, start, end, stripVideo: !opts.keepVideo },
- GENERATE,
- );
- stop();
- console.log(JSON.stringify(result));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
-}
-
-type MediaPreviewOptions = { start?: string; end?: string; scale?: string; output?: string };
-
-function parseTimeArg(value: string, flag: string, allowNegative = false): number {
- const seconds = parseTime(value);
- if (seconds === undefined || (!allowNegative && seconds < 0)) {
- console.error(
- `${flag} must be a ${allowNegative ? "" : "non-negative "}Time — seconds ("1.5"), frames ("45f"), or "MM:SS" (got "${value}")`,
- );
- process.exit(1);
- }
- return seconds;
-}
-
-// Frames and contact sheets arrive in the same shape: the app stamps each
-// image with its timecode (`08s10f`, or `0f-08s10f` for a sheet), which is the
-// filename too.
-function writeImages(images: TimecodedImage[], dir: string): void {
- for (const { timecode, base64 } of images) {
- const path = join(dir, `${timecode}.png`);
- writeFileSync(path, Buffer.from(base64, "base64"));
- console.log(JSON.stringify({ timecode, path }));
- }
-}
-
-function parsePerSheet(value: string | undefined, separate?: boolean): number | undefined {
- if (value === undefined) return undefined;
- if (separate) {
- console.error("--per-sheet lays out contact sheets; it cannot be combined with --separate.");
- process.exit(1);
- }
- const n = Number(value);
- if (!Number.isInteger(n) || n < 1 || n > MAX_FRAMES_PER_SHEET) {
- console.error(`--per-sheet must be an integer between 1 and ${MAX_FRAMES_PER_SHEET} (got "${value}")`);
- process.exit(1);
- }
- return n;
-}
-
-// Parse the window/scale flags shared by `filmstrip` and `waveform`.
-function parsePreviewWindow(opts: MediaPreviewOptions): { start?: number; end?: number; scale?: number } {
- const start = opts.start !== undefined ? parseTimeArg(opts.start, "--start") : undefined;
- const end = opts.end !== undefined ? parseTimeArg(opts.end, "--end") : undefined;
- if (start !== undefined && end !== undefined && start >= end) {
- console.error(`--start (${start}s) must be less than --end (${end}s).`);
- process.exit(1);
- }
-
- let scale: number | undefined;
- if (opts.scale !== undefined) {
- scale = Number(opts.scale);
- if (!Number.isFinite(scale) || scale <= 0) {
- console.error(`--scale must be a positive number (got "${opts.scale}")`);
- process.exit(1);
- }
- }
-
- return { start, end, scale };
-}
-
-async function mediaFilmstrip(ref: string, opts: MediaPreviewOptions): Promise {
- const { start, end, scale } = parsePreviewWindow(opts);
- const target = resolveAssetRef(ref);
- const path = opts.output ?? join(tmpdir(), `${randomUUID()}.png`);
- mkdirSync(dirname(resolve(path)), { recursive: true });
- const stop = startSpinner("Rendering filmstrip");
- try {
- const { base64, ...rest } = await editor.media.filmstrip.query({ ...target, start, end, scale });
- stop();
- writeFileSync(path, Buffer.from(base64, "base64"));
- console.log(JSON.stringify({ path, ...rest }));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
-}
+import { toolByName } from "@diffusionstudio/dapi";
+import { MCP_URL } from "@diffusionstudio/dapi/socket";
+import { APP_NAME, call, isAppDown, launchApp, ping, waitForApp } from "./cli-client";
+import { runProxy } from "./mcp-proxy";
-async function mediaWaveform(ref: string, opts: MediaPreviewOptions): Promise {
- const { start, end, scale } = parsePreviewWindow(opts);
- const target = resolveAssetRef(ref);
- const path = opts.output ?? join(tmpdir(), `${randomUUID()}.png`);
- mkdirSync(dirname(resolve(path)), { recursive: true });
- const stop = startSpinner("Rendering waveform");
- try {
- const { base64, ...rest } = await editor.media.waveform.query({ ...target, start, end, scale });
- stop();
- writeFileSync(path, Buffer.from(base64, "base64"));
- console.log(JSON.stringify({ path, ...rest }));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
-}
-
-type CaptureOptions = { time?: string[]; output?: string; separate?: boolean; perSheet?: string };
-
-async function captureNode(id: string, opts: CaptureOptions): Promise {
- const times = (opts.time ?? ["0"]).map((t) => parseTimeArg(t, "--time"));
- const frames = times.map((t) => Math.round(t * TIME_FPS));
- const perSheet = parsePerSheet(opts.perSheet, opts.separate);
-
- const dir = opts.output ?? join(tmpdir(), `dapi-capture-${randomUUID().slice(0, 8)}`);
- mkdirSync(dir, { recursive: true });
- try {
- const images = await editor.capture.query(
- { id, frames, combine: !opts.separate, perSheet },
- GENERATE,
- );
- writeImages(images, dir);
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-async function exportScene(id: string, output: string | undefined): Promise {
- // The app owns everything else: settings come from the project's
- // package.json, the extension check and the default output path need the
- // config and project folder, which live on its side of the socket.
- const path = output !== undefined ? resolve(process.cwd(), output) : undefined;
- const stop = startSpinner("Exporting scene");
- try {
- const result = await editor.export.mutate({ id, path }, EXPORT);
- stop();
- console.log(JSON.stringify(result));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
-}
-
-async function checkNode(id: string): Promise {
- try {
- const result = await editor.check.query({ id });
- console.log(JSON.stringify(result));
- // Linter convention: issues found is a different failure than "could not run".
- if (result.issues.some((issue) => issue.severity === "error")) process.exitCode = 1;
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-type OpenOptions = { background?: boolean };
-
-/** `open -a` on a running app only activates it, so this is safe to always run. */
-function launchApp(background: boolean): Promise {
- const args = background ? ["-g", "-a", APP_NAME, "--args", "--hidden"] : ["-a", APP_NAME];
- return new Promise((res) => execFile("open", args, (err) => res(!err)));
-}
-
-async function openProject(path: string | undefined, opts: OpenOptions): Promise {
- // Launching is macOS's job; elsewhere (and when the app is not installed,
- // e.g. a dev checkout run from the terminal) fall through to the socket,
- // which answers if the app is running and errors usefully if not.
- const launched = process.platform === "darwin" && (await launchApp(opts.background ?? false));
-
- try {
- // A cold launch needs the renderer up before the app can answer; when
- // nothing was launched there is nothing to wait for, so fail fast.
- if (launched) await waitForCliSocket();
- else await editor.ping.query();
-
- if (path !== undefined) {
- const result = await editor.open.mutate({ dir: resolve(path) });
- console.log(JSON.stringify(result));
- }
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-async function context(): Promise {
- try {
- const result = await editor.context.query();
- console.log(JSON.stringify(result));
- } catch (e) {
- handleSocketError(e);
- }
-}
+import type { GenericTool, ToolInput, ToolName } from "@diffusionstudio/dapi";
-async function whoami(): Promise {
- try {
- const result = await editor.whoami.query();
- console.log(JSON.stringify(result));
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-const LOG_LEVELS = ["debug", "info", "warning", "error"] as const;
-
-type LogsOptions = { tail?: string; level?: string };
-
-async function showLogs(opts: LogsOptions): Promise {
- if (opts.level !== undefined && !LOG_LEVELS.includes(opts.level as LogLevel)) {
- console.error(`--level must be one of ${LOG_LEVELS.join(", ")} (got "${opts.level}")`);
- process.exit(1);
- }
- let tail: number | undefined;
- if (opts.tail !== undefined) {
- const n = Number(opts.tail);
- if (!Number.isInteger(n) || n <= 0) {
- console.error(`--tail must be a positive integer (got "${opts.tail}")`);
- process.exit(1);
- }
- tail = n;
- }
-
- try {
- const entries = await editor.logs.query({ tail, level: opts.level as LogLevel | undefined });
- for (const entry of entries) console.log(formatLogEntry(entry));
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-function formatLogEntry(entry: LogEntry): string {
- const pad = (n: number, w = 2) => String(n).padStart(w, "0");
- const d = new Date(entry.ts);
- const time = `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`;
- const source = entry.source ? ` (${entry.source})` : "";
- return `${time} [${entry.level}] ${entry.message}${source}`;
-}
-
-type ScreenshotOptions = { output?: string };
-
-// `diffusion-studio_2026-07-31_08-55-12.png`
-function screenshotFilename(taken: Date, attempt: number): string {
- const pad = (value: number) => String(value).padStart(2, "0");
- const date = [taken.getFullYear(), pad(taken.getMonth() + 1), pad(taken.getDate())].join("-");
- const time = [pad(taken.getHours()), pad(taken.getMinutes()), pad(taken.getSeconds())].join("-");
- const slug = APP_NAME.toLowerCase().replace(/[^a-z0-9]+/g, "-");
- return `${slug}_${date}_${time}${attempt > 1 ? `-${attempt}` : ""}.png`;
-}
-
-async function appScreenshot(opts: ScreenshotOptions): Promise {
- const dir = opts.output ?? tmpdir();
- mkdirSync(dir, { recursive: true });
- try {
- const { base64, width, height } = await editor.screenshot.query();
- const taken = new Date();
- let attempt = 1;
- let path = join(dir, screenshotFilename(taken, attempt));
- while (existsSync(path)) {
- path = join(dir, screenshotFilename(taken, ++attempt));
- }
- writeFileSync(path, Buffer.from(base64, "base64"));
- console.log(JSON.stringify({ path, width, height }));
- } catch (e) {
- handleSocketError(e);
- }
+function fail(message: string): never {
+ console.error(message);
+ process.exit(1);
}
-type IssueOptions = { body?: string; command?: string[]; logs?: string };
-
-const ISSUE_LOG_TAIL = 50;
-
-async function reportIssue(title: string, opts: IssueOptions): Promise {
- const summary = title.trim();
- if (!summary) {
- console.error("A one-line title is required.");
- process.exit(1);
- }
-
- let tail = ISSUE_LOG_TAIL;
- if (opts.logs !== undefined) {
- const n = Number(opts.logs);
- if (!Number.isInteger(n) || n < 0) {
- console.error(`--logs must be a non-negative integer (got "${opts.logs}")`);
- process.exit(1);
- }
- tail = n;
- }
-
- // The app being broken (or down) is exactly what gets reported, so a failed
- // log read is recorded in the report rather than failing the command.
- let logs: string[] | undefined;
- let appStatus = "not checked";
- if (tail > 0) {
- try {
- logs = (await editor.logs.query({ tail })).map(formatLogEntry);
- appStatus = "running";
- } catch (e) {
- const code = errnoCode(e);
- appStatus = code === "ENOENT" || code === "ECONNREFUSED"
- ? "not running"
- : `unreachable (${(e as Error).message})`;
- }
- }
-
- const body = buildIssueBody({
- title: summary,
- body: opts.body,
- commands: opts.command,
- logs,
- appStatus,
- version,
- });
-
- let url: string;
- try {
- url = await createIssue(summary, body);
- } catch (e) {
- console.error((e as Error).message);
- process.exit(1);
- }
-
- console.log(JSON.stringify({ url }));
+function appError(e: unknown): never {
+ if (isAppDown(e)) fail(`${APP_NAME} is not running. Launch the app first, then retry.`);
+ fail((e as Error).message);
}
-function startSpinner(label: string): () => void {
- if (!process.stderr.isTTY) {
- process.stderr.write(`${label}…\n`);
- return () => { };
- }
- const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
- const start = Date.now();
- let i = 0;
- const render = () => {
- const secs = Math.floor((Date.now() - start) / 1000);
- process.stderr.write(`\r${frames[i]} ${label}… ${secs}s`);
- i = (i + 1) % frames.length;
- };
- render();
- const timer = setInterval(render, 80);
- return () => {
- clearInterval(timer);
- process.stderr.write("\r\x1b[K"); // carriage return + clear to end of line
- };
+/** The tool's description, verbatim. */
+function describe(name: ToolName): string {
+ return toolByName(name).description;
}
-async function listModels(type: string | undefined): Promise {
- if (type !== undefined && type !== "image" && type !== "video" && type !== "audio") {
- console.error(`[type] must be one of "image", "video", "audio" (got "${type}")`);
- process.exit(1);
- }
- try {
- const models = await editor.models.query({ type: type as "image" | "video" | "audio" | undefined });
- for (const model of models) console.log(JSON.stringify(model));
- } catch (e) {
- handleSocketError(e);
- }
+/** An input field's description, verbatim, for the option that maps onto it. */
+function field(name: ToolName, key: string): string {
+ const tool: GenericTool = toolByName(name);
+ const schema = tool.input.shape[key];
+ if (schema === undefined) throw new Error(`tool ${name} has no input field "${key}"`);
+ return schema.description ?? "";
}
-async function listVoices(): Promise {
- try {
- const voices = await editor.voices.query();
- for (const voice of voices) console.log(JSON.stringify(voice));
- } catch (e) {
- handleSocketError(e);
- }
+/**
+ * Checks the input against the tool's schema, calls the tool, and prints
+ * what the app returns — its structured content, as one JSON object, the
+ * same thing an agent receives. Strings stay strings: times like "45f" are
+ * parsed by the schema on both sides.
+ */
+async function run(name: N, input: ToolInput): Promise {
+ const parsed = toolByName(name).input.safeParse(input);
+ if (!parsed.success) fail(z.prettifyError(parsed.error));
+ const output = await call(name, input).catch(appError);
+ console.log(JSON.stringify(output));
}
-type ListFontsOptions = {
- family?: string;
- weight?: string[];
- style?: string;
- limit?: string;
- namesOnly?: boolean;
-};
-
-function listFonts(opts: ListFontsOptions): void {
- let style: "normal" | "italic" | undefined;
- if (opts.style !== undefined) {
- if (opts.style !== "normal" && opts.style !== "italic") {
- console.error(`--style must be "normal" or "italic" (got "${opts.style}")`);
- process.exit(1);
- }
- style = opts.style;
- }
-
- let limit: number | undefined;
- if (opts.limit !== undefined) {
- const n = Number(opts.limit);
- if (!Number.isInteger(n) || n <= 0) {
- console.error(`--limit must be a positive integer (got "${opts.limit}")`);
- process.exit(1);
- }
- limit = n;
- }
-
- try {
- const families = listLocalFonts({
- familyPattern: opts.family,
- weights: opts.weight,
- style,
- limit,
- });
- if (opts.namesOnly) {
- for (const family of families) console.log(family.family);
- } else {
- for (const family of families) console.log(JSON.stringify(family));
- }
- } catch (e) {
- console.error((e as Error).message);
- process.exit(1);
- }
-}
+// Numbers are converted so the schema can check them as numbers; an empty or
+// non-numeric string becomes NaN, which the schema rejects with its own message.
+const numeric = (value: string): number => (value.trim() === "" ? NaN : Number(value));
-type FetchCliOptions = { output?: string; format?: string; audio?: boolean };
-
-// `raw` is every operand after `url` — the yt-dlp passthrough placed after `--`.
-// No spinner here: yt-dlp renders its own progress to the inherited stderr.
-async function fetch(url: string, opts: FetchCliOptions, raw: string[]): Promise {
- try {
- const paths = await fetchVideo(url, { ...opts, raw });
- for (const path of paths) console.log(JSON.stringify({ path }));
- } catch (e) {
- console.error((e as Error).message);
- process.exit(1);
- }
+/**
+ * A local file (or frames folder) that exists is sent as its absolute path;
+ * 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 assetPath(ref: string): string {
+ const abs = resolve(ref);
+ if (existsSync(abs)) return abs;
+ if (isAbsolute(ref)) fail(`File not found: ${abs}`);
+ return ref;
}
const program = new Command();
@@ -608,58 +74,66 @@ program
.description(
`The Diffusion Studio CLI: understand, generate, and edit footage.
Analyze video/audio/images, generate them with AI, and compose assets.
-Use for any media analysis, media generation, or video editing task. No ffmpeg needed.`,
+Use for any media analysis, media generation, or video editing task. No ffmpeg needed.
+
+Every command wraps one tool of the running app's MCP server, which agents reach at ${MCP_URL} once the app runs (\`dapi open\`).`,
)
.version(version);
+program
+ .command("mcp")
+ .description(
+ `Serve the app's MCP server on stdio, for agents that cannot connect over HTTP (Claude Desktop). Every other agent should register the URL ${MCP_URL} instead, which the running app serves — \`dapi open\` starts it. Register this with \`claude mcp add dapi -- dapi mcp\` (or the equivalent entry in the agent's MCP config) and the agent gets every command below as a tool, with the same descriptions. Launches ${APP_NAME} in the background if it is not running (macOS).`,
+ )
+ .action(() => runProxy().catch((e: Error) => fail(e.message)));
+
program
.command("open")
.description(
- `Launch ${APP_NAME} (or surface the running instance) and, given a path, open that folder as a project.`,
+ `Launch ${APP_NAME} (or surface the running instance) and, given a path, open that folder as a project, creating the project files if the folder is not one yet. Prints the project's id, display name, and folder. Run this once before commands that need an open project (capture, check, export, context, and library paths in media commands).`,
)
- .argument("[path]", "project folder to open or create (default: none — just launch the app)")
+ .argument("[path]", `${field("open", "dir")} (default: none — just launch the app)`)
.option("-b, --background", "launch or keep the app in the background, without raising a window")
- .action((path: string | undefined, opts: OpenOptions) => openProject(path, opts));
+ .action(async (path: string | undefined, opts: { background?: boolean }) => {
+ const launched = await launchApp(opts.background ?? false);
+ await (launched ? waitForApp() : ping()).catch(appError);
+ if (path !== undefined) await run("open", { dir: resolve(path) });
+ });
program
.command("context")
.alias("ctx")
- .description(
- `Print 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 generations stand.`,
- )
- .action(() => context());
+ .description(describe("context"))
+ .action(() => run("context", {}));
program
.command("capture")
- .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 (\`--separate\` 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\`.`,
- )
- .argument("", 'scene id to capture or `file:id` when two files use the same id')
- .option("-t, --time ", `one or more positions to capture, relative to the export's first frame, the workarea's start (0 = the export's frame 0) — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0)`)
- .option("-S, --separate", "write one PNG per position instead of merging them into contact sheets")
- .option("--per-sheet ", "positions per contact sheet, 1-12; fewer means a larger cell each (default: as many as fit)")
- .option("-o, --output ", "directory to write the PNGs into (default: a fresh dir in the system temp dir)")
- .action((id: string, opts: CaptureOptions) => captureNode(id, opts));
+ .description(describe("capture"))
+ .argument("", field("capture", "id"))
+ .option("-t, --times ", field("capture", "times"))
+ .option("-S, --separate", field("capture", "separate"))
+ .option("--per-sheet ", field("capture", "perSheet"), numeric)
+ .option("-o, --output ", field("capture", "output"))
+ .action((id: string, opts: Omit, "id">) =>
+ run("capture", { id, ...opts, output: opts.output && resolve(opts.output) }),
+ );
program
.command("export")
- .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.\` 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] extension picks the container, overriding the configured format. Prints one JSON object with the written path and the settings used. One export runs at a time; progress shows in the app.`,
- )
- .argument("", 'scene id to export or `file:id` when two files use the same id')
- .argument(
- "[output]",
- 'output file path, ffmpeg-style; its extension picks the container (default: "exports/." in the project folder)',
- )
- .action((id: string, output: string | undefined) => exportScene(id, output));
+ .description(describe("export"))
+ .argument("", field("export", "id"))
+ .argument("[output]", field("export", "path"))
+ .action((id: string, output: string | undefined) => run("export", { id, path: output && resolve(output) }));
program
.command("check")
- .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). Prints one JSON object; times in issue ranges are seconds relative to the node's start — for a scene whose workarea starts at 0, the same clock \`capture --time\` uses. Exits 1 when an error-severity issue is found. Structural only: a scheduled clip can still render black (dark footage, content smaller than the canvas), so confirm suspicious spans visually with \`capture\`.`,
- )
- .argument("", 'node id to check or `file:id` when two files use the same id')
- .action((id: string) => checkNode(id));
+ .description(`${describe("check")} Exits 1 when an error-severity issue is found.`)
+ .argument("", field("check", "id"))
+ .action(async (id: string) => {
+ const output = await call("check", { id }).catch(appError);
+ console.log(JSON.stringify(output));
+ if (output.issues.some((issue) => issue.severity === "error")) process.exitCode = 1;
+ });
const media = program
.command("media")
@@ -670,148 +144,131 @@ const media = program
media
.command("probe")
- .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.`,
- )
- .argument("", "local file path")
- .action((ref: string) => mediaProbe(ref));
+ .description(describe("media_probe"))
+ .argument("", field("media_probe", "path"))
+ .action((ref: string) => run("media_probe", { path: assetPath(ref) }));
media
.command("transcribe")
- .description(
- `Transcribe the speech in a video or audio file and print 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).`,
- )
- .argument("", "local video or audio file path")
- .action((ref: string) => mediaTranscribe(ref));
+ .description(describe("media_transcribe"))
+ .argument("", field("media_transcribe", "path"))
+ .action((ref: string) => run("media_transcribe", { path: assetPath(ref) }));
media
.command("grab")
.alias("sample")
- .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 (\`--separate\` 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\`.`,
- )
- .argument("", "local video file path to grab frames from")
- .option("-t, --time ", `one or more 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)`)
- .option("-c, --count ", "instead of --time, grab this many frames evenly spaced across the clip (or across the --start/--end window)")
- .option("-a, --auto", "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")
- .option("-s, --start ", `with --count or --auto, start of the window to sample (seconds, "45f" frames, or "MM:SS"; default: 0)`)
- .option("-e, --end ", `with --count or --auto, end of the window to sample (seconds, "45f" frames, or "MM:SS"; default: asset duration)`)
- .option("-q, --quality ", "frame resolution: small (384x384), medium (768x768), large (1536x1536), or fullres (native); default: as large as the sheet cell allows, or small with --separate")
- .option("-S, --separate", "write one PNG per frame instead of merging them into contact sheets")
- .option("--per-sheet ", "frames per contact sheet, 1-12; fewer frames means a larger cell each (default: as many as fit)")
- .option("--uncapped", "lift the 100-frame safety cap (grabbing many frames is slow and token-heavy)")
- .option("-o, --output ", "directory to write the PNGs into (default: a fresh dir in the system temp dir)")
- .action((ref: string, opts: MediaFrameOptions) => mediaFrame(ref, opts));
+ .description(describe("media_grab"))
+ .argument("", field("media_grab", "path"))
+ .option("-t, --times ", field("media_grab", "times"))
+ .option("-c, --count ", field("media_grab", "count"), numeric)
+ .option("-a, --auto", field("media_grab", "auto"))
+ .option("-s, --start ", field("media_grab", "start"))
+ .option("-e, --end ", field("media_grab", "end"))
+ .option("-q, --quality ", field("media_grab", "quality"))
+ .option("-S, --separate", field("media_grab", "separate"))
+ .option("--per-sheet ", field("media_grab", "perSheet"), numeric)
+ .option("--uncapped", field("media_grab", "uncapped"))
+ .option("-o, --output ", field("media_grab", "output"))
+ .action((ref: string, opts: Omit, "path">) =>
+ run("media_grab", { path: assetPath(ref), ...opts, output: opts.output && resolve(opts.output) }),
+ );
media
.command("filmstrip")
.alias("film")
- .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).`,
- )
- .argument("", "local video file path to preview")
- .option("-s, --start ", `start of the window to preview — seconds, "45f" frames, or "MM:SS" (default: 0)`)
- .option("-e, --end ", `end of the window to preview — seconds, "45f" frames, or "MM:SS" (default: asset duration)`)
- .option("-x, --scale ", "scale factor for the thumbnails; smaller thumbnails fit more rows and columns, larger fit fewer (default: 1)")
- .option("-o, --output ", "write the PNG here instead of a temp file")
- .action((ref: string, opts: MediaPreviewOptions) => mediaFilmstrip(ref, opts));
+ .description(describe("media_filmstrip"))
+ .argument("", field("media_filmstrip", "path"))
+ .option("-s, --start ", field("media_filmstrip", "start"))
+ .option("-e, --end ", field("media_filmstrip", "end"))
+ .option("-x, --scale ", field("media_filmstrip", "scale"), numeric)
+ .option("-o, --output ", field("media_filmstrip", "output"))
+ .action((ref: string, opts: Omit, "path">) =>
+ run("media_filmstrip", { path: assetPath(ref), ...opts, output: opts.output && resolve(opts.output) }),
+ );
media
.command("waveform")
.alias("wave")
- .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.`,
- )
- .argument("", "local video or audio file path to preview")
- .option("-s, --start ", `start of the window to preview — seconds, "45f" frames, or "MM:SS" (default: 0)`)
- .option("-e, --end ", `end of the window to preview — seconds, "45f" frames, or "MM:SS" (default: asset duration)`)
- .option("-x, --scale ", "scale factor for the waveform; smaller fits more rows and columns, larger fits fewer (default: 1)")
- .option("-o, --output ", "write the PNG here instead of a temp file")
- .action((ref: string, opts: MediaPreviewOptions) => mediaWaveform(ref, opts));
+ .description(describe("media_waveform"))
+ .argument("", field("media_waveform", "path"))
+ .option("-s, --start ", field("media_waveform", "start"))
+ .option("-e, --end ", field("media_waveform", "end"))
+ .option("-x, --scale ", field("media_waveform", "scale"), numeric)
+ .option("-o, --output ", field("media_waveform", "output"))
+ .action((ref: string, opts: Omit, "path">) =>
+ run("media_waveform", { path: assetPath(ref), ...opts, output: opts.output && resolve(opts.output) }),
+ );
media
.command("listen")
- .description(
- `Prompt a multimodal model for a semantic analysis of an audio track and print 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.`,
- )
- .argument("", "local video or audio file path to analyze")
- .option("-p, --prompt ", "question or instruction to guide the analysis")
- .option("-s, --start ", `start of the segment to analyze — seconds, "45f" frames, or "MM:SS" (default: 0); timestamps in the analysis are relative to this point`)
- .option("-e, --end ", `end of the segment to analyze — seconds, "45f" frames, or "MM:SS" (default: media duration)`)
- .option("--keep-video", "for a video asset, keep the video track instead of stripping to audio, so the model also reads what is on screen (expensive: uploads the full video)")
- .action((ref: string, opts: MediaListenOptions) => mediaListen(ref, opts));
+ .description(describe("media_listen"))
+ .argument("", field("media_listen", "path"))
+ .option("-p, --prompt ", field("media_listen", "prompt"))
+ .option("-s, --start ", field("media_listen", "start"))
+ .option("-e, --end ", field("media_listen", "end"))
+ .action((ref: string, opts: Omit, "path">) => run("media_listen", { path: assetPath(ref), ...opts }));
program
.command("models")
- .description(
- `List available AI generation models and their per-model constraints (durations, aspect ratios, features), for \`generate.*\` asset declarations in a project module.`,
- )
- .argument("[type]", `filter to one of "image", "video", "audio" (default: all three)`)
- .action((type: string | undefined) => listModels(type));
+ .description(describe("models"))
+ .argument("[type]", field("models", "type"))
+ .action((type: ToolInput<"models">["type"]) => run("models", { type }));
program
.command("voices")
- .description(`List the speech voices available for \`generate.voice\` declarations in a project module.`)
- .action(() => listVoices());
+ .description(describe("voices"))
+ .action(() => run("voices", {}));
program
.command("whoami")
- .description(`Print the authenticated account, or null if signed out.`)
- .action(() => whoami());
+ .description(describe("whoami"))
+ .action(() => run("whoami", {}));
program
.command("logs")
- .description(
- `Print recent console output from the running app (what the devtools console shows: page logs, worker logs, uncaught errors), oldest first, one line per entry: local time, level, message, source location. 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.`,
- )
- .option("-n, --tail ", "output only the last entries")
- .option("-l, --level ", `minimum level to include: "debug", "info", "warning", or "error"`)
- .action((opts: LogsOptions) => showLogs(opts));
+ .description(describe("logs"))
+ .option("-n, --tail ", field("logs", "tail"), numeric)
+ .option("-l, --level ", field("logs", "level"))
+ .action((opts: ToolInput<"logs">) => run("logs", opts));
program
.command("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.`,
- )
- .option("-o, --output ", "directory to write the PNG into (default: system temp dir)")
- .action((opts: ScreenshotOptions) => appScreenshot(opts));
+ .description(describe("screenshot"))
+ .option("-o, --output ", field("screenshot", "output"))
+ .action((opts: ToolInput<"screenshot">) => run("screenshot", { output: opts.output && resolve(opts.output) }));
program
.command("report")
.alias("issue")
- .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 prints 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.`,
- )
- .argument("", "one-line summary of the problem")
- .option("-b, --body <text>", "what happened, in markdown: expected vs actual, and anything the diagnostics won't show")
- .option("-c, --command <cmd...>", "the dapi command(s) that reproduce it, in order; repeatable")
- .option("--logs <n>", `trailing app log entries to attach (0 to omit; default: ${ISSUE_LOG_TAIL})`)
- .action((title: string, opts: IssueOptions) => reportIssue(title, opts));
+ .description(describe("report"))
+ .argument("<title>", field("report", "title"))
+ .option("-b, --body <text>", field("report", "body"))
+ .option("-c, --commands <cmd...>", field("report", "commands"))
+ .option("--logs <n>", field("report", "logs"), numeric)
+ .action((title: string, opts: Omit<ToolInput<"report">, "title">) => run("report", { title, ...opts }));
program
.command("fonts")
- .description(
- `List the local fonts available on this machine (macOS only; does not require the app). These family names are valid \`fontFamily\` values on <text>; each family lists its variants.`,
- )
- .option("-f, --family <pattern>", "filter to families whose name contains <pattern> (case-insensitive)")
- .option("-w, --weight <weights...>", "filter to variants with the given CSS weight(s), e.g. -w 400 700")
- .option("-s, --style <style>", `filter to variants with the given style: "normal" or "italic"`)
- .option("-l, --limit <n>", "output at most <n> families")
- .option("-n, --names-only", "output only family names (one per line, no variant detail)")
- .action((opts: ListFontsOptions) => listFonts(opts));
+ .description(describe("fonts"))
+ .option("-f, --family <pattern>", field("fonts", "family"))
+ .option("-w, --weights <weights...>", field("fonts", "weights"))
+ .option("-s, --style <style>", field("fonts", "style"))
+ .option("-l, --limit <n>", field("fonts", "limit"), numeric)
+ .action((opts: ToolInput<"fonts">) => run("fonts", opts));
program
.command("fetch")
- .description(
- `Download a video with yt-dlp (installed separately; does not require the app). Writes files to disk only (a single URL can yield several, e.g. a playlist).`,
- )
- .argument("<url>", "video or page URL to download")
- .option("-o, --output <path>", "output file path or directory (yt-dlp -o template; default: yt-dlp's default)")
- .option("-f, --format <selector>", `yt-dlp format selector (default: prefer mp4), e.g. "bv*+ba/b"`)
- .option("-a, --audio", "extract audio only (yt-dlp -x)")
+ .description(describe("fetch"))
+ .argument("<url>", field("fetch", "url"))
+ .option("-o, --output <path>", field("fetch", "output"))
+ .option("-f, --format <selector>", field("fetch", "format"))
+ .option("-a, --audio", field("fetch", "audio"))
.allowExcessArguments()
.addHelpText("after", `\nForward raw yt-dlp flags after --, e.g. dapi fetch <url> -- --sponsorblock-remove all`)
- .action((url: string, opts: FetchCliOptions, cmd: Command) => fetch(url, opts, cmd.args.slice(1)));
+ .action((url: string, opts: Omit<ToolInput<"fetch">, "url" | "raw">, cmd: Command) =>
+ // `raw` is every operand after `url` — the yt-dlp passthrough placed after `--`.
+ run("fetch", { url, ...opts, raw: cmd.args.slice(1), output: opts.output && resolve(opts.output) }),
+ );
// Explicit argv convention: the packaged wrapper runs this bundle on
// Electron in ELECTRON_RUN_AS_NODE mode, where commander would otherwise
diff --git a/apps/cli/src/mcp-proxy.ts b/apps/cli/src/mcp-proxy.ts
new file mode 100644
index 00000000..92d99c68
--- /dev/null
+++ b/apps/cli/src/mcp-proxy.ts
@@ -0,0 +1,41 @@
+/* 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/. */
+
+// `dapi mcp`: the entry point agents register. A byte pipe between stdio and
+// the app's socket — the socket already carries MCP in stdio framing, so
+// nothing here parses a message, and any app version works with any proxy
+// version. Stdout belongs to the protocol; anything for a human goes to
+// stderr.
+
+import { APP_NAME, isAppDown, launchApp, openSocket, waitForApp } from "./cli-client";
+
+import type { Socket } from "node:net";
+
+export async function runProxy(): Promise<void> {
+ let socket: Socket;
+ try {
+ socket = await openSocket();
+ } catch (e) {
+ if (!isAppDown(e)) throw e;
+ // Launching is macOS's job; elsewhere the user starts the app by hand.
+ if (!(await launchApp(true))) {
+ throw new Error(`${APP_NAME} is not running. Launch the app first, then retry.`);
+ }
+ await waitForApp();
+ socket = await openSocket();
+ }
+
+ socket.on("error", (error) => {
+ console.error(`[dapi mcp] ${error.message}`);
+ process.exit(1);
+ });
+ // The app went away (quit, or the session was closed): the agent sees EOF.
+ socket.on("close", () => process.exit(0));
+ // The agent went away: tell the app, which ends the session.
+ process.stdin.on("end", () => socket.end());
+ process.stdout.on("error", () => socket.destroy());
+
+ process.stdin.pipe(socket);
+ socket.pipe(process.stdout);
+}
diff --git a/apps/cli/src/protocol.ts b/apps/cli/src/protocol.ts
deleted file mode 100644
index d4d60007..00000000
--- a/apps/cli/src/protocol.ts
+++ /dev/null
@@ -1,11 +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/. */
-
-// 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";
diff --git a/apps/cli/src/untyped-modules.d.ts b/apps/cli/src/untyped-modules.d.ts
deleted file mode 100644
index 736500ea..00000000
--- a/apps/cli/src/untyped-modules.d.ts
+++ /dev/null
@@ -1,15 +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/. */
-
-// Babel presets ship no type declarations; they are only ever passed opaquely
-// into @babel/core's `presets` option.
-declare module "babel-preset-solid" {
- const preset: unknown;
- export default preset;
-}
-
-declare module "@babel/preset-typescript" {
- const preset: unknown;
- export default preset;
-}
diff --git a/apps/cli/src/ytdlp.ts b/apps/cli/src/ytdlp.ts
deleted file mode 100644
index c184a2b4..00000000
--- a/apps/cli/src/ytdlp.ts
+++ /dev/null
@@ -1,74 +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/. */
-
-import { spawn, spawnSync } from "node:child_process";
-
-// Resolve the binary once. YT_DLP_PATH mirrors DIFFUSION_APP_PATH: an escape
-// hatch for pinned or non-PATH installs.
-const BIN = process.env.YT_DLP_PATH ?? "yt-dlp";
-
-// Fails with an actionable message before any download is attempted. ENOENT is
-// the "not installed" case; a non-zero status means the binary is present but
-// broken.
-function assertInstalled(): void {
- const probe = spawnSync(BIN, ["--version"], { encoding: "utf8" });
- if (probe.error) {
- if ((probe.error as NodeJS.ErrnoException).code === "ENOENT") {
- throw new Error(
- `yt-dlp not found. Install it (brew install yt-dlp, or pipx install yt-dlp) ` +
- `or set YT_DLP_PATH to its location.`,
- );
- }
- throw new Error(probe.error.message);
- }
- if (probe.status !== 0) {
- throw new Error(probe.stderr?.trim() || "yt-dlp is present but not runnable.");
- }
-}
-
-export type FetchOptions = {
- output?: string;
- format?: string;
- audio?: boolean;
- raw?: string[];
-};
-
-// Downloads the URL and resolves to the final file path(s) on disk. yt-dlp's
-// own `after_move:filepath` reports what actually landed (post extraction /
-// rename), so we never guess the name. --quiet silences stdout chatter while
-// --progress forces the progress bar to stderr, keeping stdout to just the
-// paths we capture.
-export function fetchVideo(url: string, opts: FetchOptions = {}): Promise<string[]> {
- assertInstalled();
-
- const args = ["--quiet", "--no-warnings", "--progress", "--print", "after_move:filepath"];
- if (opts.output) args.push("-o", opts.output);
- if (opts.format) {
- args.push("-f", opts.format);
- } else if (!opts.audio) {
- // Default to mp4: prefer mp4/m4a streams, then remux the merged result so
- // the landed file is a .mp4 even when only WebM/mkv sources were available.
- // An explicit -f or --audio opts out.
- args.push("-f", "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/bv*+ba/b", "--merge-output-format", "mp4");
- }
- if (opts.audio) args.push("-x");
- if (opts.raw?.length) args.push(...opts.raw);
- args.push(url);
-
- return new Promise((resolve, reject) => {
- // stdout: resolved paths (captured); stderr: live progress (inherited).
- const child = spawn(BIN, args, { stdio: ["ignore", "pipe", "inherit"] });
- let out = "";
- child.stdout.setEncoding("utf8");
- child.stdout.on("data", (chunk) => (out += chunk));
- child.on("error", reject);
- child.on("close", (code) => {
- if (code === 0) {
- resolve(out.split("\n").map((line) => line.trim()).filter(Boolean));
- } else {
- reject(new Error(`yt-dlp exited with code ${code}.`));
- }
- });
- });
-}
diff --git a/apps/cli/tsconfig.json b/apps/cli/tsconfig.json
index c3835eb7..ac304146 100644
--- a/apps/cli/tsconfig.json
+++ b/apps/cli/tsconfig.json
@@ -2,40 +2,9 @@
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
- // The AppRouter type import in cli-client.ts pulls renderer sources into
- // this program, so the web app's compiler settings (DOM, solid JSX, vite
- // types, aliases) apply here on top of the node ones.
- "useDefineForClassFields": true,
- "erasableSyntaxOnly": false,
- "lib": [
- "es2024",
- "DOM",
- "DOM.Iterable"
- ],
- "types": [
- "node",
- "vite-plugin-solid-svg/types-component-solid",
- "vite/client",
- "@types/audioworklet",
- "@types/wicg-file-system-access",
- "@webgpu/types"
- ],
- "resolveJsonModule": true,
- "allowImportingTsExtensions": true,
- "jsx": "preserve",
- "jsxImportSource": "solid-js",
- "baseUrl": "./",
- "paths": {
- "@/*": [
- "../web/src/*"
- ],
- "@desktop/*": [
- "../desktop/src/*"
- ]
- }
+ "lib": ["es2024"],
+ "types": ["node"],
+ "resolveJsonModule": true
},
- "include": [
- "src",
- "../web/src/vite-env.d.ts"
- ]
+ "include": ["src"]
}
diff --git a/apps/desktop/.gitignore b/apps/desktop/.gitignore
index 5f140748..54f86506 100644
--- a/apps/desktop/.gitignore
+++ b/apps/desktop/.gitignore
@@ -2,5 +2,4 @@ dist
web
out
cli
-docs
-skills
+knowledge
diff --git a/apps/desktop/forge.config.ts b/apps/desktop/forge.config.ts
index 5cfa8ce6..7bddecf7 100644
--- a/apps/desktop/forge.config.ts
+++ b/apps/desktop/forge.config.ts
@@ -27,9 +27,9 @@ const config: ForgeConfig = {
!path.startsWith('/dist/') &&
path !== '/web' &&
!path.startsWith('/web/'),
- // Staged by scripts/stage-{cli,docs,skills}.mjs; end up at
- // Contents/Resources/{cli,docs,skills}.
- extraResource: ['./cli', './docs', './skills'],
+ // Staged by scripts/stage-{cli,knowledge}.mjs; end up at
+ // Contents/Resources/{cli,knowledge}.
+ extraResource: ['./cli', './knowledge'],
osxSign: process.env.SKIP_SIGN ? undefined : {},
osxNotarize:
process.env.APPLE_ID && process.env.APPLE_PASSWORD && process.env.APPLE_TEAM_ID
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 20c0d2ba..553d10e8 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -15,14 +15,14 @@
"build": "npm run check && npm run build:main && npm run build:preload && npm run build:native",
"build:web": "npm --prefix ../web run build:desktop",
"stage:cli": "npm --prefix ../cli run build && node scripts/stage-cli.mjs",
- "stage:docs": "node scripts/stage-docs.mjs",
- "stage:skills": "node scripts/stage-skills.mjs",
+ "stage:knowledge": "node scripts/stage-knowledge.mjs",
"check": "tsc --noEmit",
"dev": "npm run build && electron-forge start",
- "package": "npm run build && npm run build:web && npm run stage:cli && npm run stage:docs && npm run stage:skills && electron-forge package",
- "make": "npm run build && npm run build:web && npm run stage:cli && npm run stage:docs && npm run stage:skills && electron-forge make",
- "publish": "npm run build && npm run build:web && npm run stage:cli && npm run stage:docs && npm run stage:skills && electron-forge publish",
- "make:icns": "sh scripts/make-icns.sh"
+ "package": "npm run build && npm run build:web && npm run stage:cli && npm run stage:knowledge && electron-forge package",
+ "make": "npm run build && npm run build:web && npm run stage:cli && npm run stage:knowledge && electron-forge make",
+ "publish": "npm run build && npm run build:web && npm run stage:cli && npm run stage:knowledge && electron-forge publish",
+ "make:icns": "sh scripts/make-icns.sh",
+ "test": "vitest run"
},
"devDependencies": {
"@electron-forge/cli": "^7.11.1",
@@ -32,13 +32,15 @@
"@types/babel__core": "^7.20.5",
"@types/node": "^24.10.1",
"electron": "^43.1.1",
- "typescript": "~5.9.3"
+ "typescript": "~5.9.3",
+ "vitest": "^4.0.0"
},
"dependencies": {
"@babel/core": "^7.29.7",
"@babel/preset-typescript": "^7.27.1",
- "@diffusionstudio/cli": "*",
+ "@diffusionstudio/dapi": "*",
"@diffusionstudio/jsx": "*",
+ "@modelcontextprotocol/sdk": "^1.30.0",
"babel-preset-solid": "^1.9.12",
"esbuild": "^0.28.1",
"nanoid": "^6.0.1",
diff --git a/apps/desktop/scripts/stage-cli.mjs b/apps/desktop/scripts/stage-cli.mjs
index 90590cda..0117c593 100644
--- a/apps/desktop/scripts/stage-cli.mjs
+++ b/apps/desktop/scripts/stage-cli.mjs
@@ -4,12 +4,11 @@
// Stages the dapi CLI into apps/desktop/cli so electron-forge can ship it as
// an app resource (Contents/Resources/cli). The staged layout:
-// cli/dapi.js bundled CLI (built by apps/cli)
-// cli/node_modules deps the bundle keeps external (esbuild, babel)
-// cli/bin/dapi shell wrapper, the file that gets linked into PATH
+// cli/dapi.js bundled CLI (built by apps/cli), self-contained
+// cli/bin/dapi shell wrapper: what agents run as `dapi mcp` (registered
+// by mcp-install.ts) and the file that gets linked into PATH
-import { execFileSync } from "node:child_process";
-import { chmodSync, cpSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, cpSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
@@ -17,37 +16,11 @@ const desktopDir = join(dirname(fileURLToPath(import.meta.url)), "..");
const cliDir = join(desktopDir, "..", "cli");
const stageDir = join(desktopDir, "cli");
-// Must match the --external list in the apps/cli build script, minus ws's
-// optional native addons (bufferutil, utf-8-validate): those are external
-// only so the bundle doesn't choke on them, and ws falls back to its JS
-// implementations when they are absent.
-const EXTERNALS = ["esbuild", "@babel/core", "@babel/preset-typescript", "babel-preset-solid"];
-
-const cliPkg = JSON.parse(readFileSync(join(cliDir, "package.json"), "utf8"));
-
rmSync(stageDir, { recursive: true, force: true });
mkdirSync(join(stageDir, "bin"), { recursive: true });
cpSync(join(cliDir, "dist", "index.js"), join(stageDir, "dapi.js"));
-writeFileSync(
- join(stageDir, "package.json"),
- JSON.stringify(
- {
- name: "dapi-runtime",
- private: true,
- dependencies: Object.fromEntries(EXTERNALS.map((name) => [name, cliPkg.dependencies[name]])),
- },
- null,
- 2,
- ),
-);
-
-execFileSync("npm", ["install", "--omit=dev", "--no-audit", "--no-fund", "--no-package-lock"], {
- cwd: stageDir,
- stdio: "inherit",
-});
-
// The wrapper runs the CLI bundle on the app's own Electron binary in Node
// mode, so users need no separate Node install. It resolves symlinks first
// because both Homebrew and the in-app installer link it into PATH.
@@ -67,24 +40,4 @@ ELECTRON_RUN_AS_NODE=1 exec "$DIR/../../../MacOS/Diffusion Studio" "$DIR/../dapi
writeFileSync(join(stageDir, "bin", "dapi"), wrapper);
chmodSync(join(stageDir, "bin", "dapi"), 0o755);
-// Mach-O files inside Resources are not reached by the app-bundle signing
-// pass, and notarization rejects unsigned executables; sign them here.
-if (process.platform === "darwin" && !process.env.SKIP_SIGN) {
- const identities = execFileSync("security", ["find-identity", "-v", "-p", "codesigning"], {
- encoding: "utf8",
- });
- const identity = identities.match(/"(Developer ID Application: [^"]+)"/)?.[1];
- if (identity) {
- const esbuildDir = join(stageDir, "node_modules", "@esbuild");
- for (const pkg of readdirSync(esbuildDir)) {
- const bin = join(esbuildDir, pkg, "bin", "esbuild");
- execFileSync("codesign", ["--force", "--options", "runtime", "--timestamp", "--sign", identity, bin], {
- stdio: "inherit",
- });
- }
- } else {
- console.warn("stage-cli: no Developer ID identity found, leaving esbuild binary unsigned");
- }
-}
-
console.log(`stage-cli: staged dapi at ${stageDir}`);
diff --git a/apps/desktop/scripts/stage-docs.mjs b/apps/desktop/scripts/stage-docs.mjs
deleted file mode 100644
index 602fb4ec..00000000
--- a/apps/desktop/scripts/stage-docs.mjs
+++ /dev/null
@@ -1,26 +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/. */
-
-// Stages the authoring docs into apps/desktop/docs so electron-forge can ship
-// them as an app resource (Contents/Resources/docs). The layout mirrors the
-// repo — reference/ beside examples/ — because the relative links between the
-// pages assume it. scaffold() copies the tree into each project's
-// .diffusion/docs, so what an agent reads in a project is exactly what was
-// staged here (see src/projects.ts).
-
-import { cpSync, mkdirSync, rmSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const desktopDir = join(dirname(fileURLToPath(import.meta.url)), "..");
-const repoRoot = join(desktopDir, "..", "..");
-const stageDir = join(desktopDir, "docs");
-
-rmSync(stageDir, { recursive: true, force: true });
-mkdirSync(stageDir, { recursive: true });
-for (const name of ["reference", "examples"]) {
- cpSync(join(repoRoot, name), join(stageDir, name), { recursive: true });
-}
-
-console.log(`stage-docs: staged docs at ${stageDir}`);
diff --git a/apps/desktop/scripts/stage-knowledge.mjs b/apps/desktop/scripts/stage-knowledge.mjs
new file mode 100644
index 00000000..f7f1c7e5
--- /dev/null
+++ b/apps/desktop/scripts/stage-knowledge.mjs
@@ -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/. */
+
+// Stages the knowledge base into apps/desktop/knowledge so electron-forge
+// can ship it as an app resource (Contents/Resources/knowledge). The app's
+// MCP server serves it: INSTRUCTIONS.md on connect, everything else as
+// resources under dapi://<path>. The tree is copied as it is in the repo,
+// because the relative links between the pages assume that layout.
+
+import { cpSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const desktopDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+const repoRoot = join(desktopDir, "..", "..");
+const stageDir = join(desktopDir, "knowledge");
+
+rmSync(stageDir, { recursive: true, force: true });
+mkdirSync(stageDir, { recursive: true });
+cpSync(join(repoRoot, "knowledge"), stageDir, {
+ recursive: true,
+ filter: (path) => !path.endsWith(".DS_Store") && !path.endsWith(".gitkeep"),
+});
+
+console.log(`stage-knowledge: staged the knowledge base at ${stageDir}`);
diff --git a/apps/desktop/scripts/stage-skills.mjs b/apps/desktop/scripts/stage-skills.mjs
deleted file mode 100644
index 119d3b20..00000000
--- a/apps/desktop/scripts/stage-skills.mjs
+++ /dev/null
@@ -1,51 +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/. */
-
-// Stages the agent skills into apps/desktop/skills so electron-forge can ship
-// them as an app resource (Contents/Resources/skills). The app symlinks agent
-// skill directories at these staged copies (see src/skills-install.ts), so
-// auto-updates keep installed skills in lockstep with the dapi they document.
-//
-// Prefers a sibling checkout of diffusionstudio/skills next to the repo root
-// (the dev setup); falls back to a shallow clone (CI).
-
-import { execFileSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const SKILLS_REPO = "https://github.com/diffusionstudio/skills.git";
-
-const desktopDir = join(dirname(fileURLToPath(import.meta.url)), "..");
-const repoRoot = join(desktopDir, "..", "..");
-const stageDir = join(desktopDir, "skills");
-const sibling = join(repoRoot, "..", "skills");
-
-let sourceDir = sibling;
-let tempDir = null;
-if (!existsSync(join(sibling, "editor", "SKILL.md"))) {
- tempDir = mkdtempSync(join(tmpdir(), "stage-skills-"));
- execFileSync("git", ["clone", "--depth", "1", SKILLS_REPO, tempDir], { stdio: "inherit" });
- sourceDir = tempDir;
-}
-
-// A skill is a top-level directory with a SKILL.md.
-const skills = readdirSync(sourceDir, { withFileTypes: true })
- .filter((e) => e.isDirectory() && !e.name.startsWith("."))
- .filter((e) => existsSync(join(sourceDir, e.name, "SKILL.md")))
- .map((e) => e.name);
-
-if (skills.length === 0) {
- throw new Error(`stage-skills: no skills found in ${sourceDir}`);
-}
-
-rmSync(stageDir, { recursive: true, force: true });
-mkdirSync(stageDir, { recursive: true });
-for (const name of skills) {
- cpSync(join(sourceDir, name), join(stageDir, name), { recursive: true });
-}
-if (tempDir) rmSync(tempDir, { recursive: true, force: true });
-
-console.log(`stage-skills: staged ${skills.join(", ")} at ${stageDir}`);
diff --git a/apps/desktop/src/cli-server.ts b/apps/desktop/src/cli-server.ts
deleted file mode 100644
index c78cf301..00000000
--- a/apps/desktop/src/cli-server.ts
+++ /dev/null
@@ -1,160 +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/. */
-
-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 type { CliHandshake, CliHandshakeReply } from "@diffusionstudio/cli/protocol";
-import { mainBridge } from "./main-manager";
-import { MAIN_CHANNELS } from "./main-channels";
-
-let cliServer: Server | null = null;
-let currentWindow: BrowserWindow | null = null;
-let headless = false;
-let windowLifecycleBound = false;
-
-export function isHeadless(): boolean {
- return headless;
-}
-
-function enableHeadless(): void {
- if (headless) return;
- headless = true;
- if (currentWindow && !currentWindow.isDestroyed()) {
- mainBridge.emit(currentWindow, MAIN_CHANNELS.HEADLESS_MODE, { active: true });
- }
-}
-
-// Resolves once the current window has finished loading.
-function waitForRendererReady(timeoutMs = 30000): Promise<void> {
- if (!currentWindow || currentWindow.isDestroyed()) {
- return Promise.reject(new Error("No window"));
- }
-
- if (currentWindow.webContents.isCrashed()) {
- return Promise.reject(new Error("Renderer crashed"));
- }
- if (!currentWindow.webContents.isLoading()) {
- return Promise.resolve();
- }
-
- return new Promise((resolve, reject) => {
- const timer = setTimeout(() => {
- console.warn(`[cli-server] renderer not ready after ${timeoutMs}ms`);
- reject(new Error("App did not become ready in time"));
- }, timeoutMs);
-
- const cleanup = () => {
- clearTimeout(timer);
- currentWindow?.webContents.off("did-finish-load", onLoad);
- currentWindow?.webContents.off("did-fail-load", onFail);
- };
-
- const onLoad = () => {
- cleanup();
- resolve();
- };
-
- const onFail = () => {
- cleanup();
- reject(new Error(`Renderer failed to load`));
- };
-
- currentWindow?.webContents.on("did-finish-load", onLoad);
- currentWindow?.webContents.on("did-fail-load", onFail);
- });
-}
-
-function bindWindowLifecycle(): void {
- if (windowLifecycleBound) return;
- windowLifecycleBound = true;
- app.on("browser-window-created", (_event, window) => {
- currentWindow = window;
- window.on("closed", () => {
- if (currentWindow === window) currentWindow = null;
- });
- });
- // Catch any window that was created before the server started.
- const windows = BrowserWindow.getAllWindows();
- if (windows.length > 0) currentWindow = windows[windows.length - 1]!;
-}
-
-// Relays the CLI's connect info to the renderer, which dials the CLI's
-// WebSocket server directly. The reply confirms delivery only; from there
-// the request/response traffic bypasses main entirely.
-async function deliverHandshake(handshake: CliHandshake, sock: Socket): Promise<void> {
- let reply: CliHandshakeReply;
- try {
- await waitForRendererReady();
- if (!currentWindow || currentWindow.isDestroyed()) {
- throw new Error("No window");
- }
- currentWindow.webContents.send(CLI_WIRE.CONNECT, handshake);
- reply = { ok: true };
- } catch (err) {
- reply = { ok: false, error: (err as Error).message };
- }
- if (!sock.destroyed) sock.end(JSON.stringify(reply));
-}
-
-export function startCliServer() {
- cleanupStaleSocket();
- bindWindowLifecycle();
-
- cliServer = createServer({ allowHalfOpen: true }, (sock: Socket) => {
- enableHeadless();
- let buf = "";
- sock.setEncoding("utf8");
- sock.setTimeout(60000, () => sock.destroy());
- sock.on("data", (chunk) => {
- buf += chunk;
- });
- sock.on("end", async () => {
- sock.setTimeout(0);
- let handshake: CliHandshake;
- try {
- handshake = JSON.parse(buf) as CliHandshake;
- if (typeof handshake.port !== "number" || typeof handshake.token !== "string") {
- throw new Error("Malformed handshake");
- }
- } catch {
- sock.end(JSON.stringify({ ok: false, error: "Invalid handshake" }));
- return;
- }
- await deliverHandshake(handshake, sock);
- });
- sock.on("error", () => {
- // Client hung up; nothing to do.
- });
- });
-
- cliServer.on("error", (err) => {
- console.error("CLI server error:", err);
- });
-
- cliServer.listen(SOCKET_PATH);
-}
-
-export function stopCliServer() {
- if (!cliServer) return;
- cliServer.close();
- cliServer = null;
- cleanupStaleSocket();
-}
-
-/**
- * Clean up a stale socket file (Unix). Safe because the single-instance lock
- * guarantees no other instance of ours is running.
- */
-function cleanupStaleSocket() {
- try {
- if (process.platform !== "win32" && existsSync(SOCKET_PATH)) {
- unlinkSync(SOCKET_PATH);
- }
- } catch {
- // Best-effort.
- }
-}
diff --git a/apps/desktop/src/dapi/handler.ts b/apps/desktop/src/dapi/handler.ts
new file mode 100644
index 00000000..f94d9c72
--- /dev/null
+++ b/apps/desktop/src/dapi/handler.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 type { LogEntry, ToolArgs, ToolResult } from "@diffusionstudio/dapi";
+
+/** What a main-process handler gets besides its arguments. */
+export type MainContext = {
+ /** Fires when the caller cancels or goes away. */
+ signal: AbortSignal;
+ /** The app's console buffer, oldest first. */
+ logs(): LogEntry[];
+ /** The app's version. */
+ version: string;
+};
+
+/** The tools that need the file system or a child process, not a window. */
+export type MainToolName = "logs" | "fonts" | "fetch" | "report";
+
+export type MainHandler<N extends MainToolName> = (args: ToolArgs<N>, ctx: MainContext) => Promise<ToolResult<N>>;
+
+export type MainHandlers = { readonly [N in MainToolName]: MainHandler<N> };
diff --git a/apps/desktop/src/dapi/handlers/fetch.ts b/apps/desktop/src/dapi/handlers/fetch.ts
new file mode 100644
index 00000000..a809bf23
--- /dev/null
+++ b/apps/desktop/src/dapi/handlers/fetch.ts
@@ -0,0 +1,81 @@
+/* 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 { spawn, spawnSync } from "node:child_process";
+import { DapiError } from "@diffusionstudio/dapi";
+
+import type { MainHandler } from "../handler";
+
+// Resolve the binary once. YT_DLP_PATH is an escape hatch for pinned or
+// non-PATH installs.
+const BIN = process.env.YT_DLP_PATH ?? "yt-dlp";
+
+// Fails with an actionable message before any download is attempted. ENOENT is
+// the "not installed" case; a non-zero status means the binary is present but
+// broken.
+function assertInstalled(): void {
+ const probe = spawnSync(BIN, ["--version"], { encoding: "utf8" });
+ if (probe.error) {
+ if ((probe.error as NodeJS.ErrnoException).code === "ENOENT") {
+ throw new DapiError(
+ "unsupported",
+ "yt-dlp not found. Install it (brew install yt-dlp, or pipx install yt-dlp) or set YT_DLP_PATH to its location.",
+ );
+ }
+ throw probe.error;
+ }
+ if (probe.status !== 0) {
+ throw new DapiError("unsupported", probe.stderr?.trim() || "yt-dlp is present but not runnable.");
+ }
+}
+
+// yt-dlp's own `after_move:filepath` reports what actually landed (post
+// extraction / rename), so the name is never guessed. --quiet keeps stdout to
+// those paths; stderr is kept only for the error line when it fails.
+export const fetchVideo: MainHandler<"fetch"> = ({ url, output, format, audio, raw }, ctx) => {
+ assertInstalled();
+
+ const args = ["--quiet", "--no-warnings", "--print", "after_move:filepath"];
+ if (output) args.push("-o", output);
+ if (format) {
+ args.push("-f", format);
+ } else if (!audio) {
+ // Default to mp4: prefer mp4/m4a streams, then remux the merged result so
+ // the landed file is a .mp4 even when only WebM/mkv sources were available.
+ // An explicit format or audio opts out.
+ args.push("-f", "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/bv*+ba/b", "--merge-output-format", "mp4");
+ }
+ if (audio) args.push("-x");
+ if (raw?.length) args.push(...raw);
+ args.push(url);
+
+ return new Promise((resolve, reject) => {
+ const child = spawn(BIN, args, { stdio: ["ignore", "pipe", "pipe"] });
+ let out = "";
+ child.stdout.setEncoding("utf8");
+ child.stdout.on("data", (chunk) => (out += chunk));
+
+ let stderr = "";
+ child.stderr.setEncoding("utf8");
+ child.stderr.on("data", (chunk: string) => {
+ stderr = (stderr + chunk).slice(-4096);
+ });
+
+ const onAbort = () => child.kill();
+ ctx.signal.addEventListener("abort", onAbort, { once: true });
+
+ child.on("error", reject);
+ child.on("close", (code) => {
+ ctx.signal.removeEventListener("abort", onAbort);
+ if (ctx.signal.aborted) {
+ reject(new DapiError("canceled", "Download canceled."));
+ } else if (code === 0) {
+ resolve({ paths: out.split("\n").map((line) => line.trim()).filter(Boolean) });
+ } else {
+ const detail = stderr.trim().split("\n").filter((l) => l.startsWith("ERROR")).pop();
+ reject(new Error(detail ?? `yt-dlp exited with code ${code}.`));
+ }
+ });
+ });
+};
diff --git a/apps/cli/src/fonts.ts b/apps/desktop/src/dapi/handlers/fonts.ts
similarity index 66%
rename from apps/cli/src/fonts.ts
rename to apps/desktop/src/dapi/handlers/fonts.ts
index d2de7964..56f54b5f 100644
--- a/apps/cli/src/fonts.ts
+++ b/apps/desktop/src/dapi/handlers/fonts.ts
@@ -4,21 +4,14 @@
import { spawnSync } from "node:child_process";
import { platform } from "node:os";
+import { DapiError } from "@diffusionstudio/dapi";
-export type FontVariant = {
- weight: string;
- style: "normal" | "italic";
- source: string;
-};
-
-export type FontFamily = {
- family: string;
- variants: FontVariant[];
-};
+import type { FontFamily } from "@diffusionstudio/dapi";
+import type { MainHandler } from "../handler";
// JXA script that walks every registered font family via NSFontManager and
// emits each variant's CSS-style weight, italic flag, and CSS `local()` source.
-// Embedded inline so the CLI binary is self-contained — runs via `osascript`.
+// Runs via `osascript`.
const LIST_FONTS_JXA = `
ObjC.import("AppKit");
@@ -63,16 +56,9 @@ function run() {
}
`;
-export type ListLocalFontsOptions = {
- familyPattern?: string;
- weights?: string[];
- style?: "normal" | "italic";
- limit?: number;
-};
-
-export function listLocalFonts(options: ListLocalFontsOptions = {}): FontFamily[] {
+function listLocalFonts(): FontFamily[] {
if (platform() !== "darwin") {
- throw new Error("fonts is only supported on macOS.");
+ throw new DapiError("unsupported", "fonts is only supported on macOS.");
}
const result = spawnSync("osascript", ["-l", "JavaScript", "-e", LIST_FONTS_JXA], {
encoding: "utf8",
@@ -81,23 +67,24 @@ export function listLocalFonts(options: ListLocalFontsOptions = {}): FontFamily[
if (result.status !== 0) {
throw new Error(result.stderr.trim() || "Failed to enumerate fonts.");
}
+ return JSON.parse(result.stdout.trim()) as FontFamily[];
+}
- const all = JSON.parse(result.stdout.trim()) as FontFamily[];
- const pattern = options.familyPattern?.toLowerCase();
- const weights = options.weights && options.weights.length > 0 ? new Set(options.weights) : null;
- const { style, limit } = options;
+export const fonts: MainHandler<"fonts"> = async ({ family, weights, style, limit }) => {
+ const pattern = family?.toLowerCase();
+ const wanted = weights && weights.length > 0 ? new Set(weights) : null;
- const out: FontFamily[] = [];
- for (const family of all) {
- if (pattern && !family.family.toLowerCase().includes(pattern)) continue;
- const variants = family.variants.filter((v) => {
- if (weights && !weights.has(v.weight)) return false;
+ const families: FontFamily[] = [];
+ for (const entry of listLocalFonts()) {
+ if (pattern && !entry.family.toLowerCase().includes(pattern)) continue;
+ const variants = entry.variants.filter((v) => {
+ if (wanted && !wanted.has(v.weight)) return false;
if (style && v.style !== style) return false;
return true;
});
if (variants.length === 0) continue;
- out.push({ family: family.family, variants });
- if (limit !== undefined && out.length >= limit) break;
+ families.push({ family: entry.family, variants });
+ if (limit !== undefined && families.length >= limit) break;
}
- return out;
-}
+ return { families };
+};
diff --git a/apps/desktop/src/dapi/handlers/index.ts b/apps/desktop/src/dapi/handlers/index.ts
new file mode 100644
index 00000000..0faa91ad
--- /dev/null
+++ b/apps/desktop/src/dapi/handlers/index.ts
@@ -0,0 +1,13 @@
+/* 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 { logs } from "./logs";
+import { fonts } from "./fonts";
+import { fetchVideo } from "./fetch";
+import { report } from "./report";
+
+import type { MainHandlers } from "../handler";
+
+/** Every tool main answers itself, keyed by its catalog name. */
+export const mainHandlers: MainHandlers = { logs, fonts, fetch: fetchVideo, report };
diff --git a/apps/desktop/src/dapi/handlers/logs.ts b/apps/desktop/src/dapi/handlers/logs.ts
new file mode 100644
index 00000000..7b04e6af
--- /dev/null
+++ b/apps/desktop/src/dapi/handlers/logs.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 type { LogEntry, LogLevel } from "@diffusionstudio/dapi";
+import type { MainHandler } from "../handler";
+
+const LEVEL_RANK: Record<LogLevel, number> = { debug: 0, info: 1, warning: 2, error: 3 };
+
+export const logs: MainHandler<"logs"> = async ({ tail, level }, ctx) => {
+ let entries = ctx.logs();
+ if (level !== undefined) {
+ const min = LEVEL_RANK[level];
+ entries = entries.filter((e) => LEVEL_RANK[e.level] >= min);
+ }
+ if (tail !== undefined) entries = entries.slice(-tail);
+ return { entries };
+};
+
+/** One log entry as a line: local time, level, message, source. */
+export function formatLogEntry(entry: LogEntry): string {
+ const pad = (n: number, w = 2) => String(n).padStart(w, "0");
+ const d = new Date(entry.ts);
+ const time = `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`;
+ const source = entry.source ? ` (${entry.source})` : "";
+ return `${time} [${entry.level}] ${entry.message}${source}`;
+}
diff --git a/apps/cli/src/report.ts b/apps/desktop/src/dapi/handlers/report.ts
similarity index 58%
rename from apps/cli/src/report.ts
rename to apps/desktop/src/dapi/handlers/report.ts
index d618dec5..15876e06 100644
--- a/apps/cli/src/report.ts
+++ b/apps/desktop/src/dapi/handlers/report.ts
@@ -4,50 +4,41 @@
import { spawn } from "node:child_process";
import { arch, platform, release } from "node:os";
+import { DapiError, ISSUE_LOG_TAIL } from "@diffusionstudio/dapi";
+import { formatLogEntry } from "./logs";
+
+import type { MainHandler } from "../handler";
const REPO = "diffusionstudio/editor";
-export const GH_MISSING =
+const GH_MISSING =
"gh (GitHub CLI) is not installed, so the issue cannot be filed. Install it from https://cli.github.com, run `gh auth login`, then retry.";
-export type IssueInput = {
- title: string;
- body?: string;
- commands?: string[];
- logs?: string[]; // already formatted log lines, oldest first
- appStatus: string; // "running", "not running", "not checked", or why it was unreachable
- version: string;
-};
-
function fence(language: string, content: string): string {
return `\`\`\`${language}\n${content}\n\`\`\``;
}
-function environmentTable(input: IssueInput): string {
+function environmentTable(version: string): string {
const rows: Array<[string, string]> = [
- ["dapi", input.version],
+ ["app", version],
["platform", `${platform()} ${release()} (${arch()})`],
- ["node", process.version],
- ["app", input.appStatus],
+ ["electron", process.versions.electron ?? "unknown"],
];
return ["| | |", "| --- | --- |", ...rows.map(([k, v]) => `| ${k} | ${v} |`)].join("\n");
}
-export function buildIssueBody(input: IssueInput): string {
+function buildIssueBody(input: { body?: string; commands?: string[]; logs: string[]; version: string }): string {
const sections: string[] = [];
-
if (input.body?.trim()) sections.push(input.body.trim());
if (input.commands?.length) sections.push(`## Repro\n\n${fence("sh", input.commands.join("\n"))}`);
- sections.push(`## Environment\n\n${environmentTable(input)}`);
- if (input.logs?.length) sections.push(`## App logs\n\n${fence("", input.logs.join("\n"))}`);
-
+ sections.push(`## Environment\n\n${environmentTable(input.version)}`);
+ if (input.logs.length) sections.push(`## App logs\n\n${fence("", input.logs.join("\n"))}`);
return `${sections.join("\n\n")}\n`;
}
-// --repo is explicit because dapi runs from the user's project, not a checkout
-// of the editor; the body goes over stdin so a long log tail can't blow the
-// argv size limit.
-export function createIssue(title: string, body: string): Promise<string> {
+// --repo is explicit because the app is not a checkout of the editor; the body
+// goes over stdin so a long log tail can't blow the argv size limit.
+function createIssue(title: string, body: string): Promise<string> {
return new Promise((resolve, reject) => {
const gh = spawn("gh", ["issue", "create", "--repo", REPO, "--title", title, "--body-file", "-"]);
@@ -57,7 +48,7 @@ export function createIssue(title: string, body: string): Promise<string> {
gh.stderr.on("data", (chunk) => (stderr += chunk));
gh.on("error", (e) => {
- reject((e as NodeJS.ErrnoException).code === "ENOENT" ? new Error(GH_MISSING) : e);
+ reject((e as NodeJS.ErrnoException).code === "ENOENT" ? new DapiError("unsupported", GH_MISSING) : e);
});
gh.on("close", (code) => {
if (code !== 0) {
@@ -73,7 +64,16 @@ export function createIssue(title: string, body: string): Promise<string> {
resolve(url);
});
- gh.stdin.on("error", () => { }); // gh exiting early (auth failure) breaks the pipe
+ gh.stdin.on("error", () => {}); // gh exiting early (auth failure) breaks the pipe
gh.stdin.end(body);
});
}
+
+export const report: MainHandler<"report"> = async ({ title, body, commands, logs }, ctx) => {
+ const summary = title.trim();
+ if (!summary) throw new DapiError("invalid-input", "A one-line title is required.");
+ const tail = logs ?? ISSUE_LOG_TAIL;
+ const lines = tail > 0 ? ctx.logs().slice(-tail).map(formatLogEntry) : [];
+ const url = await createIssue(summary, buildIssueBody({ body, commands, logs: lines, version: ctx.version }));
+ return { url };
+};
diff --git a/apps/desktop/src/dapi/http.test.ts b/apps/desktop/src/dapi/http.test.ts
new file mode 100644
index 00000000..2bd6a6c8
--- /dev/null
+++ b/apps/desktop/src/dapi/http.test.ts
@@ -0,0 +1,99 @@
+/* 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 { request } from "node:http";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { z } from "zod";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DapiHttpServer } from "./http";
+
+// An ephemeral port: the fixed one may be held by a running app.
+const PORT = 3200 + Math.floor(Math.random() * 500);
+const PATH = "/mcp";
+let server: DapiHttpServer;
+let firstConnections = 0;
+let sessionsCreated = 0;
+
+beforeAll(async () => {
+ server = new DapiHttpServer({
+ host: "127.0.0.1",
+ port: PORT,
+ path: PATH,
+ onFirstConnection: () => void firstConnections++,
+ createSession() {
+ sessionsCreated++;
+ const session = new McpServer({ name: "test", version: "0.0.0" }, { instructions: "Test instructions." });
+ session.registerTool(
+ "echo",
+ { inputSchema: z.object({ text: z.string() }), outputSchema: z.object({ text: z.string() }) },
+ async ({ text }) => ({ content: [{ type: "text", text }], structuredContent: { text } }),
+ );
+ session.registerResource("note", "dapi://note", { mimeType: "text/plain" }, async () => ({
+ contents: [{ uri: "dapi://note", mimeType: "text/plain", text: "hello" }],
+ }));
+ return session;
+ },
+ });
+ await server.start();
+});
+
+afterAll(() => server.stop());
+
+async function connect(): Promise<Client> {
+ const client = new Client({ name: "test-client", version: "0.0.0" });
+ await client.connect(new StreamableHTTPClientTransport(new URL(server.url)));
+ return client;
+}
+
+describe("mcp over http", () => {
+ it("serves a session: instructions, tools, resources", async () => {
+ const client = await connect();
+ expect(client.getInstructions()).toBe("Test instructions.");
+ expect((await client.listTools()).tools.map((t) => t.name)).toEqual(["echo"]);
+ const result = await client.callTool({ name: "echo", arguments: { text: "hi" } });
+ expect(result.structuredContent).toEqual({ text: "hi" });
+ const note = await client.readResource({ uri: "dapi://note" });
+ expect(note.contents[0]).toMatchObject({ text: "hello" });
+ await client.close();
+ });
+
+ it("gives each client its own session and reports the first once", async () => {
+ const before = sessionsCreated;
+ const a = await connect();
+ const b = await connect();
+ expect(sessionsCreated - before).toBe(2);
+ expect(firstConnections).toBe(1);
+ await a.close();
+ await b.close();
+ });
+
+ it("rejects a stale session id and a non-mcp path", async () => {
+ const stale = await fetch(server.url, {
+ method: "POST",
+ headers: { "content-type": "application/json", accept: "application/json, text/event-stream", "mcp-session-id": "nope" },
+ body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" }),
+ });
+ expect(stale.status).toBe(404);
+ const elsewhere = await fetch(`http://127.0.0.1:${PORT}/other`);
+ expect(elsewhere.status).toBe(404);
+ });
+
+ it("rejects a request whose Host is not loopback (dns rebinding)", async () => {
+ // node's fetch drops a custom Host header, so go through node:http.
+ const status = await new Promise<number>((resolve, reject) => {
+ const req = request(
+ { host: "127.0.0.1", port: PORT, path: PATH, method: "POST", headers: { host: "evil.example", "content-type": "application/json", accept: "application/json, text/event-stream" } },
+ (res) => {
+ res.resume();
+ res.on("end", () => resolve(res.statusCode ?? 0));
+ },
+ );
+ req.on("error", reject);
+ req.end(JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "x", version: "0" } } }));
+ });
+ expect(status).toBe(403);
+ });
+});
diff --git a/apps/desktop/src/dapi/http.ts b/apps/desktop/src/dapi/http.ts
new file mode 100644
index 00000000..dbdb1415
--- /dev/null
+++ b/apps/desktop/src/dapi/http.ts
@@ -0,0 +1,133 @@
+/* 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/. */
+
+// MCP over Streamable HTTP on a fixed loopback port: the transport agents
+// register by URL. One MCP session per client, keyed by the session id the
+// transport hands out on `initialize`; later requests carry it in a header.
+// No token: the server binds to loopback and rejects any Host header that is
+// not the loopback address, which is what keeps browser pages from reaching
+// it. Everything else running as the user can already reach the app.
+
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export type HttpServerDeps = {
+ host: string;
+ port: number;
+ /** The URL path the endpoint answers on; anything else is 404. */
+ path: string;
+ /** A fresh MCP server with the tools and resources registered, one per session. */
+ createSession(): McpServer;
+ /** Called once, when the first session initializes. */
+ onFirstConnection(): void;
+};
+
+type Session = { transport: StreamableHTTPServerTransport; server: McpServer };
+
+const SESSION_HEADER = "mcp-session-id";
+
+export class DapiHttpServer {
+ private readonly deps: HttpServerDeps;
+ private readonly sessions = new Map<string, Session>();
+ private server: Server | null = null;
+ private connected = false;
+
+ constructor(deps: HttpServerDeps) {
+ this.deps = deps;
+ }
+
+ /** Resolves once listening; rejects when the port is taken, so the caller can say so. */
+ start(): Promise<void> {
+ return new Promise((resolve, reject) => {
+ const server = createServer((req, res) => void this.handle(req, res));
+ server.once("error", reject);
+ server.listen(this.deps.port, this.deps.host, () => {
+ server.off("error", reject);
+ server.on("error", (error) => console.error("[dapi] http server error:", error));
+ this.server = server;
+ resolve();
+ });
+ });
+ }
+
+ stop(): void {
+ for (const { transport, server } of this.sessions.values()) {
+ void transport.close();
+ void server.close();
+ }
+ this.sessions.clear();
+ this.server?.close();
+ this.server = null;
+ }
+
+ get url(): string {
+ return `http://${this.deps.host}:${this.deps.port}${this.deps.path}`;
+ }
+
+ private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+ const url = new URL(req.url ?? "/", this.url);
+ if (url.pathname !== this.deps.path) {
+ res.writeHead(404, { "content-type": "text/plain" }).end("Not found");
+ return;
+ }
+ try {
+ const id = header(req, SESSION_HEADER);
+ const existing = id === undefined ? undefined : this.sessions.get(id);
+ if (existing) {
+ await existing.transport.handleRequest(req, res);
+ return;
+ }
+ if (id !== undefined) {
+ // The transport would answer the same way; answering here keeps a
+ // stale id from allocating a server it never initializes.
+ res.writeHead(404, { "content-type": "application/json" }).end(
+ JSON.stringify({ jsonrpc: "2.0", error: { code: -32001, message: "Session not found" }, id: null }),
+ );
+ return;
+ }
+ // No session: either an `initialize`, which the transport answers with
+ // a new id, or a stray request it rejects with 400.
+ await this.open().transport.handleRequest(req, res);
+ } catch (error) {
+ console.error("[dapi] http request failed:", error);
+ if (!res.headersSent) res.writeHead(500, { "content-type": "text/plain" }).end("Internal error");
+ }
+ }
+
+ private open(): Session {
+ const server = this.deps.createSession();
+ const hosts = [this.deps.host, "localhost"];
+ const transport = new StreamableHTTPServerTransport({
+ sessionIdGenerator: () => randomUUID(),
+ enableDnsRebindingProtection: true,
+ allowedHosts: [...hosts, ...hosts.map((host) => `${host}:${this.deps.port}`)],
+ onsessioninitialized: (id) => {
+ this.sessions.set(id, session);
+ if (!this.connected) {
+ this.connected = true;
+ this.deps.onFirstConnection();
+ }
+ },
+ onsessionclosed: (id) => {
+ this.sessions.delete(id);
+ },
+ });
+ const session: Session = { transport, server };
+ transport.onclose = () => {
+ if (transport.sessionId !== undefined) this.sessions.delete(transport.sessionId);
+ };
+ // connect() starts the transport; it does not block on I/O.
+ void server.connect(transport);
+ return session;
+ }
+}
+
+function header(req: IncomingMessage, name: string): string | undefined {
+ const value = req.headers[name];
+ return Array.isArray(value) ? value[0] : value;
+}
diff --git a/apps/desktop/src/dapi/knowledge.test.ts b/apps/desktop/src/dapi/knowledge.test.ts
new file mode 100644
index 00000000..6a4a0b67
--- /dev/null
+++ b/apps/desktop/src/dapi/knowledge.test.ts
@@ -0,0 +1,170 @@
+/* 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 { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { instructions, registerPrompts, registerResources, SKILLS } from "./knowledge";
+
+import type { KnowledgeDeps } from "./knowledge";
+
+// A knowledge base in miniature, laid out like the repo's `knowledge/`.
+const root = mkdtempSync(join(tmpdir(), "dapi-knowledge-"));
+const knowledgeDir = join(root, "knowledge");
+const projectDir = join(root, "project");
+
+beforeAll(() => {
+ mkdirSync(join(knowledgeDir, "reference", "jsx"), { recursive: true });
+ mkdirSync(join(knowledgeDir, "examples", "node_modules"), { recursive: true });
+ mkdirSync(join(knowledgeDir, "skills"), { recursive: true });
+ mkdirSync(join(knowledgeDir, "brand", "assets", "logos"), { recursive: true });
+ writeFileSync(join(knowledgeDir, "INSTRUCTIONS.md"), "Diffusion Studio is running.\n");
+ writeFileSync(join(knowledgeDir, "reference", "jsx", "text.md"), "# text\n\nThe `<text>` element draws a run of text. It wraps at `width`.\n\n## Props\n");
+ writeFileSync(join(knowledgeDir, "reference", "README.md"), "---\ntitle: x\n---\n# Reference\n\n| a | b |\n\nEvery page, one per tool.\n");
+ writeFileSync(join(knowledgeDir, "skills", "editor.md"), "# Editing\n\nHow to edit.\n");
+ writeFileSync(join(knowledgeDir, "skills", "watch.md"), "# Watching\n\nHow to watch.\n");
+ writeFileSync(join(knowledgeDir, "examples", "01-hello.tsx"), "export default <scene />;\n");
+ writeFileSync(join(knowledgeDir, "examples", "tsconfig.json"), "{}\n");
+ writeFileSync(join(knowledgeDir, "examples", "node_modules", "ignored.md"), "no\n");
+ writeFileSync(join(knowledgeDir, "brand", "assets", "logos", "icon.svg"), "<svg/>\n");
+ writeFileSync(join(knowledgeDir, ".DS_Store"), "");
+ mkdirSync(projectDir);
+});
+
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+const deps = (projectOpen: boolean, dir: string | null = knowledgeDir): KnowledgeDeps => ({
+ knowledgeDir: dir,
+ logs: () => [{ ts: 1, level: "info", message: "hi", source: "" }],
+ context: async () => ({ rootDir: root, projectDir: projectOpen ? projectDir : null, currentTime: null, fontFamilies: [], generations: [] }),
+});
+
+async function connect(d: KnowledgeDeps): Promise<Client> {
+ const server = new McpServer({ name: "test", version: "0" }, { instructions: instructions(d) });
+ registerResources(server, d);
+ registerPrompts(server, d);
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ const client = new Client({ name: "test-client", version: "0" });
+ await client.connect(clientTransport);
+ return client;
+}
+
+describe("instructions", () => {
+ it("is INSTRUCTIONS.md followed by where the tree sits on disk", () => {
+ const text = instructions(deps(true));
+ expect(text.startsWith("Diffusion Studio is running.")).toBe(true);
+ expect(text).toContain(knowledgeDir);
+ });
+
+ it("lists the skills, marking the default, with both ways to pull one in", () => {
+ const text = instructions(deps(true));
+ expect(text).toContain("`editor` (the default) —");
+ expect(text).toContain("Pull it in with the `editor` prompt, or read `dapi://skills/editor.md`.");
+ expect(text).toContain("`watch` —");
+ expect(text).not.toContain("`watch` (the default)");
+ });
+
+ it("falls back to a one-liner when nothing is staged", () => {
+ const text = instructions(deps(true, null));
+ expect(text).toContain("The tools are the whole API");
+ expect(text).not.toContain("dapi://skills");
+ });
+});
+
+describe("resources", () => {
+ it("lists every page under dapi://<path>, docs and svg only, no node_modules or dotfiles", async () => {
+ const client = await connect(deps(true));
+ const uris = (await client.listResources()).resources.map((r) => r.uri).sort();
+ expect(uris).toEqual([
+ "dapi://brand/assets/logos/icon.svg",
+ "dapi://context",
+ "dapi://examples/01-hello.tsx",
+ "dapi://logs",
+ "dapi://reference/README.md",
+ "dapi://reference/jsx/text.md",
+ "dapi://skills/editor.md",
+ "dapi://skills/watch.md",
+ ]);
+ await client.close();
+ });
+
+ it("describes markdown pages by their first paragraph, skipping headings, frontmatter and tables", async () => {
+ const client = await connect(deps(true));
+ const byUri = new Map((await client.listResources()).resources.map((r) => [r.uri, r]));
+ expect(byUri.get("dapi://reference/jsx/text.md")?.description).toBe("The `<text>` element draws a run of text. It wraps at `width`.");
+ expect(byUri.get("dapi://reference/README.md")?.description).toBe("Every page, one per tool.");
+ expect(byUri.get("dapi://examples/01-hello.tsx")?.description).toBeUndefined();
+ await client.close();
+ });
+
+ it("reads a page, an svg, and the live state", async () => {
+ const client = await connect(deps(true));
+ expect((await client.readResource({ uri: "dapi://reference/jsx/text.md" })).contents[0]).toMatchObject({ mimeType: "text/markdown" });
+ expect((await client.readResource({ uri: "dapi://brand/assets/logos/icon.svg" })).contents[0]).toMatchObject({ mimeType: "image/svg+xml", text: "<svg/>\n" });
+ const context = await client.readResource({ uri: "dapi://context" });
+ expect(JSON.parse((context.contents[0] as { text: string }).text).projectDir).toBe(projectDir);
+ const logs = await client.readResource({ uri: "dapi://logs" });
+ expect(JSON.parse((logs.contents[0] as { text: string }).text).entries).toHaveLength(1);
+ await client.close();
+ });
+
+ it("serves the repo's own knowledge base without broken instructions", () => {
+ const repoKnowledge = join(__dirname, "..", "..", "..", "..", "knowledge");
+ if (!existsSync(repoKnowledge)) return;
+ const text = instructions(deps(true, repoKnowledge));
+ expect(text).toContain("dapi://skills/editor.md");
+ expect(text).not.toContain("\\`");
+ });
+});
+
+describe("prompts", () => {
+ it("offers one prompt per skill, described the way the instructions describe it", async () => {
+ const client = await connect(deps(true));
+ const prompts = (await client.listPrompts()).prompts;
+ expect(prompts.map((p) => p.name).sort()).toEqual(["editor", "watch"]);
+ for (const skill of SKILLS) {
+ expect(prompts.find((p) => p.name === skill.name)?.description).toBe(skill.description);
+ }
+ await client.close();
+ });
+
+ it("returns the page as the prompt, with the coda that says what to do with it", async () => {
+ const client = await connect(deps(true));
+ const result = await client.getPrompt({ name: "editor" });
+ expect(result.messages).toHaveLength(1);
+ expect(result.messages[0].role).toBe("user");
+ const text = (result.messages[0].content as { text: string }).text;
+ expect(text.startsWith("# Editing")).toBe(true);
+ expect(text).toContain("ask them what they want to make");
+ await client.close();
+ });
+
+ it("has no prompts when nothing is staged", async () => {
+ const client = await connect(deps(true, null));
+ await expect(client.listPrompts()).rejects.toThrow();
+ await client.close();
+ });
+
+ it("skips a skill whose page the staged tree does not carry", async () => {
+ const bare = join(root, "bare");
+ mkdirSync(join(bare, "skills"), { recursive: true });
+ writeFileSync(join(bare, "skills", "editor.md"), "# Editing\n");
+ const client = await connect(deps(true, bare));
+ expect((await client.listPrompts()).prompts.map((p) => p.name)).toEqual(["editor"]);
+ await client.close();
+ });
+
+ it("has a page in the repo's own knowledge base for every skill in the table", () => {
+ const repoKnowledge = join(__dirname, "..", "..", "..", "..", "knowledge");
+ if (!existsSync(repoKnowledge)) return;
+ expect(SKILLS.map((s) => s.name)).toEqual(["editor", "watch"]);
+ expect(SKILLS.filter((s) => s.default)).toHaveLength(1);
+ for (const skill of SKILLS) expect(existsSync(join(repoKnowledge, skill.page))).toBe(true);
+ });
+});
diff --git a/apps/desktop/src/dapi/knowledge.ts b/apps/desktop/src/dapi/knowledge.ts
new file mode 100644
index 00000000..b7ff9aa8
--- /dev/null
+++ b/apps/desktop/src/dapi/knowledge.ts
@@ -0,0 +1,207 @@
+/* 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 { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LogEntry, ToolOutput } from "@diffusionstudio/dapi";
+
+export type KnowledgeDeps = {
+ /** The staged `knowledge/` tree. Null when not staged. */
+ knowledgeDir: string | null;
+ logs(): LogEntry[];
+ context(signal: AbortSignal): Promise<ToolOutput<"context">>;
+};
+
+export const INSTRUCTIONS_FILE = "INSTRUCTIONS.md";
+
+const RESOURCE_PREFIX = "dapi://";
+
+export type Skill = {
+ name: string;
+ /** The page carrying the guidance, relative to the knowledge base. */
+ page: string;
+ description: string;
+ /** The skill to reach for when the user has not pointed at one. Exactly one. */
+ default?: boolean;
+};
+
+/**
+ * What the server offers besides the tools. Each entry is both a line in the
+ * instructions every session receives and a prompt (`/diffusion:editor`), so
+ * adding a skill is adding a row here and its page under `knowledge/skills/`.
+ * Editing is the default; watching is the one you ask for.
+ */
+export const SKILLS: readonly Skill[] = [
+ {
+ name: "editor",
+ page: "skills/editor.md",
+ default: true,
+ description:
+ "Understand, generate, and edit footage with Diffusion Studio: analyze video/audio/images, generate them with AI, and compose video compositions. Use for any media analysis, media generation, or video editing task.",
+ },
+ {
+ name: "watch",
+ page: "skills/watch.md",
+ description:
+ "Watch and understand footage with Diffusion Studio: answer questions about a video or audio file, summarize it, find scenes and moments, pull quotes, and describe what happens and when. Use whenever the user asks what's in a piece of footage, wants a summary or recap, wants to locate a moment, or needs a claim about a video or audio file checked.",
+ },
+];
+
+const MIME_TYPES: Record<string, string> = {
+ ".md": "text/markdown",
+ ".ts": "text/plain",
+ ".tsx": "text/plain",
+ ".svg": "image/svg+xml",
+};
+
+const FALLBACK_INSTRUCTIONS =
+ "Diffusion Studio, a video editor, is running on this machine and you are connected to it. The tools are the whole API; their descriptions are authoritative.";
+
+/**
+ * The text every client gets on connect: INSTRUCTIONS.md from the knowledge
+ * base, plus where that tree sits on disk, since resources carry text and the
+ * brand kit has logos, fonts and components meant to be copied.
+ */
+export function instructions(deps: KnowledgeDeps): string {
+ const text = deps.knowledgeDir ? readText(join(deps.knowledgeDir, INSTRUCTIONS_FILE)) : null;
+ const parts = [text?.trim() || FALLBACK_INSTRUCTIONS];
+ if (deps.knowledgeDir) {
+ parts.push(skillList());
+ parts.push(
+ `The resources under \`dapi://\` are the files at \`${deps.knowledgeDir}\`, for anything a resource cannot carry (fonts, imagery, components to copy). They belong to the app; read them, never edit them.`,
+ );
+ }
+ return parts.join("\n\n");
+}
+
+export function registerResources(session: McpServer, deps: KnowledgeDeps): void {
+ for (const file of pages(deps)) {
+ session.registerResource(file.name, file.uri, { title: file.name, description: file.description, mimeType: file.mimeType }, async () => ({
+ contents: [{ uri: file.uri, mimeType: file.mimeType, text: await readFile(file.path, "utf8") }],
+ }));
+ }
+
+ session.registerResource(
+ "context",
+ "dapi://context",
+ { title: "App context", description: "The open project, the playhead, registered fonts, and where generations stand.", mimeType: "application/json" },
+ async (uri, extra) => ({
+ contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(await deps.context(extra.signal)) }],
+ }),
+ );
+
+ session.registerResource(
+ "logs",
+ "dapi://logs",
+ { title: "App logs", description: "The app's console output, oldest first.", mimeType: "application/json" },
+ async (uri) => ({
+ contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify({ entries: deps.logs() }) }],
+ }),
+ );
+}
+
+/**
+ * The skills as the instructions present them: what each is for, which to
+ * reach for by default, and both ways to pull one in — the prompt, for agents
+ * that list them, and the resource, for the ones that do not.
+ */
+function skillList(): string {
+ const lines = SKILLS.map(
+ (skill) =>
+ `- \`${skill.name}\`${skill.default ? " (the default)" : ""} — ${skill.description} Pull it in with the \`${skill.name}\` prompt, or read \`${RESOURCE_PREFIX}${skill.page}\`.`,
+ );
+ return ["Before starting on the work itself, pull in the skill that covers it:", ...lines].join("\n");
+}
+
+/**
+ * One prompt per skill, named as the table names it, so an agent that lists a
+ * server's prompts offers `/diffusion:editor` and `/diffusion:watch` beside
+ * its own commands. The page is read at call time, like a resource.
+ */
+export function registerPrompts(session: McpServer, deps: KnowledgeDeps): void {
+ const dir = deps.knowledgeDir;
+ if (!dir) return;
+ for (const skill of SKILLS) {
+ const path = join(dir, ...skill.page.split("/"));
+ if (!existsSync(path)) continue; // a page the staged tree does not carry
+ session.registerPrompt(skill.name, { title: skill.name, description: skill.description }, async () => ({
+ messages: [{ role: "user", content: { type: "text", text: `${await readFile(path, "utf8")}\n${PROMPT_CODA}` } }],
+ }));
+ }
+}
+
+// A prompt arrives as a user turn, so the page needs a closing line saying
+// what to do with guidance that turned up without a request attached to it.
+const PROMPT_CODA =
+ "\nThe guidance above is in effect for the rest of this conversation. Apply it to what the user asked for; if they have not asked for anything yet, ask them what they want to make.";
+
+type Page = { name: string; uri: string; path: string; mimeType: string; description?: string };
+
+// The listing is the same for every session; walk the staged tree once.
+let cache: { dir: string; pages: Page[] } | null = null;
+
+function pages(deps: KnowledgeDeps): Page[] {
+ if (!deps.knowledgeDir) return [];
+ if (cache?.dir === deps.knowledgeDir) return cache.pages;
+ const found: Page[] = [];
+ collect(deps.knowledgeDir, deps.knowledgeDir, found);
+ cache = { dir: deps.knowledgeDir, pages: found };
+ return found;
+}
+
+function collect(root: string, dir: string, out: Page[]): void {
+ let entries: string[];
+ try {
+ entries = readdirSync(dir);
+ } catch {
+ return;
+ }
+ for (const entry of entries.sort()) {
+ if (entry.startsWith(".") || entry === "node_modules") continue;
+ const path = join(dir, entry);
+ let isDirectory: boolean;
+ try {
+ isDirectory = statSync(path).isDirectory();
+ } catch {
+ continue;
+ }
+ if (isDirectory) {
+ collect(root, path, out);
+ continue;
+ }
+ const mimeType = MIME_TYPES[entry.slice(entry.lastIndexOf("."))];
+ if (!mimeType) continue;
+ const name = relative(root, path).split(sep).join("/");
+ if (name === INSTRUCTIONS_FILE) continue; // already in every session's instructions
+ out.push({ name, uri: `${RESOURCE_PREFIX}${name}`, path, mimeType, description: mimeType === "text/markdown" ? summary(path) : undefined });
+ }
+}
+
+/**
+ * A page's first paragraph after its heading, so `resources/list` reads as a
+ * table of contents without opening anything.
+ */
+function summary(path: string): string | undefined {
+ const text = readText(path);
+ if (!text) return undefined;
+ const body = text.replace(/^---\n[\s\S]*?\n---\n/, "");
+ const paragraph = body
+ .split(/\n\s*\n/)
+ .map((block) => block.trim())
+ .find((block) => block && !block.startsWith("#") && !block.startsWith("```") && !block.startsWith("|") && !block.startsWith("<"));
+ if (!paragraph) return undefined;
+ const line = paragraph.replace(/\s+/g, " ");
+ return line.length > 200 ? `${line.slice(0, 197).trimEnd()}…` : line;
+}
+
+function readText(path: string): string | null {
+ try {
+ return readFileSync(path, "utf8");
+ } catch {
+ return null;
+ }
+}
diff --git a/apps/desktop/src/dapi/present.test.ts b/apps/desktop/src/dapi/present.test.ts
new file mode 100644
index 00000000..5f5115c8
--- /dev/null
+++ b/apps/desktop/src/dapi/present.test.ts
@@ -0,0 +1,68 @@
+/* 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 { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { present, toCallToolResult } from "./present";
+
+const dir = mkdtempSync(join(tmpdir(), "dapi-present-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+const png = (byte: number, size = 8) => new Uint8Array(size).fill(byte);
+
+describe("present", () => {
+ it("writes capture frames by timecode into the requested directory and returns their paths", async () => {
+ const out = join(dir, "frames");
+ const presented = await present("capture", { id: "intro", output: out }, [
+ { timecode: "0f", png: png(1) },
+ { timecode: "1s", png: png(2) },
+ ]);
+ expect(presented.output).toEqual({ images: [{ timecode: "0f", path: join(out, "0f.png") }, { timecode: "1s", path: join(out, "1s.png") }] });
+ expect(readFileSync(join(out, "1s.png"))).toEqual(Buffer.from(png(2)));
+ });
+
+ it("picks a fresh temp directory when none is given", async () => {
+ const presented = await present("media_grab", { path: "/c.mp4" }, [{ timecode: "0f", png: png(3) }]);
+ const { path } = (presented.output as { images: Array<{ path: string }> }).images[0]!;
+ expect(path).toMatch(/dapi-grab-.*[\\/]0f\.png$/);
+ rmSync(join(path, ".."), { recursive: true, force: true });
+ });
+
+ it("keeps a preview's other fields next to the path", async () => {
+ const file = join(dir, "wave.png");
+ const presented = await present("media_waveform", { path: "/c.mp4", output: file }, { png: png(4), silences: [{ start: 0, end: 1 }] });
+ expect(presented.output).toEqual({ path: file, silences: [{ start: 0, end: 1 }] });
+ });
+
+ it("names screenshots by time and never overwrites one", async () => {
+ const first = await present("screenshot", { output: dir }, { png: png(5), width: 10, height: 10 });
+ const second = await present("screenshot", { output: dir }, { png: png(6), width: 10, height: 10 });
+ const a = (first.output as { path: string }).path;
+ const b = (second.output as { path: string }).path;
+ expect(a).toMatch(/diffusion-studio_\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}\.png$/);
+ expect(b).not.toBe(a);
+ });
+
+ it("passes other results through untouched", async () => {
+ expect(await present("check", { id: "x" }, { stats: {}, issues: [] })).toEqual({ output: { stats: {}, issues: [] }, images: [] });
+ });
+});
+
+describe("toCallToolResult", () => {
+ it("inlines a few small images and always carries the output as text and structure", () => {
+ const result = toCallToolResult({ output: { images: [] }, images: [{ path: "/a.png", png: png(1) }] });
+ expect(result.structuredContent).toEqual({ images: [] });
+ expect(result.content[0]).toEqual({ type: "text", text: '{"images":[]}' });
+ expect(result.content[1]).toMatchObject({ type: "image", mimeType: "image/png" });
+ });
+
+ it("sends paths only when there are many images or a large one", () => {
+ const many = Array.from({ length: 5 }, (_, i) => ({ path: `/${i}.png`, png: png(i) }));
+ expect(toCallToolResult({ output: {}, images: many }).content).toHaveLength(1);
+ const large = [{ path: "/big.png", png: png(0, (1 << 20) + 1) }];
+ expect(toCallToolResult({ output: {}, images: large }).content).toHaveLength(1);
+ });
+});
diff --git a/apps/desktop/src/dapi/present.ts b/apps/desktop/src/dapi/present.ts
new file mode 100644
index 00000000..67d90d1f
--- /dev/null
+++ b/apps/desktop/src/dapi/present.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/. */
+
+// Turns what a handler returned into what a caller receives. Tools that
+// render images hand back bytes; here they become files on disk, paths in
+// the structured result, and — when the result is small — inline images the
+// agent sees without opening anything.
+
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { TimecodedImage, ToolArgs, ToolName, ToolOutput, ToolResult } from "@diffusionstudio/dapi";
+
+/** A file the tool wrote, kept in memory only long enough to decide whether to inline it. */
+export type WrittenImage = { path: string; png: Uint8Array };
+
+export type Presented = { output: unknown; images: WrittenImage[] };
+
+/** More than this, or any image larger than INLINE_MAX_BYTES, and the caller gets paths only. */
+const INLINE_MAX_IMAGES = 4;
+const INLINE_MAX_BYTES = 1 << 20;
+
+const APP_SLUG = "diffusion-studio";
+
+export async function present(name: ToolName, args: unknown, result: unknown): Promise<Presented> {
+ switch (name) {
+ case "capture":
+ return presentImages(result as ToolResult<"capture">, (args as ToolArgs<"capture">).output, "capture");
+ case "media_grab":
+ return presentImages(result as ToolResult<"media_grab">, (args as ToolArgs<"media_grab">).output, "grab");
+ case "media_filmstrip":
+ return presentPreview(result as ToolResult<"media_filmstrip">, (args as ToolArgs<"media_filmstrip">).output, "filmstrip");
+ case "media_waveform":
+ return presentPreview(result as ToolResult<"media_waveform">, (args as ToolArgs<"media_waveform">).output, "waveform");
+ case "screenshot":
+ return presentScreenshot(result as ToolResult<"screenshot">, (args as ToolArgs<"screenshot">).output);
+ default:
+ return { output: result, images: [] };
+ }
+}
+
+// Frames and contact sheets arrive in the same shape: each image is stamped
+// with its timecode (`08s10f`, or `0f-08s10f` for a sheet), which is the
+// filename too.
+async function presentImages(images: TimecodedImage[], output: string | undefined, kind: string): Promise<Presented> {
+ const dir = output ?? (await mkdtemp(join(tmpdir(), `dapi-${kind}-`)));
+ await mkdir(dir, { recursive: true });
+ const written: WrittenImage[] = [];
+ const refs: ToolOutput<"capture">["images"] = [];
+ for (const { timecode, png } of images) {
+ const path = join(dir, `${timecode}.png`);
+ await writeFile(path, png);
+ written.push({ path, png });
+ refs.push({ timecode, path });
+ }
+ return { output: { images: refs }, images: written };
+}
+
+async function presentPreview(
+ result: { png: Uint8Array } & Record<string, unknown>,
+ output: string | undefined,
+ kind: string,
+): Promise<Presented> {
+ const { png, ...rest } = result;
+ const path = output ?? join(tmpdir(), `dapi-${kind}-${randomUUID()}.png`);
+ await mkdir(dirname(path), { recursive: true });
+ await writeFile(path, png);
+ return { output: { path, ...rest }, images: [{ path, png }] };
+}
+
+async function presentScreenshot(result: ToolResult<"screenshot">, output: string | undefined): Promise<Presented> {
+ const dir = output ?? tmpdir();
+ await mkdir(dir, { recursive: true });
+ const taken = new Date();
+ let attempt = 1;
+ let path = join(dir, screenshotFilename(taken, attempt));
+ while (existsSync(path)) path = join(dir, screenshotFilename(taken, ++attempt));
+ await writeFile(path, result.png);
+ const presented: ToolOutput<"screenshot"> = { path, width: result.width, height: result.height };
+ return { output: presented, images: [{ path, png: result.png }] };
+}
+
+function screenshotFilename(taken: Date, attempt: number): string {
+ const pad = (value: number) => String(value).padStart(2, "0");
+ const date = [taken.getFullYear(), pad(taken.getMonth() + 1), pad(taken.getDate())].join("-");
+ const time = [pad(taken.getHours()), pad(taken.getMinutes()), pad(taken.getSeconds())].join("-");
+ return `${APP_SLUG}_${date}_${time}${attempt > 1 ? `-${attempt}` : ""}.png`;
+}
+
+/** The MCP result: the output as text and structured content, plus the images when they are few and small. */
+export function toCallToolResult({ output, images }: Presented): CallToolResult {
+ const content: CallToolResult["content"] = [{ type: "text", text: JSON.stringify(output) }];
+ const inline = images.length <= INLINE_MAX_IMAGES && images.every((image) => image.png.byteLength <= INLINE_MAX_BYTES);
+ if (inline) {
+ for (const { png } of images) {
+ content.push({ type: "image", data: Buffer.from(png).toString("base64"), mimeType: "image/png" });
+ }
+ }
+ return { content, structuredContent: output as Record<string, unknown> };
+}
+
+/** A failure the agent reads as a sentence, not a protocol error. */
+export function toErrorResult(error: unknown): CallToolResult {
+ return { isError: true, content: [{ type: "text", text: (error as Error).message }] };
+}
diff --git a/apps/desktop/src/dapi/renderer-calls.ts b/apps/desktop/src/dapi/renderer-calls.ts
new file mode 100644
index 00000000..e5be4f51
--- /dev/null
+++ b/apps/desktop/src/dapi/renderer-calls.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 { randomUUID } from "node:crypto";
+import { app, BrowserWindow, ipcMain } from "electron";
+import { DAPI_WIRE, DapiError } from "@diffusionstudio/dapi";
+
+import type { DapiCall, DapiCancel, DapiReply } from "@diffusionstudio/dapi";
+
+type InFlight = {
+ resolve(data: unknown): void;
+ reject(error: Error): void;
+};
+
+/**
+ * Runs renderer tools from main: one `dapi:call` per request, answered by
+ * `dapi:reply`, or `dapi:cancel` if the caller gives up. Calls wait for the
+ * current window to finish loading; a window that reloads or dies fails the
+ * calls it was answering.
+ */
+export class RendererCalls {
+ private readonly inFlight = new Map<string, InFlight>();
+ private window: BrowserWindow | null = null;
+
+ start(): void {
+ ipcMain.on(DAPI_WIRE.REPLY, (_event, reply: DapiReply) => {
+ const call = this.inFlight.get(reply.id);
+ if (!call) return;
+ this.inFlight.delete(reply.id);
+ if (reply.ok) call.resolve(reply.data);
+ else call.reject(reply.error.code ? new DapiError(reply.error.code, reply.error.message) : new Error(reply.error.message));
+ });
+
+ app.on("browser-window-created", (_event, window) => this.track(window));
+ const windows = BrowserWindow.getAllWindows();
+ if (windows.length > 0) this.track(windows[windows.length - 1]!);
+ }
+
+ async call(tool: string, args: unknown, signal: AbortSignal): Promise<unknown> {
+ const window = await this.ready();
+ const id = randomUUID();
+ return new Promise((resolve, reject) => {
+ const onAbort = () => {
+ this.inFlight.delete(id);
+ if (!window.isDestroyed()) window.webContents.send(DAPI_WIRE.CANCEL, { id } satisfies DapiCancel);
+ reject(new DapiError("canceled", "The call was canceled."));
+ };
+ signal.addEventListener("abort", onAbort, { once: true });
+ this.inFlight.set(id, {
+ resolve: (data) => {
+ signal.removeEventListener("abort", onAbort);
+ resolve(data);
+ },
+ reject: (error) => {
+ signal.removeEventListener("abort", onAbort);
+ reject(error);
+ },
+ });
+ window.webContents.send(DAPI_WIRE.CALL, { id, tool, args } satisfies DapiCall);
+ });
+ }
+
+ private track(window: BrowserWindow): void {
+ this.window = window;
+ const fail = (why: string) => () => this.failAll(why);
+ window.webContents.on("did-start-loading", fail("The app reloaded before replying"));
+ window.webContents.on("render-process-gone", fail("The app's renderer crashed"));
+ window.on("closed", () => {
+ if (this.window === window) this.window = null;
+ this.failAll("The app window closed before replying");
+ });
+ }
+
+ private failAll(message: string): void {
+ const calls = [...this.inFlight.values()];
+ this.inFlight.clear();
+ for (const call of calls) call.reject(new Error(message));
+ }
+
+ // Resolves with the current window once it has finished loading.
+ private ready(timeoutMs = 30000): Promise<BrowserWindow> {
+ const window = this.window;
+ if (!window || window.isDestroyed()) return Promise.reject(new Error("The app has no window"));
+ if (window.webContents.isCrashed()) return Promise.reject(new Error("The app's renderer crashed"));
+ if (!window.webContents.isLoading()) return Promise.resolve(window);
+
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => {
+ cleanup();
+ reject(new Error("The app did not become ready in time"));
+ }, timeoutMs);
+ const cleanup = () => {
+ clearTimeout(timer);
+ window.webContents.off("did-finish-load", onLoad);
+ window.webContents.off("did-fail-load", onFail);
+ };
+ const onLoad = () => {
+ cleanup();
+ resolve(window);
+ };
+ const onFail = () => {
+ cleanup();
+ reject(new Error("The app failed to load"));
+ };
+ window.webContents.on("did-finish-load", onLoad);
+ window.webContents.on("did-fail-load", onFail);
+ });
+ }
+}
diff --git a/apps/desktop/src/dapi/server.ts b/apps/desktop/src/dapi/server.ts
new file mode 100644
index 00000000..99b3357d
--- /dev/null
+++ b/apps/desktop/src/dapi/server.ts
@@ -0,0 +1,165 @@
+/* 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 { chmodSync, existsSync, unlinkSync } from "node:fs";
+import { createServer } from "node:net";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { tools } from "@diffusionstudio/dapi";
+import { MCP_HOST, MCP_PATH, MCP_PORT, SOCKET_PATH, SocketTransport } from "@diffusionstudio/dapi/socket";
+import { mainHandlers } from "./handlers";
+import { DapiHttpServer } from "./http";
+import { instructions, registerPrompts, registerResources } from "./knowledge";
+import { SERVER_NAME } from "../mcp-config";
+import { present, toCallToolResult, toErrorResult } from "./present";
+import { RendererCalls } from "./renderer-calls";
+
+import type { Server, Socket } from "node:net";
+import type { GenericTool, LogEntry, ToolName, ToolOutput } from "@diffusionstudio/dapi";
+import type { MainContext, MainToolName } from "./handler";
+
+export type DapiServerDeps = {
+ version: string;
+ /** The app's console buffer, for `logs` and `report`. */
+ logs(): LogEntry[];
+ /** Called once, on the first connection: an agent is driving, so the UI may step back. */
+ onFirstConnection(): void;
+ /** The staged knowledge base: INSTRUCTIONS.md for every session, the rest as resources. Null when not staged. */
+ knowledgeDir: string | null;
+};
+
+/**
+ * The app's MCP server, on two transports over one catalog: Streamable HTTP
+ * on a fixed loopback port, which agents register by URL, and the local
+ * socket the `dapi` CLI uses (and `dapi mcp` proxies for agents that only
+ * speak stdio). Each connection gets its own MCP session. Main-process tools
+ * run here; renderer tools are forwarded over IPC and their results
+ * presented (files written, small images inlined) before they go back out.
+ */
+export class DapiServer {
+ private readonly deps: DapiServerDeps;
+ private readonly renderer = new RendererCalls();
+ private readonly sessions = new Set<McpServer>();
+ private readonly http: DapiHttpServer;
+ private server: Server | null = null;
+ private connected = false;
+ private instructionsText: string | null = null;
+
+ constructor(deps: DapiServerDeps) {
+ this.deps = deps;
+ for (const tool of tools) {
+ if (tool.environment === "main" && !(tool.name in mainHandlers)) {
+ throw new Error(`Main-process tool "${tool.name}" has no handler`);
+ }
+ }
+ this.http = new DapiHttpServer({
+ host: MCP_HOST,
+ port: MCP_PORT,
+ path: MCP_PATH,
+ createSession: () => this.createSession(),
+ onFirstConnection: () => this.firstConnection(),
+ });
+ }
+
+ /** The URL agents register. */
+ get url(): string {
+ return this.http.url;
+ }
+
+ start(): void {
+ removeStaleSocket();
+ this.renderer.start();
+ this.server = createServer((socket) => void this.accept(socket));
+ this.server.on("error", (error) => console.error("[dapi] server error:", error));
+ this.server.listen(SOCKET_PATH, () => {
+ // Linux shares /tmp between users; the socket file's mode is the auth.
+ if (process.platform !== "win32") chmodSync(SOCKET_PATH, 0o600);
+ });
+ // A taken port is the one way this fails; the socket keeps the CLI and
+ // `dapi mcp` working meanwhile, so it is logged, not fatal.
+ this.http.start().catch((error: Error) => console.error(`[dapi] cannot serve MCP at ${this.url}: ${error.message}`));
+ }
+
+ stop(): void {
+ this.http.stop();
+ for (const session of this.sessions) void session.close();
+ this.sessions.clear();
+ this.server?.close();
+ this.server = null;
+ removeStaleSocket();
+ }
+
+ private firstConnection(): void {
+ if (this.connected) return;
+ this.connected = true;
+ this.deps.onFirstConnection();
+ }
+
+ private async accept(socket: Socket): Promise<void> {
+ this.firstConnection();
+ const session = this.createSession();
+ this.sessions.add(session);
+ session.server.onclose = () => this.sessions.delete(session);
+ try {
+ await session.connect(new SocketTransport(socket));
+ } catch (error) {
+ console.error("[dapi] session failed to start:", error);
+ this.sessions.delete(session);
+ socket.destroy();
+ }
+ }
+
+ /** One MCP server over the whole catalog, plus the docs and live state as resources and the skills as prompts. */
+ private createSession(): McpServer {
+ const knowledge = {
+ knowledgeDir: this.deps.knowledgeDir,
+ logs: this.deps.logs,
+ context: (signal: AbortSignal) => this.renderer.call("context", {}, signal) as Promise<ToolOutput<"context">>,
+ };
+ this.instructionsText ??= instructions(knowledge);
+ // `name` is the machine identity, and matches the key we write into agent
+ // configs; `title` is what a client shows a person.
+ const session = new McpServer({ name: SERVER_NAME, title: "Diffusion Studio", version: this.deps.version }, { instructions: this.instructionsText });
+ for (const tool of tools) this.register(session, tool);
+ registerResources(session, knowledge);
+ registerPrompts(session, knowledge);
+ return session;
+ }
+
+ private register(session: McpServer, tool: GenericTool): void {
+ session.registerTool(
+ tool.name,
+ { title: tool.title, description: tool.description, inputSchema: tool.input, outputSchema: tool.output },
+ async (args, extra) => {
+ try {
+ const result =
+ tool.environment === "main"
+ ? await this.runInMain(tool.name as MainToolName, args, extra.signal)
+ : await this.renderer.call(tool.name, args, extra.signal);
+ return toCallToolResult(await present(tool.name as ToolName, args, result));
+ } catch (error) {
+ return toErrorResult(error);
+ }
+ },
+ );
+ }
+
+ private runInMain(name: MainToolName, args: unknown, signal: AbortSignal): Promise<unknown> {
+ const ctx: MainContext = { signal, logs: this.deps.logs, version: this.deps.version };
+ // Each handler takes its own parsed args; the map's union type cannot
+ // express that pairing, so the call site widens.
+ return (mainHandlers[name] as (args: unknown, ctx: MainContext) => Promise<unknown>)(args, ctx);
+ }
+}
+
+/**
+ * A socket file left by a previous run (Unix). Safe to remove because the
+ * single-instance lock guarantees no other instance of ours is running.
+ */
+function removeStaleSocket(): void {
+ try {
+ if (process.platform !== "win32" && existsSync(SOCKET_PATH)) unlinkSync(SOCKET_PATH);
+ } catch {
+ // Best-effort.
+ }
+}
diff --git a/apps/desktop/src/edit-types.ts b/apps/desktop/src/edit-types.ts
new file mode 100644
index 00000000..1523cc57
--- /dev/null
+++ b/apps/desktop/src/edit-types.ts
@@ -0,0 +1,140 @@
+/* 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/. */
+
+// The shapes of a source edit and its outcome: the contract between the
+// canvas (renderer) and the edit writer (main). Types only, with no Node
+// imports, so the renderer's program can include it without Node's types.
+
+import type { InspectValue, PropValue, SerializedAssetRef } from "@diffusionstudio/jsx";
+
+export type { PropValue, SerializedAssetRef };
+
+/**
+ * A value an edit can carry: what a source spells as a literal, or a
+ * `generate.*` declaration in its wire form, spelled as the call that
+ * reproduces it (see `setProp`).
+ */
+export type EditValue = PropValue | SerializedAssetRef;
+
+export interface SourceContext {
+ /** Absolute path of the project folder. */
+ dir: string;
+ /** Called with the project-relative path of every file written. */
+ onWrite?: (file: string) => void;
+}
+
+/**
+ * Overwrites props of the element named by `source` (a `SOURCE_ATTR` value),
+ * and — for a `<text>` — what it says. `text` is its literal content, which is
+ * its children rather than a prop and so arrives on its own; an element that
+ * only says something new comes with no props at all.
+ */
+export interface SourceSet {
+ kind: "set";
+ source: string;
+ props: Record<string, EditValue>;
+ text?: string;
+}
+
+/**
+ * Adds `<tag {...props} />` under the element named by `parent`, in front of
+ * the child named by `before` or last. `source` is the pending name the canvas
+ * knows the new element by; the write answers with the real one in `ids`.
+ * A parent may itself be pending when it was inserted earlier in the same
+ * write. `text`, when present, is the element's literal text content
+ * (`<text>Hello</text>`); without it the element is written self-closing.
+ */
+export interface SourceInsert {
+ kind: "insert";
+ source: string;
+ parent: string;
+ tag: string;
+ props: Record<string, EditValue>;
+ before?: string;
+ text?: string;
+}
+
+/**
+ * Moves the element named by `source` under the one named by `parent`, in
+ * front of the child named by `before` or last. The element travels as it was
+ * written — its own text, re-indented for where it lands — so a move is the
+ * one edit that does not touch what an element says, only where it says it.
+ * Both ends must be in one file: an element cannot move into another module's
+ * JSX any more than a project could have put it there.
+ */
+export interface SourceMove {
+ kind: "move";
+ source: string;
+ parent: string;
+ before?: string;
+}
+
+/**
+ * Removes the element named by `source` from the file, and with it everything
+ * it contains: its children are its text, and go the way a move takes them
+ * along. Addressed like a move — an unnamed element is a position, and cutting
+ * text renumbers positions, so the element is found before anything is cut.
+ */
+export interface SourceRemove {
+ kind: "remove";
+ source: string;
+}
+
+/**
+ * One iteration of a loop as the canvas rendered it: for every composition
+ * element of the loop body, by its source, the props it came out with and (for
+ * a `<text>`) its literal content — the values that were computed from the
+ * item, spelled as literals. `pending` is the name the canvas already knows
+ * that iteration's copy of the element by; the write answers with the real
+ * one in `ids`. The first iteration keeps the body's own names, so it carries
+ * none.
+ */
+export type SourceIteration = Record<string, { props: Record<string, EditValue>; text?: string; pending?: string }>;
+
+/**
+ * Replaces the `<For>`/`<Index>` around the element named by `source` with
+ * one copy of its body per iteration, each spelling out what that iteration
+ * rendered. Nothing that comes after this in the same write can address a
+ * looped element (see `inLoop`): the loop is a recipe for elements, and a
+ * change to one of them means writing them down first.
+ */
+export interface SourceUnroll {
+ kind: "unroll";
+ source: string;
+ iterations: SourceIteration[];
+}
+
+/**
+ * Overwrites the initializer of an `@inspect`-annotated top-level const (see
+ * @diffusionstudio/jsx's inspect). Addressed by file and variable name — a
+ * const's name is unique in its module, so no id is needed — and only written
+ * when the declaration still carries the annotation and holds a literal: an
+ * initializer someone rewrote into an expression is theirs again.
+ */
+export interface SourceVariable {
+ kind: "variable";
+ file: string;
+ name: string;
+ value: InspectValue;
+}
+
+export type SourceEdit = SourceSet | SourceInsert | SourceMove | SourceRemove | SourceUnroll | SourceVariable;
+
+export interface WriteResult {
+ /** Sources that could not be written, as `id` or `id (prop)`. */
+ skipped: string[];
+ /**
+ * Elements that earned a name in this write, as `old source id -> new one`.
+ * The canvas re-stamps its entities with these, so identity does not have to
+ * wait for a recompile.
+ */
+ ids?: Record<string, string>;
+ /**
+ * The loops this write unrolled, by the `source` of the `SourceUnroll` that
+ * asked. An unroll not listed here was declined, and the canvas takes its
+ * loop back (see the edit writer).
+ */
+ unrolled?: string[];
+ error?: string;
+}
diff --git a/apps/desktop/src/edit.ts b/apps/desktop/src/edit.ts
index b878d6de..f0f7dd70 100644
--- a/apps/desktop/src/edit.ts
+++ b/apps/desktop/src/edit.ts
@@ -11,7 +11,7 @@ import { IndentationText, Project, SyntaxKind } from "ts-morph";
import { ID_ATTR, INSPECT_TAG, formatSource, isCompositionTag, isLoopTag, isSerializedAssetRef, parseSource } from "@diffusionstudio/jsx";
-import type { InspectValue, PropValue, SerializedAssetRef } from "@diffusionstudio/jsx";
+import type { PropValue, SerializedAssetRef } from "@diffusionstudio/jsx";
import type {
ArrowFunction,
FunctionExpression,
@@ -24,136 +24,19 @@ import type {
SourceFile,
} from "ts-morph";
-export type { PropValue, SerializedAssetRef };
-
-/**
- * A value an edit can carry: what a source spells as a literal, or a
- * `generate.*` declaration in its wire form, spelled as the call that
- * reproduces it (see `setProp`).
- */
-export type EditValue = PropValue | SerializedAssetRef;
-
-export interface SourceContext {
- /** Absolute path of the project folder. */
- dir: string;
- /** Called with the project-relative path of every file written. */
- onWrite?: (file: string) => void;
-}
-
-/**
- * Overwrites props of the element named by `source` (a `SOURCE_ATTR` value),
- * and — for a `<text>` — what it says. `text` is its literal content, which is
- * its children rather than a prop and so arrives on its own; an element that
- * only says something new comes with no props at all.
- */
-export interface SourceSet {
- kind: "set";
- source: string;
- props: Record<string, EditValue>;
- text?: string;
-}
-
-/**
- * Adds `<tag {...props} />` under the element named by `parent`, in front of
- * the child named by `before` or last. `source` is the pending name the canvas
- * knows the new element by; the write answers with the real one in `ids`.
- * A parent may itself be pending when it was inserted earlier in the same
- * write. `text`, when present, is the element's literal text content
- * (`<text>Hello</text>`); without it the element is written self-closing.
- */
-export interface SourceInsert {
- kind: "insert";
- source: string;
- parent: string;
- tag: string;
- props: Record<string, EditValue>;
- before?: string;
- text?: string;
-}
-
-/**
- * Moves the element named by `source` under the one named by `parent`, in
- * front of the child named by `before` or last. The element travels as it was
- * written — its own text, re-indented for where it lands — so a move is the
- * one edit that does not touch what an element says, only where it says it.
- * Both ends must be in one file: an element cannot move into another module's
- * JSX any more than a project could have put it there.
- */
-export interface SourceMove {
- kind: "move";
- source: string;
- parent: string;
- before?: string;
-}
-
-/**
- * Removes the element named by `source` from the file, and with it everything
- * it contains: its children are its text, and go the way a move takes them
- * along. Addressed like a move — an unnamed element is a position, and cutting
- * text renumbers positions, so the element is found before anything is cut.
- */
-export interface SourceRemove {
- kind: "remove";
- source: string;
-}
-
-/**
- * One iteration of a loop as the canvas rendered it: for every composition
- * element of the loop body, by its source, the props it came out with and (for
- * a `<text>`) its literal content — the values that were computed from the
- * item, spelled as literals. `pending` is the name the canvas already knows
- * that iteration's copy of the element by; the write answers with the real
- * one in `ids`. The first iteration keeps the body's own names, so it carries
- * none.
- */
-export type SourceIteration = Record<string, { props: Record<string, EditValue>; text?: string; pending?: string }>;
-
-/**
- * Replaces the `<For>`/`<Index>` around the element named by `source` with
- * one copy of its body per iteration, each spelling out what that iteration
- * rendered. Nothing that comes after this in the same write can address a
- * looped element (see `inLoop`): the loop is a recipe for elements, and a
- * change to one of them means writing them down first.
- */
-export interface SourceUnroll {
- kind: "unroll";
- source: string;
- iterations: SourceIteration[];
-}
-
-/**
- * Overwrites the initializer of an `@inspect`-annotated top-level const (see
- * @diffusionstudio/jsx's inspect). Addressed by file and variable name — a
- * const's name is unique in its module, so no id is needed — and only written
- * when the declaration still carries the annotation and holds a literal: an
- * initializer someone rewrote into an expression is theirs again.
- */
-export interface SourceVariable {
- kind: "variable";
- file: string;
- name: string;
- value: InspectValue;
-}
-
-export type SourceEdit = SourceSet | SourceInsert | SourceMove | SourceRemove | SourceUnroll | SourceVariable;
-
-export interface WriteResult {
- /** Sources that could not be written, as `id` or `id (prop)`. */
- skipped: string[];
- /**
- * Elements that earned a name in this write, as `old source id -> new one`.
- * The canvas re-stamps its entities with these, so identity does not have to
- * wait for a recompile.
- */
- ids?: Record<string, string>;
- /**
- * The loops this write unrolled, by the `source` of the `SourceUnroll` that
- * asked. An unroll not listed here was declined, and the canvas takes its
- * loop back (see the edit writer).
- */
- unrolled?: string[];
- error?: string;
-}
+export type * from "./edit-types";
+import type {
+ EditValue,
+ SourceContext,
+ SourceEdit,
+ SourceInsert,
+ SourceIteration,
+ SourceMove,
+ SourceRemove,
+ SourceUnroll,
+ SourceVariable,
+ WriteResult,
+} from "./edit-types";
/** The opening half of a JSX element — where its attributes live. */
type JsxTag = JsxOpeningElement | JsxSelfClosingElement;
diff --git a/apps/desktop/src/headless.ts b/apps/desktop/src/headless.ts
new file mode 100644
index 00000000..b695807e
--- /dev/null
+++ b/apps/desktop/src/headless.ts
@@ -0,0 +1,18 @@
+/* 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/. */
+
+// Whether an agent has connected since launch. Once one has, the UI steps
+// back: file writes from tools are not echoed as edits, and the window may
+// stay hidden. Set by the MCP server on its first connection; read wherever
+// behaviour depends on who is driving.
+
+let headless = false;
+
+export function isHeadless(): boolean {
+ return headless;
+}
+
+export function enableHeadless(): void {
+ headless = true;
+}
diff --git a/apps/desktop/src/main-channels.ts b/apps/desktop/src/main-channels.ts
index 5df8bb83..79e17eac 100644
--- a/apps/desktop/src/main-channels.ts
+++ b/apps/desktop/src/main-channels.ts
@@ -7,10 +7,10 @@
// through these via an envelope carrying the logical MAIN_CHANNELS name and
// (for requests) a UUID for correlation.
//
-// 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 { SourceEdit, WriteResult } from "./edit";
+// Tool calls from the MCP server use their own wire (DAPI_WIRE in
+// @diffusionstudio/dapi), in the other direction: main asks, the renderer answers.
+import type { LogEntry, ScreenshotResult } from "@diffusionstudio/dapi";
+import type { SourceEdit, WriteResult } from "./edit-types";
export const MAIN_WIRE = {
REQUEST: "main:request",
@@ -23,8 +23,8 @@ export type MainWireChannel = (typeof MAIN_WIRE)[keyof typeof MAIN_WIRE];
// Logical channels. Two categories:
// • Renderer→Main requests (request + response)
// • Main→Renderer events (push, no response)
-// Renderer-state queries used to live here; they now answer CLI requests
-// directly via the CLI bridge.
+// Tool calls are not here: they arrive from main over DAPI_WIRE and are
+// answered by the renderer's handlers (apps/web/src/dapi).
export const MAIN_CHANNELS = {
// Renderer→Main requests
APP_OPEN_EXTERNAL: "app:open-external",
@@ -33,8 +33,8 @@ export const MAIN_CHANNELS = {
CHECKOUT_GET_PENDING_CALLBACK: "checkout:get-pending-callback",
CLI_IS_INSTALLED: "cli:is-installed",
CLI_INSTALL: "cli:install",
- SKILLS_IS_INSTALLED: "skills:is-installed",
- SKILLS_INSTALL: "skills:install",
+ MCP_IS_REGISTERED: "mcp:is-registered",
+ MCP_REGISTER: "mcp:register",
WINDOW_IS_FULLSCREEN: "window:is-fullscreen",
WINDOW_CAPTURE: "window:capture",
FILE_TRANSFER: "file:transfer",
@@ -112,9 +112,12 @@ export type CliInstallResult =
| { status: "cancelled" }
| { status: "error"; error: string };
-// Outcome of symlinking the bundled skills into the agent skill directories.
-export type SkillsInstallResult =
- | { status: "installed" }
+// Outcome of registering the app's MCP server with the agents on this
+// machine. `agents` names the configs written; `url` is the HTTP endpoint
+// most of them got, `command` the stdio proxy the rest run (null when this
+// build has no dapi binary).
+export type McpRegisterResult =
+ | { status: "registered"; agents: string[]; url: string; command: string | null }
| { status: "error"; error: string };
export type { SourceEdit, WriteResult };
@@ -133,8 +136,8 @@ export type MainRequestMap = {
[MAIN_CHANNELS.CHECKOUT_GET_PENDING_CALLBACK]: { request: void; response: string | null };
[MAIN_CHANNELS.CLI_IS_INSTALLED]: { request: void; response: boolean };
[MAIN_CHANNELS.CLI_INSTALL]: { request: void; response: CliInstallResult };
- [MAIN_CHANNELS.SKILLS_IS_INSTALLED]: { request: void; response: boolean };
- [MAIN_CHANNELS.SKILLS_INSTALL]: { request: void; response: SkillsInstallResult };
+ [MAIN_CHANNELS.MCP_IS_REGISTERED]: { request: void; response: boolean };
+ [MAIN_CHANNELS.MCP_REGISTER]: { request: void; response: McpRegisterResult };
[MAIN_CHANNELS.WINDOW_IS_FULLSCREEN]: { request: void; response: boolean };
[MAIN_CHANNELS.WINDOW_CAPTURE]: { request: void; response: ScreenshotResult };
[MAIN_CHANNELS.FILE_TRANSFER]: {
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index b965b054..3cadaec0 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -4,13 +4,15 @@
import { app, BrowserWindow, nativeImage, session, shell } from "electron";
import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
import { mkdir, open, unlink } from "node:fs/promises";
import { randomUUID } from "node:crypto";
import type { FileHandle } from "node:fs/promises";
import { updateElectronApp } from "update-electron-app";
-import { startCliServer, stopCliServer, isHeadless } from "./cli-server";
+import { DapiServer } from "./dapi/server";
+import { enableHeadless, isHeadless } from "./headless";
import { installCli, isCliInstalled } from "./cli-install";
-import { healSkillsLinks, installSkills, isSkillsInstalled } from "./skills-install";
+import { healMcpRegistrations, isMcpRegistered, registerMcp } from "./mcp-install";
import { trackInstall } from "./analytics";
import { setupAppMenu } from "./menu";
import { mainBridge } from "./main-manager";
@@ -42,7 +44,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";
@@ -97,6 +99,29 @@ const pendingDeepLinks = new Map<DeepLinkChannel, string>();
const LOG_BUFFER_MAX = 2000;
const logBuffer: LogEntry[] = [];
+// The knowledge base the MCP server serves: staged into the bundle by
+// scripts/stage-knowledge.mjs (Contents/Resources/knowledge) when packaged;
+// the repo's own `knowledge/` in development, so edits show up without a
+// staging step. Null when neither exists.
+function knowledgeDir(): string | null {
+ const dir = app.isPackaged ? join(process.resourcesPath, "knowledge") : join(app.getAppPath(), "..", "..", "knowledge");
+ return existsSync(dir) ? dir : null;
+}
+
+// The MCP server agents and the dapi CLI talk to. Started once the app is
+// ready; the first connection switches the UI into headless mode.
+const dapi = new DapiServer({
+ version: app.getVersion(),
+ logs: () => logBuffer,
+ knowledgeDir: knowledgeDir(),
+ onFirstConnection() {
+ enableHeadless();
+ if (mainWindow && !mainWindow.isDestroyed()) {
+ mainBridge.emit(mainWindow, MAIN_CHANNELS.HEADLESS_MODE, { active: true });
+ }
+ },
+});
+
function pushLog(level: LogEntry["level"], message: string, source: string) {
logBuffer.push({ ts: Date.now(), level, message, source });
if (logBuffer.length > LOG_BUFFER_MAX) logBuffer.shift();
@@ -262,8 +287,8 @@ if (app.requestSingleInstanceLock()) {
mainBridge.handle(MAIN_CHANNELS.APP_SHOW_IN_FOLDER, ({ path }) => shell.showItemInFolder(path));
mainBridge.handle(MAIN_CHANNELS.CLI_IS_INSTALLED, () => isCliInstalled());
mainBridge.handle(MAIN_CHANNELS.CLI_INSTALL, () => installCli());
- mainBridge.handle(MAIN_CHANNELS.SKILLS_IS_INSTALLED, () => isSkillsInstalled());
- mainBridge.handle(MAIN_CHANNELS.SKILLS_INSTALL, () => installSkills());
+ mainBridge.handle(MAIN_CHANNELS.MCP_IS_REGISTERED, () => isMcpRegistered());
+ mainBridge.handle(MAIN_CHANNELS.MCP_REGISTER, () => registerMcp());
mainBridge.handle(MAIN_CHANNELS.AUTH_GET_PENDING_CALLBACK, () =>
takePendingDeepLink(MAIN_CHANNELS.AUTH_CALLBACK),
);
@@ -275,7 +300,9 @@ if (app.requestSingleInstanceLock()) {
if (!mainWindow || mainWindow.isDestroyed()) throw new Error("No main window");
const image = await mainWindow.webContents.capturePage(undefined, { stayHidden: true });
const { width, height } = image.getSize();
- return { base64: image.toPNG().toString("base64"), width, height };
+ const png = image.toPNG();
+ // A plain Uint8Array over the PNG, so the renderer sees bytes and not a Buffer.
+ return { png: new Uint8Array(png.buffer, png.byteOffset, png.byteLength), width, height };
});
mainBridge.handle(MAIN_CHANNELS.HEADLESS_GET_MODE, () => isHeadless());
mainBridge.handle(MAIN_CHANNELS.LOGS_GET, () => logBuffer);
@@ -359,15 +386,15 @@ if (app.requestSingleInstanceLock()) {
const url = findProtocolUrl(process.argv);
if (url) deliverDeepLink(url);
- startCliServer();
- healSkillsLinks();
+ dapi.start();
+ healMcpRegistrations();
trackInstall();
createWindow(!isHiddenLaunch(process.argv));
});
app.on("before-quit", () => {
unwatchAll();
- stopCliServer();
+ dapi.stop();
});
app.on("window-all-closed", () => {
diff --git a/apps/desktop/src/mcp-config.test.ts b/apps/desktop/src/mcp-config.test.ts
new file mode 100644
index 00000000..a294410c
--- /dev/null
+++ b/apps/desktop/src/mcp-config.test.ts
@@ -0,0 +1,111 @@
+/* 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 { AGENT_TARGETS, readServer, upsertServer } from "./mcp-config";
+
+const spec = {
+ url: "http://127.0.0.1:3274/mcp",
+ command: "/Applications/Diffusion Studio.app/Contents/Resources/cli/bin/dapi",
+ args: ["mcp"],
+};
+
+const target = (label: string) => {
+ const found = AGENT_TARGETS.find((t) => t.label === label);
+ if (!found) throw new Error(label);
+ return found;
+};
+
+describe("per-agent entries", () => {
+ it("spells the URL the way each agent expects", () => {
+ expect(target("Claude Code").entry(spec)).toEqual({ type: "http", url: spec.url });
+ expect(target("Cursor").entry(spec)).toEqual({ url: spec.url });
+ expect(target("Codex").entry(spec)).toEqual({ url: spec.url });
+ expect(target("Gemini CLI").entry(spec)).toEqual({ httpUrl: spec.url });
+ expect(target("Windsurf").entry(spec)).toEqual({ serverUrl: spec.url });
+ });
+
+ it("gives Claude Desktop the stdio proxy", () => {
+ expect(target("Claude Desktop").entry(spec)).toEqual({ command: spec.command, args: ["mcp"] });
+ });
+});
+
+describe("json configs", () => {
+ it("creates the file from nothing", () => {
+ const text = upsertServer(null, "json", { type: "http", url: spec.url });
+ expect(JSON.parse(text)).toEqual({ mcpServers: { diffusion: { type: "http", url: spec.url } } });
+ expect(text.endsWith("\n")).toBe(true);
+ });
+
+ it("keeps other servers and unrelated keys", () => {
+ const before = JSON.stringify({
+ numStartups: 12,
+ mcpServers: { other: { command: "x", args: [] } },
+ projects: { "/a": { allowedTools: [] } },
+ });
+ const after = JSON.parse(upsertServer(before, "json", { url: spec.url }));
+ expect(after.numStartups).toBe(12);
+ expect(after.projects).toEqual({ "/a": { allowedTools: [] } });
+ expect(after.mcpServers.other).toEqual({ command: "x", args: [] });
+ expect(after.mcpServers.diffusion).toEqual({ url: spec.url });
+ });
+
+ it("replaces a stdio entry with a URL entry, and reads either", () => {
+ const before = upsertServer(null, "json", { command: "/old/dapi", args: ["mcp"] });
+ expect(readServer(before, "json")).toEqual({ command: "/old/dapi" });
+ const after = upsertServer(before, "json", { type: "http", url: spec.url });
+ expect(readServer(after, "json")).toEqual({ url: spec.url });
+ expect(JSON.parse(after).mcpServers.diffusion.command).toBeUndefined();
+ });
+
+ it("reads the URL under each agent's key", () => {
+ for (const key of ["url", "httpUrl", "serverUrl"]) {
+ expect(readServer(upsertServer(null, "json", { [key]: spec.url }), "json")).toEqual({ url: spec.url });
+ }
+ });
+
+ it("refuses to overwrite a file it cannot parse", () => {
+ expect(() => upsertServer("{ not json", "json", { url: spec.url })).toThrow();
+ expect(() => upsertServer("[1, 2]", "json", { url: spec.url })).toThrow();
+ expect(readServer("{ not json", "json")).toBeNull();
+ });
+
+ it("treats an empty file as no config", () => {
+ expect(readServer("", "json")).toBeNull();
+ expect(JSON.parse(upsertServer(" \n", "json", { url: spec.url }))).toEqual({ mcpServers: { diffusion: { url: spec.url } } });
+ });
+});
+
+describe("toml configs (codex)", () => {
+ it("appends a table to an existing config", () => {
+ const before = 'model = "o3"\n\n[mcp_servers.other]\ncommand = "x"\n';
+ const after = upsertServer(before, "toml", { url: spec.url });
+ expect(after).toBe('model = "o3"\n\n[mcp_servers.other]\ncommand = "x"\n\n[mcp_servers.diffusion]\nurl = "http://127.0.0.1:3274/mcp"\n');
+ expect(readServer(after, "toml")).toEqual({ url: spec.url });
+ });
+
+ it("replaces our table in place and leaves the next one alone", () => {
+ const before = '[mcp_servers.diffusion]\ncommand = "/old/dapi"\nargs = ["mcp"]\n\n[mcp_servers.other]\ncommand = "x"\n';
+ expect(readServer(before, "toml")).toEqual({ command: "/old/dapi" });
+ const after = upsertServer(before, "toml", { url: spec.url });
+ expect(after).toBe('[mcp_servers.diffusion]\nurl = "http://127.0.0.1:3274/mcp"\n[mcp_servers.other]\ncommand = "x"\n');
+ expect(readServer(after, "toml")).toEqual({ url: spec.url });
+ });
+
+ it("starts a file from nothing", () => {
+ const text = upsertServer(null, "toml", { url: spec.url });
+ expect(text).toBe('[mcp_servers.diffusion]\nurl = "http://127.0.0.1:3274/mcp"\n');
+ });
+
+ it("escapes quotes and backslashes in stdio paths", () => {
+ const odd = { command: 'C:\\Apps\\"Diffusion"\\dapi', args: ["mcp"] };
+ const text = upsertServer(null, "toml", odd);
+ expect(text).toContain('command = "C:\\\\Apps\\\\\\"Diffusion\\"\\\\dapi"');
+ expect(readServer(text, "toml")).toEqual({ command: odd.command });
+ });
+
+ it("reads nothing from a config without our table", () => {
+ expect(readServer('model = "o3"\n', "toml")).toBeNull();
+ });
+});
diff --git a/apps/desktop/src/mcp-config.ts b/apps/desktop/src/mcp-config.ts
new file mode 100644
index 00000000..fab14673
--- /dev/null
+++ b/apps/desktop/src/mcp-config.ts
@@ -0,0 +1,166 @@
+/* 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/. */
+
+// How the app's MCP server is written into each agent's config, as pure
+// text transforms: no file system, no Electron, so the merge rules are
+// testable. `mcp-install.ts` decides which files and does the I/O.
+
+/**
+ * The two ways to reach the app. Agents that speak Streamable HTTP get the
+ * URL, which is the same on every machine; the rest get the bundled `dapi`
+ * binary in stdio proxy mode.
+ */
+export type McpServerSpec = { url: string; command: string; args: string[] };
+
+/**
+ * The key our entry lives under in every agent's server map, and so the
+ * namespace an agent shows us under: `mcp__diffusion__<tool>` and
+ * `/diffusion:<prompt>`. The same word as our URL scheme, and not `dapi`,
+ * which is the CLI.
+ */
+export const SERVER_NAME = "diffusion";
+
+/** One agent's config entry: what its file format spells a server as. */
+export type ServerEntry = Record<string, string | string[]>;
+
+export type AgentTarget = {
+ /** Human name, for the result dialog. */
+ label: string;
+ /** Home-relative path whose presence means the agent is set up on this machine. */
+ marker: string;
+ /** Home-relative path of the config file our entry goes into. */
+ config: string;
+ format: "json" | "toml";
+ /** The entry for this agent: which transport it gets, under the keys its format uses. */
+ entry(spec: McpServerSpec): ServerEntry;
+};
+
+const http = (key: string, extra: ServerEntry = {}) => (spec: McpServerSpec): ServerEntry => ({ ...extra, [key]: spec.url });
+const stdio = (spec: McpServerSpec): ServerEntry => ({ command: spec.command, args: [...spec.args] });
+
+// Agents whose MCP config we know how to write. Claude Code's user scope is
+// the top-level `mcpServers` of ~/.claude.json, the same file `claude mcp
+// add --scope user` edits. Claude Desktop's file takes stdio commands only,
+// so it gets the proxy.
+export const AGENT_TARGETS: readonly AgentTarget[] = [
+ { label: "Claude Code", marker: ".claude", config: ".claude.json", format: "json", entry: http("url", { type: "http" }) },
+ { label: "Codex", marker: ".codex", config: ".codex/config.toml", format: "toml", entry: http("url") },
+ { label: "Cursor", marker: ".cursor", config: ".cursor/mcp.json", format: "json", entry: http("url") },
+ { label: "Gemini CLI", marker: ".gemini", config: ".gemini/settings.json", format: "json", entry: http("httpUrl") },
+ { label: "Windsurf", marker: ".codeium/windsurf", config: ".codeium/windsurf/mcp_config.json", format: "json", entry: http("serverUrl") },
+ {
+ label: "Claude Desktop",
+ marker: "Library/Application Support/Claude",
+ config: "Library/Application Support/Claude/claude_desktop_config.json",
+ format: "json",
+ entry: stdio,
+ },
+];
+
+/** The agent a machine with none of the above still gets set up for. */
+export const FALLBACK_TARGET = AGENT_TARGETS[0];
+
+/**
+ * The config with our entry set, leaving everything else as it was. `text`
+ * is the file's current content, or null when there is none yet. Throws
+ * when the file cannot be parsed: a config we cannot read is not one we
+ * should overwrite.
+ */
+export function upsertServer(text: string | null, format: AgentTarget["format"], entry: ServerEntry): string {
+ return format === "toml" ? upsertToml(text, entry) : upsertJson(text, entry);
+}
+
+/** Where our entry currently points, whatever keys the agent spells it with; null when there is none. */
+export type Registered = { url?: string; command?: string };
+
+export function readServer(text: string | null, format: AgentTarget["format"]): Registered | null {
+ if (text === null) return null;
+ const entry = format === "toml" ? readToml(text) : readJson(text);
+ if (!entry) return null;
+ const url = entry.url ?? entry.httpUrl ?? entry.serverUrl;
+ const command = entry.command;
+ if (typeof url !== "string" && typeof command !== "string") return null;
+ return {
+ ...(typeof url === "string" ? { url } : {}),
+ ...(typeof command === "string" ? { command } : {}),
+ };
+}
+
+// --- JSON ------------------------------------------------------------------
+
+type JsonConfig = { mcpServers?: Record<string, unknown> } & Record<string, unknown>;
+
+function parseJson(text: string | null): JsonConfig {
+ if (text === null || text.trim() === "") return {};
+ const parsed: unknown = JSON.parse(text);
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+ throw new Error("expected a JSON object at the top level");
+ }
+ return parsed as JsonConfig;
+}
+
+function upsertJson(text: string | null, entry: ServerEntry): string {
+ const config = parseJson(text);
+ const servers = typeof config.mcpServers === "object" && config.mcpServers !== null ? config.mcpServers : {};
+ config.mcpServers = { ...servers, [SERVER_NAME]: entry };
+ return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+function readJson(text: string): Record<string, unknown> | null {
+ let config: JsonConfig;
+ try {
+ config = parseJson(text);
+ } catch {
+ return null;
+ }
+ const entry = config.mcpServers?.[SERVER_NAME];
+ return typeof entry === "object" && entry !== null ? (entry as Record<string, unknown>) : null;
+}
+
+// --- TOML (Codex) ----------------------------------------------------------
+
+// Our table, from its header up to the next table header or the end. A
+// header line is `[...]` at column 0; indented or commented ones are not.
+const TOML_TABLE = new RegExp(String.raw`^\[mcp_servers\.${SERVER_NAME}\][^\n]*\n(?:(?!\[)[^\n]*\n?)*`, "m");
+
+function tomlString(value: string): string {
+ return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+
+function tomlValue(value: string | string[]): string {
+ return Array.isArray(value) ? `[${value.map(tomlString).join(", ")}]` : tomlString(value);
+}
+
+function tomlTable(entry: ServerEntry): string {
+ const lines = Object.entries(entry).map(([key, value]) => `${key} = ${tomlValue(value)}`);
+ return [`[mcp_servers.${SERVER_NAME}]`, ...lines, ""].join("\n");
+}
+
+function upsertToml(text: string | null, entry: ServerEntry): string {
+ const current = text ?? "";
+ const table = tomlTable(entry);
+ if (TOML_TABLE.test(current)) return current.replace(TOML_TABLE, table);
+ const separator = current === "" || current.endsWith("\n\n") ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+ return `${current}${separator}${table}`;
+}
+
+function readToml(text: string): Record<string, unknown> | null {
+ const table = text.match(TOML_TABLE)?.[0];
+ if (!table) return null;
+ const entry: Record<string, unknown> = {};
+ for (const line of table.split("\n").slice(1)) {
+ const scalar = line.match(/^(\w+)\s*=\s*"((?:[^"\\]|\\.)*)"\s*$/);
+ if (scalar) {
+ entry[scalar[1]] = untomlString(scalar[2]);
+ continue;
+ }
+ const list = line.match(/^(\w+)\s*=\s*\[([^\]]*)\]\s*$/);
+ if (list) entry[list[1]] = [...list[2].matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => untomlString(m[1]));
+ }
+ return entry;
+}
+
+function untomlString(value: string): string {
+ return value.replaceAll('\\"', '"').replaceAll("\\\\", "\\");
+}
diff --git a/apps/desktop/src/mcp-install.ts b/apps/desktop/src/mcp-install.ts
new file mode 100644
index 00000000..b37d8400
--- /dev/null
+++ b/apps/desktop/src/mcp-install.ts
@@ -0,0 +1,131 @@
+/* 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/. */
+
+// Registers the app's MCP server with the agents on this machine: the fixed
+// loopback URL for agents that speak HTTP, the bundled `dapi mcp` proxy for
+// the rest. No PATH symlink and no admin prompt — the counterpart of the
+// shell install in `cli-install.ts`, which stays for people who type `dapi`.
+
+import { app } from "electron";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { MCP_URL } from "@diffusionstudio/dapi/socket";
+import { AGENT_TARGETS, FALLBACK_TARGET, readServer, upsertServer } from "./mcp-config";
+
+import type { AgentTarget, McpServerSpec } from "./mcp-config";
+import type { McpRegisterResult } from "./main-channels";
+
+// The dev workflow links the workspace build into Homebrew's bin
+// (`symlink:create` in apps/cli); that is the binary a dev build registers.
+const DEV_BINARY = "/opt/homebrew/bin/dapi";
+
+/** The bundled `dapi` binary, or null when none is available (an unstaged dev build). */
+export function dapiBinary(): string | null {
+ const command = app.isPackaged ? join(process.resourcesPath, "cli", "bin", "dapi") : DEV_BINARY;
+ return existsSync(command) ? command : null;
+}
+
+function spec(): McpServerSpec {
+ return { url: MCP_URL, command: dapiBinary() ?? "", args: ["mcp"] };
+}
+
+function configPath(target: AgentTarget): string {
+ return join(homedir(), target.config);
+}
+
+function readConfig(target: AgentTarget): string | null {
+ const path = configPath(target);
+ return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+
+function writeConfig(target: AgentTarget, text: string): void {
+ const path = configPath(target);
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, text);
+}
+
+function needsBinary(target: AgentTarget): boolean {
+ return "command" in target.entry({ url: MCP_URL, command: "x", args: [] });
+}
+
+// Agents present on this machine, falling back to Claude Code so a machine
+// with no agent yet still gets set up for the primary one.
+function targetAgents(): AgentTarget[] {
+ const home = homedir();
+ const present = AGENT_TARGETS.filter((target) => existsSync(join(home, target.marker)));
+ return present.length > 0 ? present : [FALLBACK_TARGET];
+}
+
+/** True when at least one agent's config points at this app. */
+export function isMcpRegistered(): boolean {
+ const current = spec();
+ return AGENT_TARGETS.some((target) => {
+ const registered = readServer(readConfig(target), target.format);
+ return registered?.url === current.url || (current.command !== "" && registered?.command === current.command);
+ });
+}
+
+export function registerMcp(): McpRegisterResult {
+ // A quarantined first launch runs from a translocated read-only mount whose
+ // path won't survive the next launch — registering it would dangle.
+ if (app.isPackaged && process.resourcesPath.includes("/AppTranslocation/")) {
+ return {
+ status: "error",
+ error: "Move Diffusion Studio to the Applications folder and relaunch it, then try again.",
+ };
+ }
+ const current = spec();
+ const agents: string[] = [];
+ const failures: string[] = [];
+ for (const target of targetAgents()) {
+ if (needsBinary(target) && current.command === "") {
+ failures.push(`${target.label}: needs the dapi binary, which this build does not have`);
+ continue;
+ }
+ try {
+ writeConfig(target, upsertServer(readConfig(target), target.format, target.entry(current)));
+ agents.push(target.label);
+ } catch (e) {
+ failures.push(`${target.label} (${target.config}): ${(e as Error).message}`);
+ }
+ }
+ if (agents.length === 0) {
+ return { status: "error", error: `Could not write any agent config:\n${failures.join("\n")}` };
+ }
+ return {
+ status: "registered",
+ agents,
+ url: current.url,
+ command: current.command === "" ? null : `${current.command} ${current.args.join(" ")}`,
+ };
+}
+
+/**
+ * Launch-time self-heal. Two cases: an entry that still runs the stdio proxy
+ * from a bundle that moved (or was translocated when it was written), and an
+ * entry written before the app served HTTP, which the agent could be using
+ * the URL for instead. Both are rewritten to what `registerMcp` would write
+ * today. Entries the user wrote by hand for something else are left alone.
+ */
+export function healMcpRegistrations(): void {
+ if (!app.isPackaged) return;
+ const current = spec();
+ if (current.command === "" || current.command.includes("/AppTranslocation/")) return;
+
+ for (const target of AGENT_TARGETS) {
+ const text = readConfig(target);
+ const registered = readServer(text, target.format);
+ if (!registered?.command) continue;
+ const ours = registered.command.includes("Diffusion Studio") || registered.command.includes("/AppTranslocation/");
+ if (!ours) continue;
+ const entry = target.entry(current);
+ if (registered.command === entry.command) continue;
+ try {
+ writeConfig(target, upsertServer(text, target.format, entry));
+ } catch {
+ // best effort — the connect button remains as a manual fix
+ }
+ }
+}
diff --git a/apps/desktop/src/menu.ts b/apps/desktop/src/menu.ts
index 31bef6aa..3893344a 100644
--- a/apps/desktop/src/menu.ts
+++ b/apps/desktop/src/menu.ts
@@ -6,6 +6,27 @@ import { app, dialog, Menu } from "electron";
import type { MenuItemConstructorOptions } from "electron";
import { CLI_LINK_PATH, installCli } from "./cli-install";
+import { registerMcp } from "./mcp-install";
+
+async function registerMcpFromMenu() {
+ const result = registerMcp();
+ if (result.status === "registered") {
+ await dialog.showMessageBox({
+ type: "info",
+ message: "Diffusion Studio is registered as an MCP server.",
+ detail: [
+ `Connected: ${result.agents.join(", ")}. Restart the agent to pick it up.`,
+ `Any other agent can use the URL ${result.url}${result.command ? `, or run "${result.command}" over stdio` : ""}.`,
+ ].join("\n\n"),
+ });
+ } else {
+ await dialog.showMessageBox({
+ type: "error",
+ message: "Could not register the MCP server.",
+ detail: result.error,
+ });
+ }
+}
async function installCliFromMenu() {
const result = await installCli();
@@ -34,6 +55,10 @@ export function setupAppMenu() {
submenu: [
{ role: "about" },
{ type: "separator" },
+ {
+ label: "Connect Agents (MCP)…",
+ click: registerMcpFromMenu,
+ },
{
label: "Install dapi Command Line Tool…",
enabled: app.isPackaged,
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index 688361ec..1793687d 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -4,16 +4,17 @@
import { contextBridge, ipcRenderer, webUtils } from "electron";
import { MAIN_WIRE } from "./main-channels";
-import { CLI_WIRE } from "@diffusionstudio/cli/channels";
+import { DAPI_WIRE } from "@diffusionstudio/dapi";
import type { IpcRendererEvent } from "electron";
-const ALLOWED_RENDERER_TO_MAIN: ReadonlySet<string> = new Set([MAIN_WIRE.REQUEST]);
+const ALLOWED_RENDERER_TO_MAIN: ReadonlySet<string> = new Set([MAIN_WIRE.REQUEST, DAPI_WIRE.REPLY]);
const ALLOWED_MAIN_TO_RENDERER: ReadonlySet<string> = new Set([
MAIN_WIRE.RESPONSE,
MAIN_WIRE.EVENT,
- CLI_WIRE.CONNECT,
+ DAPI_WIRE.CALL,
+ DAPI_WIRE.CANCEL,
]);
contextBridge.exposeInMainWorld("desktop", {
diff --git a/apps/desktop/src/projects.ts b/apps/desktop/src/projects.ts
index 533fffb9..6b93c379 100644
--- a/apps/desktop/src/projects.ts
+++ b/apps/desktop/src/projects.ts
@@ -9,12 +9,13 @@ import { cp, mkdir, readdir, readFile, realpath, rename, rm, stat, writeFile } f
import { createRequire } from "node:module";
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { nanoid } from "nanoid";
+import { MCP_URL } from "@diffusionstudio/dapi/socket";
import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
import type { PluginItem, TransformOptions } from "@babel/core";
import type { BuildOptions, Plugin } from "esbuild";
-import { isHeadless } from "./cli-server";
+import { isHeadless } from "./headless";
import { mainBridge } from "./main-manager";
import { MAIN_CHANNELS } from "./main-channels";
import { applyEdits, editLabel, stampProject } from "./edit";
@@ -530,7 +531,7 @@ const TSCONFIG = `{
}
`;
-/** What a project folder produces but should not check in: installs, derived data (thumbnails, waveforms), and the app-owned docs. */
+/** What a project folder produces but should not check in: installs, derived data (thumbnails, waveforms), and the app-owned folder. */
const GITIGNORE = `node_modules/
cache/
.diffusion/
@@ -564,6 +565,14 @@ a plain npm package whose entry file is a [Solid](https://www.solidjs.com)
component; the app compiles it and renders every element into an editable node
on the canvas.
+## Agents
+
+Everything an agent needs is in the app's MCP server (\`dapi\`): its tools
+are the API, its instructions say how to work, and its resources are the
+authoring reference for the installed version. If it is not among your tools,
+add it — the app serves it at \`${MCP_URL}\` while it is running — and start
+a new session.
+
## Structure
| Path | What it is |
@@ -574,8 +583,6 @@ on the canvas.
| \`assets.yml\` | The asset library: for every asset its library path, where its bytes are, and what it was found to be. Written by the app; hand edits are read on the next load. |
| \`assets/\` | The library's files: put one here and it is taken in while the app watches, and the app writes its own here too — generations under \`assets/generated/\`. Media imported through the app is linked where it lies instead, never copied. |
| \`cache/\` | Derived data (thumbnails, waveforms). Disposable, and not checked in. |
-| \`AGENTS.md\` | The agent entry point: what to read in \`.diffusion/docs/\` and how to work here. |
-| \`.diffusion/\` | App-owned. \`docs/\` is the authoring reference and examples for the installed app version; the app regenerates it, and it is not checked in. |
## Authoring
@@ -662,116 +669,21 @@ All of them talk to the running app, except \`fonts\` and \`fetch\`.
## Reference
-- [JSX reference](https://github.com/diffusionstudio/editor/blob/main/reference/jsx/README.md): elements, timing, paints, generation, captions
-- [CLI reference](https://github.com/diffusionstudio/editor/blob/main/reference/README.md): every command, its options and its output
-- [Examples](https://github.com/diffusionstudio/editor/tree/main/examples): runnable compositions to read
-`;
-
-/**
- * The agent entry point, written once like the README: the file coding agents
- * load without being asked, and therefore the one place a project is reliably
- * discovered from. Loaded into context whole, so it stays a thin index into
- * `.diffusion/docs` rather than the docs themselves — and being the author's
- * file after the first write, an agent can append project conventions to it
- * while the paths it points at stay put.
- */
-const AGENTS = `# Authoring this project
-
-A Diffusion Studio project: a video composition authored as code. The entry
-(\`index.tsx\`) default-exports a Solid component that renders a \`<stage>\`;
-the app compiles it and renders every element into an editable node on the
-canvas. The source is the document in both directions: saving recompiles and
-remounts the project, and edits made in the app land back in the JSX as props
-on the element they were authored as.
-
-## Docs
-
-\`.diffusion/docs/\` holds the authoring reference and runnable examples for
-the installed app version. The app regenerates it on version changes: read it,
-never edit it, and trust it over memory.
-
-| Read | For |
-| ---- | --- |
-| \`.diffusion/docs/reference/jsx/README.md\` | The JSX contract — elements, props, pipeline. Start here. |
-| \`.diffusion/docs/reference/jsx/timing.md\` | \`start\`/\`end\`/\`sourceIn\`/\`sourceOut\`, and the time formats. |
-| \`.diffusion/docs/reference/jsx/generate.md\` | Declaring AI-generated assets (\`generate.*\`). |
-| \`.diffusion/docs/reference/jsx/variables.md\` | \`@inspect\` variables: annotated consts as live inspector controls. |
-| \`.diffusion/docs/reference/README.md\` | Every dapi command, its options and its output. |
-| \`.diffusion/docs/examples/\` | Complete compositions, basics through shaders. |
-
-## Working here
-
-- Every dapi command is an npm script: \`npm run\` lists them, and
- \`npm run <name> -- <args>\` runs one.
-- \`npm run context\` reports what the app has open, where its playhead sits,
- and where generations stand.
-- Verify visually with \`npm run capture -- <sceneId>\`: it renders the
- scene's frames exactly as an export encodes them. Do not export a video to
- check work.
-- Position and size are explicit, in pixels. There is no layout pass and no CSS.
-- A composition you author from scratch marks one scene \`active\` and gives
- \`<stage>\` a \`camera\` framing it, or the project opens on an empty timeline
- with the frame off screen.
-- Times are seconds (\`1.5\`), frames (\`"45f"\`), or \`"MM:SS"\`.
-- Types are stripped at compile time, never checked: run \`npx tsc --noEmit\`.
+- [JSX reference](https://github.com/diffusionstudio/editor/blob/main/knowledge/reference/jsx/README.md): elements, timing, paints, generation, captions
+- [Tool reference](https://github.com/diffusionstudio/editor/blob/main/knowledge/reference/tools/README.md): every tool and command, its options and its output
+- [Examples](https://github.com/diffusionstudio/editor/tree/main/knowledge/examples): runnable compositions to read
`;
// ---------------------------------------------------------------------------
-// Authoring docs
+// The app-owned folder
/**
- * The project-relative folder the app owns outright. Everything else the
- * scaffold writes is written once and is the author's from then on; this
- * folder is regenerated wholesale, which is why it gets a namespace of its
- * own instead of files among the author's.
+ * The project-relative folder the app owns outright, ignored by git and by
+ * the project watcher. Earlier versions copied the authoring docs into it;
+ * the docs now live in the app's MCP server.
*/
const APP_DIR = ".diffusion";
-/** Repo housekeeping that has no business in a project's copy of the docs. */
-const DOCS_SKIP = new Set(["tsconfig.json", ".DS_Store"]);
-
-/**
- * Where the shipped docs come from: staged app resources when packaged (see
- * scripts/stage-docs.mjs), the repo checkout in development. Both lay the
- * tree out as the repo does — `reference/` beside `examples/` — so the
- * relative links between the pages keep resolving after the copy.
- */
-function docsSources(): string {
- return app.isPackaged ? join(process.resourcesPath, "docs") : join(app.getAppPath(), "..", "..");
-}
-
-/**
- * Copies the authoring reference and examples into `.diffusion/docs`, stamped
- * with the app version and refreshed whenever the stamp stops matching. Docs
- * that outlive the app they sit next to would lie about it, so unlike the
- * rest of the scaffold this is rewritten, not written once. The stamp only
- * moves with a release; in development a refresh is forced by deleting the
- * folder. This runs on every compile, so the up-to-date case is one read.
- */
-async function syncDocs(dir: string): Promise<void> {
- const docsDir = join(dir, APP_DIR, "docs");
- const stampFile = join(docsDir, ".version");
- const version = app.getVersion();
- try {
- if ((await readFile(stampFile, "utf8")).trim() === version) return;
- } catch {
- // No stamp: never synced, or a copy that did not finish. Full copy below.
- }
- const source = docsSources();
- await rm(docsDir, { recursive: true, force: true });
- await mkdir(docsDir, { recursive: true });
- for (const name of ["reference", "examples"]) {
- const src = join(source, name);
- if (!(await exists(src))) continue;
- await cp(src, join(docsDir, name), {
- recursive: true,
- filter: (path) => !DOCS_SKIP.has(basename(path)),
- });
- }
- // Written last, so a copy that died refuses to pass for a synced one.
- await writeFile(stampFile, version + "\n", "utf8");
-}
-
async function writeIfMissing(dir: string, name: string, content: string): Promise<void> {
const path = join(dir, name);
if (await exists(path)) return;
@@ -822,15 +734,7 @@ export async function scaffold(dir: string, displayName = basename(dir)): Promis
await writeIfMissing(dir, "tsconfig.json", TSCONFIG);
await writeIfMissing(dir, ".gitignore", GITIGNORE);
await writeIfMissing(dir, "README.md", readme(displayName));
- await writeIfMissing(dir, "AGENTS.md", AGENTS);
- // The docs are auxiliary: a project must still open and compile without
- // them, so a failed sync is a warning rather than a failed scaffold.
- try {
- await syncDocs(dir);
- } catch (error) {
- console.warn(`projects: could not sync the authoring docs into ${dir}`, error);
- }
if (!(await exists(join(dir, MANIFEST_FILE)))) {
await writeManifest(dir, EMPTY_MANIFEST);
diff --git a/apps/desktop/src/skills-install.ts b/apps/desktop/src/skills-install.ts
deleted file mode 100644
index c7cd4dd5..00000000
--- a/apps/desktop/src/skills-install.ts
+++ /dev/null
@@ -1,191 +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/. */
-
-import { app } from "electron";
-import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import type { SkillsInstallResult } from "./main-channels";
-
-const AGENT_SKILLS_DIRS = [
- ".adal/skills",
- ".agents/skills",
- ".aider-desk/skills",
- ".astrbot/data/skills",
- ".augment/skills",
- ".autohand/skills",
- ".bob/skills",
- ".claude/skills",
- ".clawdbot/skills",
- ".codeartsdoer/skills",
- ".codebuddy/skills",
- ".codeium/windsurf/skills",
- ".codemaker/skills",
- ".codestudio/skills",
- ".codex/skills",
- ".commandcode/skills",
- ".config/agents/skills",
- ".config/crush/skills",
- ".config/devin/skills",
- ".config/goose/skills",
- ".config/kimchi/harness/skills",
- ".config/opencode/skills",
- ".continue/skills",
- ".copilot/skills",
- ".cursor/skills",
- ".deepagents/agent/skills",
- ".factory/skills",
- ".firebender/skills",
- ".forge/skills",
- ".gemini/antigravity-cli/skills",
- ".gemini/antigravity/skills",
- ".gemini/skills",
- ".grok/skills",
- ".hermes/skills",
- ".iflow/skills",
- ".inferencesh/skills",
- ".jazz/skills",
- ".junie/skills",
- ".kilocode/skills",
- ".kiro/skills",
- ".kode/skills",
- ".lingma/skills",
- ".mcpjam/skills",
- ".minimax/skills",
- ".moltbot/skills",
- ".moxby/skills",
- ".mux/skills",
- ".neovate/skills",
- ".ona/skills",
- ".openclaw/skills",
- ".openhands/skills",
- ".pi/agent/skills",
- ".pochi/skills",
- ".posit/assistant/skills",
- ".qoder-cn/skills",
- ".qoder/skills",
- ".qwen/skills",
- ".reasonix/skills",
- ".roo/skills",
- ".rovodev/skills",
- ".snowflake/cortex/skills",
- ".tabnine/agent/skills",
- ".terramind/skills",
- ".tinycloud/skills",
- ".trae-cn/skills",
- ".trae/skills",
- ".vibe/skills",
- ".zcode/skills",
- ".zencoder/skills",
-];
-
-const FALLBACK_AGENT_DIR = ".claude/skills";
-
-function stagedSkillsDir(): string {
- return app.isPackaged
- ? join(process.resourcesPath, "skills")
- : join(app.getAppPath(), "skills");
-}
-
-function stagedSkillNames(): string[] {
- const dir = stagedSkillsDir();
- if (!existsSync(dir)) return [];
- return readdirSync(dir, { withFileTypes: true })
- .filter((entry) => entry.isDirectory())
- .map((entry) => entry.name);
-}
-
-// Agents whose config dir exists on this machine, falling back to Claude Code
-// so a machine with no agent yet still gets set up for the primary one.
-function targetAgentDirs(): string[] {
- const home = homedir();
- const present = AGENT_SKILLS_DIRS.filter((dir) => existsSync(join(home, dirname(dir))));
- return (present.length > 0 ? present : [FALLBACK_AGENT_DIR]).map((dir) => join(home, dir));
-}
-
-// `existsSync` follows symlinks, so a dangling link doesn't count.
-export function isSkillsInstalled(): boolean {
- const home = homedir();
- const marker = stagedSkillNames()[0] ?? "editor";
- return AGENT_SKILLS_DIRS.some((dir) => existsSync(join(home, dir, marker, "SKILL.md")));
-}
-
-// ln -sf semantics that never clobber real files: an existing symlink is
-// repointed (ours or the skills CLI's — the user asked to install), but a
-// real directory (a `skills add --copy` install) is left alone.
-function linkSkill(linkPath: string, target: string): void {
- try {
- if (!lstatSync(linkPath).isSymbolicLink()) return;
- rmSync(linkPath);
- } catch {
- // nothing at linkPath
- }
- symlinkSync(target, linkPath);
-}
-
-export function installSkills(): SkillsInstallResult {
- const source = stagedSkillsDir();
- // A quarantined first launch runs from a translocated read-only mount whose
- // path won't survive the next launch — linking to it would dangle.
- if (source.includes("/AppTranslocation/")) {
- return {
- status: "error",
- error: "Move Diffusion Studio to the Applications folder and relaunch it, then try again.",
- };
- }
- const skills = stagedSkillNames();
- if (skills.length === 0) {
- return {
- status: "error",
- error: app.isPackaged
- ? "The app bundle is missing its skills resources."
- : "Skills are not staged — run `npm run stage:skills` in apps/desktop.",
- };
- }
- try {
- for (const agentDir of targetAgentDirs()) {
- mkdirSync(agentDir, { recursive: true });
- for (const name of skills) {
- linkSkill(join(agentDir, name), join(source, name));
- }
- }
- return { status: "installed" };
- } catch (e) {
- return { status: "error", error: (e as Error).message };
- }
-}
-
-/**
- * Launch-time self-heal: links created by installSkills break when the app
- * moves or was translocated when they were made. Any symlink that targets a
- * Diffusion Studio bundle but not the running app's resources is repointed.
- * Links owned by the skills CLI and copied installs are left alone.
- */
-export function healSkillsLinks(): void {
- if (!app.isPackaged) return;
- const source = stagedSkillsDir();
- if (source.includes("/AppTranslocation/")) return;
-
- const home = homedir();
- for (const dir of AGENT_SKILLS_DIRS) {
- for (const name of stagedSkillNames()) {
- const linkPath = join(home, dir, name);
- let target: string;
- try {
- target = readlinkSync(linkPath);
- } catch {
- continue; // missing, or not a symlink
- }
- const ours = target.includes("Diffusion Studio") || target.includes("/AppTranslocation/");
- const current = join(source, name);
- if (!ours || target === current) continue;
- try {
- rmSync(linkPath);
- symlinkSync(current, linkPath);
- } catch {
- // best effort — the install button remains as a manual fix
- }
- }
- }
-}
diff --git a/apps/web/package.json b/apps/web/package.json
index 619eba2a..929f6a3d 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -15,7 +15,6 @@
"dependencies": {
"@diffusionstudio/api-contract": "^0.1.0",
"@diffusionstudio/assets": "*",
- "@diffusionstudio/cli": "*",
"@diffusionstudio/encoder": "*",
"@diffusionstudio/jsx": "*",
"@diffusionstudio/koota-solid": "*",
@@ -42,7 +41,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/app.tsx b/apps/web/src/app.tsx
index bb490a29..a57cf178 100644
--- a/apps/web/src/app.tsx
+++ b/apps/web/src/app.tsx
@@ -10,14 +10,13 @@ import { AppContextMenu } from "@/components/app-context-menu";
import { AuthProvider, useAuth } from '@/context/auth';
import { PersistRoute } from '@/lib/persist-route';
-import { EditorApi } from '@/context/dapi';
+import { EditorApi } from '@/dapi';
import { UpgradeDialog } from '@/components/upgrade-dialog';
import { PurchaseSuccess } from '@/components/purchase-success';
import { ScreenTooSmall } from '@/components/screen-too-small';
import { UnsupportedBrowser } from '@/components/unsupported-browser';
import { ProjectPage } from '@/pages/project';
import { LoginPage } from '@/pages/login';
-import { OnboardingPage, onboardingCompleted } from '@/pages/onboarding';
import { AuthCallbackPage } from '@/pages/auth-callback';
import { NotFoundPage } from '@/pages/not-found';
import { DashboardPage } from '@/pages/dashboard';
@@ -28,12 +27,7 @@ function AuthGate(props: { children: JSX.Element }) {
return (
<Show when={!auth.isLoading()}>
<Show when={auth.isAuthenticated() || auth.headless()}>
- <Show
- when={onboardingCompleted() || auth.headless()}
- fallback={<OnboardingPage />}
- >
- {props.children}
- </Show>
+ {props.children}
</Show>
<Show when={!auth.isAuthenticated()}>
<LoginPage />
diff --git a/apps/web/src/components/canvas/desktop-app-banner.tsx b/apps/web/src/components/canvas/desktop-app-banner.tsx
index c1637fc1..5db091c6 100644
--- a/apps/web/src/components/canvas/desktop-app-banner.tsx
+++ b/apps/web/src/components/canvas/desktop-app-banner.tsx
@@ -5,7 +5,7 @@
import { Show } from "solid-js";
import { Button } from "@/components/ui/button";
import { Icon } from "@/components/ui/icon";
-import { useEditorApi } from "@/context/dapi";
+import { useEditorApi } from "@/dapi";
import { createStoredSignal } from "@/lib/store";
import { downloadDesktopApp } from "@/lib/desktop-app";
import { track } from "@/lib/analytics";
diff --git a/apps/web/src/components/sidebar-left/project-menu/index.tsx b/apps/web/src/components/sidebar-left/project-menu/index.tsx
index 2d2735a5..d9838de6 100644
--- a/apps/web/src/components/sidebar-left/project-menu/index.tsx
+++ b/apps/web/src/components/sidebar-left/project-menu/index.tsx
@@ -19,7 +19,7 @@ import {
import { useNavigate } from "@solidjs/router";
import { Show, onCleanup, onMount } from "solid-js";
import { isInputTarget } from "@/utils";
-import { useEditorApi } from "@/context/dapi";
+import { useEditorApi } from "@/dapi";
import { downloadDesktopApp } from "@/lib/desktop-app";
import { FileMenu } from "./file-menu";
import { EditMenu } from "./edit-menu";
diff --git a/apps/web/src/components/sidebar-left/sidebar-left.tsx b/apps/web/src/components/sidebar-left/sidebar-left.tsx
index a179fce4..b71c9db2 100644
--- a/apps/web/src/components/sidebar-left/sidebar-left.tsx
+++ b/apps/web/src/components/sidebar-left/sidebar-left.tsx
@@ -4,7 +4,7 @@
import { Assets } from "./assets";
import { useLayout } from "@/context/layout";
-import { useEditorApi } from "@/context/dapi";
+import { useEditorApi } from "@/dapi";
import { createSignal, Show } from "solid-js";
import { toast } from "somoto";
import { Button } from "../ui/button";
diff --git a/apps/web/src/context/dapi/api.tsx b/apps/web/src/context/dapi/api.tsx
deleted file mode 100644
index 1619cf04..00000000
--- a/apps/web/src/context/dapi/api.tsx
+++ /dev/null
@@ -1,145 +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/. */
-
-import { createEffect, createContext, useContext, onCleanup } from "solid-js";
-import { useNavigate } from "@solidjs/router";
-import { useWorld } from '@diffusionstudio/koota-solid';
-import { Project } from '@diffusionstudio/runtime';
-import { useProject } from '@/context/project';
-import { useAuth } from '@/context/auth';
-import { useEngineContext } from '@/engine';
-import { t, q, q0, m } from "@/lib/cli-rpc";
-import { editorSession, requireEditorSession, setEditorSession } from "./session";
-import { handleContextGet } from "./context";
-import { createAssetResolver, handleMediaProbe, handleMediaFrame, handleMediaTranscribe, handleMediaFilmstrip, handleMediaWaveform, handleMediaListen } from "./media";
-import { handleCapture } from "./capture";
-import { handleCheck } from "./check";
-import { handleExport } from "./export";
-import { handleLogs } from "./logs";
-import { handleModels } from "./models";
-import { handleVoices } from "./voices";
-import { cliBridge } from '@/lib/ipc';
-import { createRouterCaller } from '@/lib/cli-rpc';
-import { openProjectFolder } from '@/projects';
-import { projectRoute } from '@/hooks/use-project-route';
-import { assert } from "@/utils/common";
-import { handleWindowScreenshot } from "./window";
-import { useFullscreenState } from "@/hooks/use-fullscreen-state";
-
-import type { JSX, Accessor } from 'solid-js';
-import type { Navigator } from '@solidjs/router';
-import type { User } from '@supabase/supabase-js';
-
-type EditorApiProviderProps = {
- children: JSX.Element;
-};
-
-type EditorApiContextValue = {
- isFullscreen: Accessor<boolean>;
- isDesktop: boolean;
-};
-
-const EditorApiContext = createContext<EditorApiContextValue>();
-
-/**
- * The one CLI router, registered for as long as the app runs. Every endpoint
- * is reachable whether or not a project is open; the ones that need one read
- * the session slot (see ./session) per request and fail with a clear error —
- * or, for `context`, report that nothing is open. Renders nothing; must sit
- * inside the router tree for `useNavigate` and inside the auth provider.
- */
-export function EditorApi() {
- const navigate = useNavigate();
- const auth = useAuth();
-
- const requireAuth = <I, O>(fn: (data: I) => Promise<O>) => (data: I) => {
- assert(auth.isAuthenticated(), "Sign in required: AI generation needs a Diffusion Studio account.");
- return fn(data);
- };
-
- const getUser = () => {
- const user = auth.user();
- assert(user, "User not found");
- return user;
- };
-
- const router = createAppRouter({ navigate, getUser, requireAuth });
- onCleanup(cliBridge.register(createRouterCaller(router)));
- return null;
-}
-
-/**
- * Publishes the editor session for the CLI router while the project is open,
- * and provides the editor UI's own view of the app shell (fullscreen state,
- * desktop-ness). Mounted per project page.
- */
-export function EditorApiProvider(props: EditorApiProviderProps) {
- const project = useProject();
- const isFullscreen = useFullscreenState();
- const world = useWorld();
- const engine = useEngineContext();
-
- createEffect(() => {
- if (!window.desktop || project.id() !== world.get(Project)?.id) return;
-
- setEditorSession({ world, project, engine });
- onCleanup(() => setEditorSession(null));
- });
-
- return (
- <EditorApiContext.Provider
- value={{
- isFullscreen,
- isDesktop: !!window.desktop,
- }}
- >
- {props.children}
- </EditorApiContext.Provider>
- );
-}
-
-
-type AppRouterDeps = {
- navigate: Navigator;
- getUser: () => User;
- requireAuth: <I, O>(fn: (data: I) => Promise<O>) => (data: I) => Promise<O>;
-};
-
-function createAppRouter({ navigate, getUser, requireAuth }: AppRouterDeps) {
- const resolveAsset = createAssetResolver(editorSession);
-
- return t.router({
- ping: t.procedure.query(() => {}),
- open: m(async ({ dir }: { dir: string }) => {
- const project = await openProjectFolder(dir);
- navigate(projectRoute(project.id || project.name));
- return { id: project.id, name: project.displayName, dir: project.dir };
- }),
- whoami: t.procedure.query(() => getUser()),
- context: q0(handleContextGet(editorSession)),
- capture: q(handleCapture(requireEditorSession)),
- check: q(handleCheck(requireEditorSession)),
- export: m(handleExport(requireEditorSession)),
- models: q(handleModels()),
- logs: q(handleLogs()),
- screenshot: q0(handleWindowScreenshot()),
- voices: q0(handleVoices()),
- media: t.router({
- probe: q(handleMediaProbe(resolveAsset)),
- frame: q(handleMediaFrame(resolveAsset)),
- transcribe: q(handleMediaTranscribe(resolveAsset)),
- filmstrip: q(handleMediaFilmstrip(resolveAsset)),
- waveform: q(handleMediaWaveform(resolveAsset)),
- listen: q(requireAuth(handleMediaListen(resolveAsset, editorSession))),
- }),
- });
-}
-
-export type AppRouter = ReturnType<typeof createAppRouter>;
-
-export function useEditorApi() {
- const ctx = useContext(EditorApiContext);
- assert(ctx, "useEditorApi must be used within EditorApiProvider");
- return ctx;
-}
diff --git a/apps/web/src/context/dapi/capture.ts b/apps/web/src/context/dapi/capture.ts
deleted file mode 100644
index 28034ae0..00000000
--- a/apps/web/src/context/dapi/capture.ts
+++ /dev/null
@@ -1,102 +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/. */
-
-import {
- composeSheet,
- createImageEncoder,
- decodePngBase64,
- planSheet,
- planSheetSizes,
- sheetTimecode,
-} from "@diffusionstudio/encoder";
-
-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 { EditorSession } from "./session";
-
-// Ceiling on the height a sheet cell renders a node at.
-const SHEET_CAPTURE_HEIGHT = 1080;
-
-export function handleCapture(session: () => EditorSession) {
- return async ({ id, frames, combine = true, perSheet }: CaptureRequest): Promise<CaptureResult> => {
- const { world, project } = session();
- const node = resolveNode(world, id);
-
- // Scenes only: a capture's promise is that its frames are the frames an
- // export encodes, and a scene is the unit an export renders — framing an
- // arbitrary node would need its bounds measured across the requested
- // positions first, and that pre-roll runs the project's code ahead of the
- // frames being drawn, which is exactly what an export never does.
- if (!isScene(node)) {
- let scene = getParentNode(node);
- while (scene !== null && !isScene(scene)) scene = getParentNode(scene);
- const stamp = scene?.get(Source)?.value;
- throw new Error(
- stamp
- ? `"${id}" is not a scene — capture renders what an export renders. Capture its scene "${stamp}" instead.`
- : `"${id}" is not a scene — capture renders what an export renders, so it takes a scene id.`,
- );
- }
-
- // `undefined` means the export's first frame (the workarea's start).
- let shots = frames;
- if (shots === undefined || shots.length === 0) {
- shots = [0];
- }
-
- // The project re-rendered into a world of its own, reduced to this scene:
- // the same arrangement an export runs against, and the encoder's to draw.
- const capture = await createCapture(world, node, { dir: project.dir() });
-
- try {
- const encoder = await createImageEncoder(capture.world, {
- frames: shots,
- resolution: 720,
- });
-
- // Sheets render at their cell size instead of the flat 720p: with a few
- // frames that is sharper than a standalone capture, never coarser. A
- // scene is drawn, not decoded, so a small one is worth rendering past
- // its own size; beyond SHEET_CAPTURE_HEIGHT that only costs tokens.
- const aspect = encoder.bounds.width / encoder.bounds.height;
- const height = Math.max(encoder.bounds.height, SHEET_CAPTURE_HEIGHT);
- const sizes = combine ? planSheetSizes(shots.length, perSheet) : [];
- const plans = sizes.map((n) => planSheet(n, { width: height * aspect, height }));
- if (combine) {
- encoder.resize(Math.max(...plans.map((plan) => plan.cellHeight)));
- }
-
- const result = await encoder.render();
-
- if (result.type === "canceled") throw new Error("Capture canceled");
- if (result.type === "error") throw result.error;
-
- if (!combine) return result.data;
-
- const sheets: TimecodedImage[] = [];
- let offset = 0;
- for (const [sheet, size] of sizes.entries()) {
- const group = result.data.slice(offset, offset + size);
- const cells = group.map(({ timecode }, k) => ({ at: shots[offset + k], timecode }));
- offset += size;
- const images = await Promise.all(group.map((image) => decodePngBase64(image.base64)));
- sheets.push({
- timecode: sheetTimecode(cells),
- base64: await composeSheet(
- images.map((image, k) => ({ image, label: group[k].timecode })),
- plans[sheet],
- ),
- });
- for (const image of images) image.close();
- }
- return sheets;
- } finally {
- capture.dispose();
- }
- };
-}
diff --git a/apps/web/src/context/dapi/context.ts b/apps/web/src/context/dapi/context.ts
deleted file mode 100644
index 1f6a7bb8..00000000
--- a/apps/web/src/context/dapi/context.ts
+++ /dev/null
@@ -1,99 +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/. */
-
-import { AssetId, Computed, Fonts, FrameRate, Generating, getActiveEntity, Library, Name, PendingSource, Source, SourceError } from "@diffusionstudio/runtime";
-
-import { getProjectsRoot } from "@/projects";
-
-import type { Accessor } from "solid-js";
-import type { Entity, World } from "koota";
-import type { EditorSession } from "./session";
-
-/**
- * What `dapi context` reports: what the project's source cannot say. The JSX is
- * the composition — its scenes, what is selected, which scene is active, the
- * work area are all in the file, and a caller that wants them reads it. What is
- * left over is which folder projects live under, which project folder the app
- * has open, where its playhead sits, which font families are actually
- * registered in the world drawing it. With no project open only the root is
- * left to report, and the report says so.
- */
-export function handleContextGet(session: Accessor<EditorSession | null>) {
- return async () => {
- const rootDir = await getProjectsRoot();
-
- const open = session();
- if (!open) return { rootDir, projectDir: null };
-
- const { world, project } = open;
- const frameRate = world.get(FrameRate)?.value || 30;
- const active = getActiveEntity(world);
-
- return {
- rootDir,
- projectDir: project.dir(),
- // Seconds, the unit the source places clips in; null when no scene is
- // active, which is when there is no playhead to report.
- currentTime: active ? (active.get(Computed)?.localTime ?? 0) / frameRate : null,
- // What text can be drawn with right now: registered in the world, not
- // merely named in the source. The editor default is always among them.
- fontFamilies: [...new Set(["Inter", ...(world.get(Fonts)?.list ?? []).map((f) => f.family)])],
- generations: collectGenerations(world),
- };
- }
-}
-
-type GenerationRow = {
- /** The element's source stamp, `<file>:<key or position>`; null for an
- * entity no element produced. */
- element: string | null;
- name: string | null;
- state: "generating" | "failed" | "done";
- /** What the generation failed with, on `failed` rows. */
- error?: string;
- /** The library path the generation landed as, on `done` rows — ready for
- * `dapi media probe` and its siblings. */
- asset?: string;
-};
-
-function collectGenerations(world: World): GenerationRow[] {
- const library = world.get(Library);
- const rows: GenerationRow[] = [];
- const seen = new Set<string>();
-
- const push = (row: GenerationRow) => {
- const key = JSON.stringify(row);
- if (seen.has(key)) return;
- seen.add(key);
- rows.push(row);
- };
-
- for (const entity of world.query(Generating)) {
- push({ ...describeElement(entity), state: "generating" });
- }
-
- for (const entity of world.query(SourceError)) {
- const failure = entity.get(SourceError)!;
- if (!failure.generated) continue;
- push({ ...describeElement(entity), state: "failed", error: failure.value });
- }
-
- for (const entity of world.query(AssetId)) {
- // A stale binding — the element is off generating a new answer or failed
- // getting one — is not a generation that is done.
- if (entity.has(Generating) || entity.has(PendingSource) || entity.has(SourceError)) continue;
- const asset = library?.get(entity.get(AssetId)!.value);
- if (!asset?.generation) continue;
- push({ ...describeElement(entity), state: "done", asset: asset.path });
- }
-
- return rows;
-}
-
-function describeElement(entity: Entity): Pick<GenerationRow, "element" | "name"> {
- return {
- element: entity.get(Source)?.value || null,
- name: entity.get(Name)?.value || null,
- };
-}
diff --git a/apps/web/src/context/dapi/export.ts b/apps/web/src/context/dapi/export.ts
deleted file mode 100644
index a2a6536e..00000000
--- a/apps/web/src/context/dapi/export.ts
+++ /dev/null
@@ -1,141 +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/. */
-
-import { canEncodeVideo } from "mediabunny";
-import { computeOutputSize } from "@diffusionstudio/encoder";
-import { Computed, FrameRate, getParentNode, isScene, Source, Workarea } from "@diffusionstudio/runtime";
-
-import { renderOverlay, renderScene } from "@/context/render";
-import { ElectronWritableFileHandle } from "@/lib/electron-file-writable";
-import { ProjectConfig as ProjectConfigTrait } from "@/engine/traits";
-import { sceneConfigKey } from "@/engine/project-config";
-import {
- getDefaultExportTemplate,
- VIDEO_FORMAT_OPTIONS,
-} from "@/components/sidebar-right/inspector/export-templates";
-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 { ContainerFormat, ExportConfig } from "@/engine/project-config";
-import type { EditorSession } from "./session";
-
-/**
- * The container the export writes: the output extension when a path was
- * given (ffmpeg's rule — the file must be what its name says), the config's
- * format otherwise, mp4 when neither says. A given path settles it entirely,
- * so a bad config format only fails an export that would actually use it.
- */
-function resolveFormat(path: string | undefined, config: ExportConfig): ContainerFormat {
- const supported = VIDEO_FORMAT_OPTIONS.map((format) => `.${format}`).join(", ");
- if (path !== undefined) {
- const extension = /\.([a-z0-9]+)$/i.exec(path)?.[1]?.toLowerCase();
- if (!extension || !VIDEO_FORMAT_OPTIONS.includes(extension as ContainerFormat)) {
- throw new Error(`The output path must end in a container extension: ${supported}.`);
- }
- return extension as ContainerFormat;
- }
- const format = config.format ?? "mp4";
- if (!VIDEO_FORMAT_OPTIONS.includes(format)) {
- throw new Error(`The export entry names an unknown format "${format}" — use one of ${supported.replaceAll(".", "")}.`);
- }
- return format;
-}
-
-export function handleExport(session: () => EditorSession) {
- return async ({ id, path }: ExportRequest): Promise<ExportResult> => {
- const { world, project, engine } = session();
-
- const scene = resolveNode(world, id);
- if (!isScene(scene)) {
- let parent = getParentNode(scene);
- while (parent !== null && !isScene(parent)) parent = getParentNode(parent);
- const stamp = parent?.get(Source)?.value;
- throw new Error(
- stamp
- ? `"${id}" is not a scene — a scene is the unit an export renders. Export its scene "${stamp}" instead.`
- : `"${id}" is not a scene — a scene is the unit an export renders, so export takes a scene id.`,
- );
- }
-
- // The scene's entry in the project's package.json (`diffusion.export.<id>`)
- // — the same one the app's export panel writes — so a CLI export
- // reproduces the in-app one; a scene without an entry uses the default
- // template, the way ⌘E does. `template` is only the preset's label.
- const base = world.get(ProjectConfigTrait)?.exportOf(scene) ?? getDefaultExportTemplate();
- const settings: ExportConfig = { format: base.format, video: base.video, audio: base.audio };
-
- const format = resolveFormat(path, settings);
- const key = sceneConfigKey(scene) ?? id;
- const target = path ?? `${project.dir()}/exports/${key.replace(/[^\w.-]+/g, "-")}.${format}`;
-
- // Fail before the render machinery spins up: an unencodable configuration
- // is known right away (same precheck the UI export runs).
- const videoEnabled = format !== "ogg" && settings.video?.enabled !== false;
- const computed = scene.get(Computed);
- const { width, height } = computeOutputSize(
- computed?.width || 1920,
- computed?.height || 1080,
- settings.video?.resolution ?? 1080,
- );
- if (videoEnabled) {
- const codec = settings.video?.codec ?? "avc";
- const encodable = await canEncodeVideo(codec, {
- width,
- height,
- bitrate: settings.video?.bitrate ?? 10e6,
- });
- if (!encodable) {
- throw new Error(
- `Cannot encode ${codec.toUpperCase()} at ${width}×${height}. ` +
- "Set a lower resolution, a lower bitrate, or another codec in the scene's export entry.",
- );
- }
- }
-
- const workarea = scene.get(Workarea);
- const frames = workarea ? workarea.end - workarea.start : computed?.duration ?? 0;
- const duration = frames / (world.get(FrameRate)?.value || 30);
-
- // renderScene owns the one render slot (it stops the live engine and
- // raises the progress overlay), so refuse a second export rather than
- // interleave. No await sits between this check and renderScene claiming
- // the overlay, so two racing requests cannot both pass.
- if (renderOverlay()) {
- throw new Error("An export is already running — wait for it to finish, or cancel it in the app.");
- }
-
- const handle = new ElectronWritableFileHandle(target);
- try {
- const result = await renderScene(engine, {
- scene,
- target: handle,
- config: { ...settings, format },
- dir: project.dir(),
- });
- if (result.type === "canceled") throw new Error("Export canceled in the app");
- if (result.type === "error") throw result.error;
- } catch (error) {
- // Close the fd and drop the partial file; a failed export leaves nothing.
- await handle.dispose().catch(() => {});
- throw error;
- }
-
- const stat = await mainBridge.call(MAIN_CHANNELS.PROJECTS_FS_STAT, {
- dir: project.dir(),
- source: target,
- });
-
- const config: ExportSettings = { format, video: settings.video, audio: settings.audio };
- return {
- path: target,
- width: videoEnabled ? width : 0,
- height: videoEnabled ? height : 0,
- duration,
- size: stat?.size ?? 0,
- config,
- };
- };
-}
diff --git a/apps/web/src/context/dapi/logs.ts b/apps/web/src/context/dapi/logs.ts
deleted file mode 100644
index e70d29e5..00000000
--- a/apps/web/src/context/dapi/logs.ts
+++ /dev/null
@@ -1,21 +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/. */
-
-import { mainBridge } from "@/lib/ipc";
-import { MAIN_CHANNELS } from "@desktop/main-channels";
-import type { LogsRequest, LogLevel } from "@diffusionstudio/cli/channels";
-
-const LEVEL_RANK: Record<LogLevel, number> = { debug: 0, info: 1, warning: 2, error: 3 };
-
-export function handleLogs() {
- return async (req: LogsRequest) => {
- let entries = await mainBridge.call(MAIN_CHANNELS.LOGS_GET, undefined);
- if (req.level !== undefined) {
- const min = LEVEL_RANK[req.level];
- entries = entries.filter((e) => LEVEL_RANK[e.level] >= min);
- }
- if (req.tail !== undefined) entries = entries.slice(-req.tail);
- return entries;
- };
-}
diff --git a/apps/web/src/context/dapi/media.ts b/apps/web/src/context/dapi/media.ts
deleted file mode 100644
index 74cab872..00000000
--- a/apps/web/src/context/dapi/media.ts
+++ /dev/null
@@ -1,361 +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/. */
-
-import { ALL_FORMATS, BlobSource, CanvasSink, Input } from 'mediabunny';
-import { pickInformativeTimes } from './frame-triage';
-import { trpc } from '@/lib/trpc';
-import { uploadBlob } from '@/lib/uploads';
-import { composeSheet, planSheet, planSheetSizes, sheetTimecode } from '@diffusionstudio/encoder';
-import { assert } from '@/utils';
-import { startResumableSession, uploadResumableStream } from '@/lib/uploads';
-import { filmstripAsset, formatTimecode, getAssetFile, getLibrary, Project, transcodeForAnalysis, transcodeForTranscription, waveformAsset } from '@diffusionstudio/runtime';
-import { AssetLibrary, assetName, isAbsoluteSource, isUrlSource } from '@diffusionstudio/assets';
-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";
-
-type ResolveAsset = (path: string) => Promise<Asset>;
-
-/**
- * Resolves a command target by path. With a project open, its library answers:
- * library paths look assets up, absolute paths and URLs are described in place
- * without being added (transient assets). With none open, a throwaway library
- * over a project-less FS describes absolute paths and URLs the same way — a
- * fresh one per request, so nothing is remembered between calls.
- */
-export function createAssetResolver(session: Accessor<EditorSession | null>): ResolveAsset {
- return (path) => {
- const world = session()?.world;
- if (world) return getLibrary(world).resolve(path);
- assert(
- isAbsoluteSource(path) || isUrlSource(path),
- `Could not resolve "${path}": with no project open only absolute paths and URLs resolve — run \`dapi open <dir>\` to use library paths.`,
- );
- return new AssetLibrary(createProjectFS("")).resolve(path);
- };
-}
-
-const PROBE_SAMPLE_PACKETS = 200;
-
-export function handleMediaProbe(resolve: ResolveAsset) {
- return async (req: MediaProbeRequest): Promise<unknown> => {
- const asset = await resolve(req.path);
-
- const blob = await getAssetFile(asset);
- const base = {
- id: asset.id,
- name: assetName(asset),
- path: asset.path,
- type: asset.type,
- mimeType: asset.mimeType,
- size: blob.size,
- ...("width" in asset && { width: asset.width, height: asset.height }),
- };
-
- const input = new Input({ formats: ALL_FORMATS, source: new BlobSource(blob) });
- try {
- const format = await input.getFormat();
- const mimeType = await input.getMimeType();
- const duration = await input.computeDuration();
- const { images, ...tags } = await input.getMetadataTags();
- delete tags.raw;
-
- const tracks: Array<Record<string, unknown>> = [];
- for (const track of await input.getTracks()) {
- const stats = await track.computePacketStats(PROBE_SAMPLE_PACKETS);
- tracks.push({
- id: track.id,
- type: track.type,
- codec: track.codec,
- language: track.languageCode,
- firstTimestamp: await track.getFirstTimestamp(),
- duration: await track.computeDuration(),
- ...stats,
- ...(track.isVideoTrack() && {
- codedWidth: track.codedWidth,
- codedHeight: track.codedHeight,
- displayWidth: track.displayWidth,
- displayHeight: track.displayHeight,
- rotation: track.rotation,
- }),
- ...(track.isAudioTrack() && {
- sampleRate: track.sampleRate,
- channels: track.numberOfChannels,
- }),
- });
- }
-
- return {
- ...base,
- format: format.name,
- mimeType,
- duration,
- tags: { ...tags, ...(images?.length && { attachedImages: images.length }) },
- tracks,
- };
- } catch {
- return { ...base, format: null, tracks: [] };
- } finally {
- input.dispose();
- }
- };
-}
-
-// Named quality presets mapped to a per-frame total-pixel budget (aspect ratio
-// preserved). A budget of 0 means native resolution. `small` keeps frames small
-// enough for vision models and is the default.
-const FRAME_QUALITY_BUDGETS = {
- small: 384 * 384, // 147,456
- medium: 768 * 768, // 589,824
- large: 1536 * 1536, // 2,359,296
- fullres: 0, // native
-} as const;
-
-// Default cap on frames returned by auto selection when `count` is not given.
-const AUTO_MAX_FRAMES = 30;
-
-export function handleMediaFrame(resolve: ResolveAsset) {
- return async (req: MediaFrameRequest): Promise<MediaFrameResult> => {
- const { times, count, start, end, quality, auto } = req;
- const combine = req.combine ?? true;
- const asset = await resolve(req.path);
- const id = asset.id;
- assert(asset.type === "VIDEO", `Asset ${id} is not a video.`);
-
- // `count` samples evenly across a window (default the whole clip); `auto`
- // scans the window and keeps frames where the footage settles into a new
- // visual state, capped at `count` (resolved once the track is open).
- // Otherwise grab the explicit `times` (falling back to a single frame at 0).
- const from = Math.min(Math.max(start ?? 0, 0), asset.duration);
- const to = Math.min(Math.max(end ?? asset.duration, from), asset.duration);
- let requested: number[] = [];
- if (auto || count !== undefined) {
- assert(to > from, `The requested window is empty; start (${from.toFixed(2)}s) is at or past end (${to.toFixed(2)}s).`);
- if (!auto && count !== undefined) {
- const interval = (to - from) / count;
- requested = Array.from({ length: count }, (_, i) => from + i * interval);
- }
- } else {
- const raw = times && times.length ? times : [0];
- // A negative time is an offset back from the end of the clip: -1 is one
- // second before the end, -1f one frame before it.
- requested = raw.map((t) => {
- if (t >= 0) {
- assert(t <= asset.duration, `--time ${t}s is past the asset's duration (${asset.duration.toFixed(2)}s).`);
- return t;
- }
- const resolved = asset.duration + t;
- assert(resolved >= 0, `--time ${t} counts past the start of the clip (duration ${asset.duration.toFixed(2)}s).`);
- return resolved;
- });
- }
-
- const budget = FRAME_QUALITY_BUDGETS[quality ?? (combine ? "fullres" : "small")];
-
- const blob = await getAssetFile(asset);
- const input = new Input({ formats: ALL_FORMATS, source: new BlobSource(blob) });
- try {
- const track = await input.getPrimaryVideoTrack();
- assert(track, `Asset ${id} has no video track.`);
-
- // Track timestamps may not start at 0; offset content time by the first.
- const firstTimestamp = (await track.getFirstTimestamp()) ?? 0;
-
- if (auto) {
- const picked = await pickInformativeTimes(track, {
- from: firstTimestamp + from,
- to: firstTimestamp + to,
- max: count ?? AUTO_MAX_FRAMES,
- });
- requested = picked.map((t) => Math.max(0, t - firstTimestamp));
- }
-
- // Downscale to fit the pixel budget while preserving aspect ratio; setting
- // only the width lets the sink derive a matching height.
- const displayWidth = await track.getDisplayWidth();
- const displayHeight = await track.getDisplayHeight();
- let sourceWidth = displayWidth;
- let sourceHeight = displayHeight;
- if (budget > 0 && displayWidth * displayHeight > budget) {
- const scale = Math.sqrt(budget / (displayWidth * displayHeight));
- sourceWidth = Math.max(1, Math.round(displayWidth * scale));
- sourceHeight = Math.max(1, Math.round(displayHeight * scale));
- }
-
- // Lay the sheets out up front: the largest cell across them sets the
- // decode size, so no frame is decoded bigger than it will be drawn.
- const sizes = combine ? planSheetSizes(requested.length, req.perSheet) : [];
- const plans = sizes.map((n) => planSheet(n, { width: sourceWidth, height: sourceHeight }));
- const width = combine
- ? Math.min(sourceWidth, Math.max(...plans.map((plan) => plan.cellWidth)))
- : sourceWidth;
-
- // Decode in ascending order (the sink's fast path), remember each
- // entry's original slot so output mirrors the requested order.
- const ordered = requested.map((time, index) => ({ time, index })).sort((a, b) => a.time - b.time);
-
- // No pool: each yielded canvas is fresh, so converting to PNG can't race
- // the generator's read-ahead reusing a pooled canvas.
- const sink = new CanvasSink(track, width < displayWidth ? { width } : undefined);
- const timestamps = ordered.map(({ time }) => firstTimestamp + time);
-
- // Which sheet each frame belongs to, and where that sheet starts.
- const sheetOf: number[] = [];
- const sheetStart: number[] = [];
- for (const [sheet, size] of sizes.entries()) {
- sheetStart.push(sheetOf.length);
- for (let k = 0; k < size; k++) sheetOf.push(sheet);
- }
- const missing = [...sizes];
-
- const cells: Array<{ at: number; timecode: string }> = new Array(requested.length);
- const canvases: Array<CanvasImageSource | undefined> = new Array(requested.length);
- const result: TimecodedImage[] = new Array(combine ? sizes.length : requested.length);
-
- let i = 0;
- for await (const wrapped of sink.canvasesAtTimestamps(timestamps)) {
- const { time, index } = ordered[i++];
- assert(wrapped, `No frame found at ${time}s.`);
- const timecode = formatTimecode(time, asset.frameRate);
- cells[index] = { at: time, timecode };
-
- if (!combine) {
- result[index] = { timecode, base64: await canvasToPngBase64(wrapped.canvas) };
- continue;
- }
-
- // Compose a sheet as soon as its last frame lands and drop the
- // canvases, so a long run never holds every decoded frame at once.
- canvases[index] = wrapped.canvas;
- const sheet = sheetOf[index];
- if (--missing[sheet] > 0) continue;
-
- const from = sheetStart[sheet];
- const to = from + sizes[sheet];
- result[sheet] = {
- timecode: sheetTimecode(cells.slice(from, to)),
- base64: await composeSheet(
- canvases.slice(from, to).map((canvas, k) => ({ image: canvas!, label: cells[from + k].timecode })),
- plans[sheet],
- ),
- };
- for (let k = from; k < to; k++) canvases[k] = undefined;
- }
-
- return result;
- } finally {
- input.dispose();
- }
- };
-}
-
-const transcripts = new Map<string, TranscriptSegment[]>();
-
-export function handleMediaTranscribe(resolve: ResolveAsset) {
- return async (req: MediaTranscribeRequest): Promise<MediaTranscribeResult> => {
- const asset = await resolve(req.path);
- const id = asset.id;
- assert(
- asset.type === "AUDIO" || asset.type === "VIDEO",
- `Asset ${id} is not a video or audio asset.`,
- );
-
- let transcript = transcripts.get(asset.id);
- if (!transcript) {
- const uploadId = crypto.randomUUID();
- const audioFile = await transcodeForTranscription(asset);
- const fileRef = await uploadBlob(audioFile, uploadId);
- if (!fileRef) throw new Error(`Failed to upload asset ${id} for transcription.`);
-
- ({ results: transcript } = await trpc.transcribe.mutate({ audio: fileRef }));
- if (!transcript.length || transcript.every((s) => s.words.length === 0)) {
- throw new Error("No speech detected. The audio does not appear to contain recognizable speech.");
- }
-
- transcripts.set(asset.id, transcript);
- }
-
- return { segments: transcript };
- };
-}
-
-export function handleMediaFilmstrip(resolve: ResolveAsset) {
- return async (req: MediaFilmstripRequest): Promise<MediaFilmstripResult> => {
- const asset = await resolve(req.path);
- const { dataUrl, ...rest } = await filmstripAsset(asset, { start: req.start, end: req.end, scale: req.scale });
- const base64 = dataUrl.slice(dataUrl.indexOf(",") + 1);
- return { base64, ...rest };
- };
-}
-
-export function handleMediaWaveform(resolve: ResolveAsset) {
- return async (req: MediaWaveformRequest): Promise<MediaWaveformResult> => {
- const asset = await resolve(req.path);
- const { dataUrl, ...rest } = await waveformAsset(asset, { start: req.start, end: req.end, scale: req.scale });
- const base64 = dataUrl.slice(dataUrl.indexOf(",") + 1);
- return { base64, ...rest };
- };
-}
-
-export function handleMediaListen(resolve: ResolveAsset, session: Accessor<EditorSession | null>) {
- return async (req: MediaListenRequest): Promise<MediaListenResult> => {
- const { prompt, start, end } = req;
- let { stripVideo } = req;
- const asset = await resolve(req.path);
- const id = asset.id;
- assert(
- asset.type === "AUDIO" || asset.type === "VIDEO",
- `Asset ${id} is not a video or audio asset.`,
- );
-
- const hasWindow = start !== undefined || end !== undefined;
- stripVideo = stripVideo !== false && asset.type === "VIDEO";
-
- const contentType =
- asset.type === "VIDEO" ? (stripVideo ? "audio/ogg" : "video/mp4") : "audio/ogg";
-
- const window = hasWindow ? `-${start ?? 0}-${end ?? "end"}` : "";
- const uploadId = `${session()?.world.get(Project)?.id ?? "project"}-${id}-analyze${stripVideo ? "-audio" : ""}${window}`
- .replace(/[^A-Za-z0-9._-]/g, "_");
- const { uploadUrl, fileRef } = await trpc.getUploadUrl.mutate({
- action: "resumable",
- id: uploadId,
- contentType,
- });
-
- // Transcoding pending
- if (uploadUrl) {
- const transcoder = await transcodeForAnalysis(asset, { start, end, stripVideo });
- const sessionUrl = await startResumableSession(uploadUrl, contentType);
- const uploadPromise = uploadResumableStream(transcoder.readable, sessionUrl);
- await transcoder.run?.();
- await uploadPromise;
- }
-
- const { analysis } = await trpc.analyze.mutate({ media: fileRef, prompt });
-
- return { result: analysis, start, end };
- };
-}
-
-async function canvasToPngBase64(canvas: HTMLCanvasElement | OffscreenCanvas): Promise<string> {
- if (canvas instanceof OffscreenCanvas) {
- const blob = await canvas.convertToBlob({ type: "image/png" });
- return base64FromArrayBuffer(await blob.arrayBuffer());
- }
- return canvas.toDataURL("image/png").split(",")[1] ?? "";
-}
-
-function base64FromArrayBuffer(buf: ArrayBuffer): string {
- const bytes = new Uint8Array(buf);
- let binary = "";
- const chunk = 0x8000;
- for (let i = 0; i < bytes.length; i += chunk) {
- binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
- }
- return btoa(binary);
-}
diff --git a/apps/web/src/context/dapi/models.ts b/apps/web/src/context/dapi/models.ts
deleted file mode 100644
index 9a63257e..00000000
--- a/apps/web/src/context/dapi/models.ts
+++ /dev/null
@@ -1,47 +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/. */
-
-import {
- PROMPT_INPUT_IMAGE_MODEL_OPTIONS,
- PROMPT_INPUT_VIDEO_MODEL_OPTIONS,
- PROMPT_INPUT_AUDIO_MODEL_OPTIONS,
-} from "@/components/genai/config";
-import type { ModelsRequest, ModelInfo } from "@diffusionstudio/cli/channels";
-
-export function handleModels() {
- return async (req: ModelsRequest) => {
- const out: ModelInfo[] = [];
- if (!req.type || req.type === "image") {
- for (const option of PROMPT_INPUT_IMAGE_MODEL_OPTIONS) {
- out.push({
- type: "image",
- id: option.id,
- name: option.name,
- });
- }
- }
- if (!req.type || req.type === "video") {
- for (const option of PROMPT_INPUT_VIDEO_MODEL_OPTIONS) {
- out.push({
- type: "video",
- id: option.id,
- name: option.name,
- durations: option.durations,
- aspectRatios: option.aspectRatios,
- features: option.features,
- });
- }
- }
- if (!req.type || req.type === "audio") {
- for (const option of PROMPT_INPUT_AUDIO_MODEL_OPTIONS) {
- out.push({
- type: "audio",
- id: option.id,
- name: option.name,
- });
- }
- }
- return out;
- };
-}
diff --git a/apps/web/src/context/dapi/window.ts b/apps/web/src/context/dapi/window.ts
deleted file mode 100644
index 5ae14da0..00000000
--- a/apps/web/src/context/dapi/window.ts
+++ /dev/null
@@ -1,19 +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/. */
-
-import { mainBridge } from "@/lib/ipc";
-import { MAIN_CHANNELS } from "@desktop/main-channels";
-
-export function handleGetFullscreenState() {
- if (!window.desktop) return Promise.resolve(false);
- return mainBridge.call(MAIN_CHANNELS.WINDOW_IS_FULLSCREEN, undefined);
-}
-
-export function handleWindowScreenshot() {
- return () => mainBridge.call(MAIN_CHANNELS.WINDOW_CAPTURE, undefined);
-}
-
-export function handleWindowFullscreenChange(mutate: (fullscreen: boolean) => void) {
- return ({ fullscreen }: { fullscreen: boolean }) => mutate(fullscreen);
-}
diff --git a/apps/web/src/context/render.ts b/apps/web/src/context/render.ts
index ab2eca7b..b7003a9d 100644
--- a/apps/web/src/context/render.ts
+++ b/apps/web/src/context/render.ts
@@ -32,6 +32,8 @@ export type RenderOverlayState = {
remaining?: { minutes: number; seconds: number };
};
+const PROGRESS_LOG_STEP = 2;
+
const [overlay, setOverlay] = createSignal<RenderOverlayState | null>(null);
let cancelActive: (() => void) | undefined;
@@ -78,6 +80,13 @@ export async function renderScene(
cancelActive = undefined;
setOverlay({ config, width, height, duration, progress: 0, remaining: undefined });
+ let logged = -1;
+ const logProgress = (percent: number) => {
+ if (percent - logged < PROGRESS_LOG_STEP && percent < 100) return;
+ logged = percent;
+ console.info(`[export] ${percent}%`);
+ };
+
engine.stop();
let capture: Capture | undefined;
@@ -94,6 +103,7 @@ export async function renderScene(
comment: `Made with Diffusion Studio v${version}`,
onProgress(p) {
const percent = Math.round((p.progress / p.total) * 100);
+ logProgress(percent);
setOverlay((prev) =>
prev
? {
diff --git a/apps/web/src/dapi/api.tsx b/apps/web/src/dapi/api.tsx
new file mode 100644
index 00000000..f2d9c8ca
--- /dev/null
+++ b/apps/web/src/dapi/api.tsx
@@ -0,0 +1,94 @@
+/* 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 { createEffect, createContext, useContext, onCleanup } from "solid-js";
+import { useNavigate } from "@solidjs/router";
+import { useWorld } from "@diffusionstudio/koota-solid";
+import { Project } from "@diffusionstudio/runtime";
+import { DapiError } from "@diffusionstudio/dapi";
+import { useProject } from "@/context/project";
+import { useAuth } from "@/context/auth";
+import { useEngineContext } from "@/engine";
+import { openProjectFolder } from "@/projects";
+import { projectRoute } from "@/hooks/use-project-route";
+import { useFullscreenState } from "@/hooks/use-fullscreen-state";
+import { assert } from "@/utils/common";
+import { toolBridge } from "./bridge";
+import { handlers } from "./handlers";
+import { editorSession, requireEditorSession, setEditorSession } from "./session";
+
+import type { JSX, Accessor } from "solid-js";
+import type { ContextFactory } from "./bridge";
+
+type EditorApiContextValue = {
+ isFullscreen: Accessor<boolean>;
+ isDesktop: boolean;
+};
+
+const EditorApiContext = createContext<EditorApiContextValue>();
+
+/**
+ * Registers the tool handlers for as long as the app runs. Every tool is
+ * reachable whether or not a project is open; the ones that need one read
+ * the session slot (see ./session) per call and fail with a clear error —
+ * or, for `context`, report that nothing is open. Renders nothing; must sit
+ * inside the router tree for `useNavigate` and inside the auth provider.
+ */
+export function EditorApi() {
+ const navigate = useNavigate();
+ const auth = useAuth();
+
+ const context: ContextFactory = (signal) => ({
+ session: editorSession,
+ requireSession: requireEditorSession,
+ signal,
+ app: {
+ async openProject(dir) {
+ const project = await openProjectFolder(dir);
+ navigate(projectRoute(project.id || project.name));
+ return { id: project.id, name: project.displayName, dir: project.dir };
+ },
+ user: () => auth.user() ?? null,
+ requireUser() {
+ const user = auth.user();
+ if (!user) throw new DapiError("sign-in-required", "Sign in required: AI generation needs a Diffusion Studio account.");
+ return user;
+ },
+ },
+ });
+
+ onCleanup(toolBridge.register(handlers, context));
+ return null;
+}
+
+/**
+ * Publishes the editor session for the tool handlers while the project is
+ * open, and provides the editor UI's own view of the app shell (fullscreen
+ * state, desktop-ness). Mounted per project page.
+ */
+export function EditorApiProvider(props: { children: JSX.Element }) {
+ const project = useProject();
+ const isFullscreen = useFullscreenState();
+ const world = useWorld();
+ const engine = useEngineContext();
+
+ createEffect(() => {
+ if (!window.desktop || project.id() !== world.get(Project)?.id) return;
+
+ setEditorSession({ world, project, engine });
+ onCleanup(() => setEditorSession(null));
+ });
+
+ return (
+ <EditorApiContext.Provider value={{ isFullscreen, isDesktop: !!window.desktop }}>
+ {props.children}
+ </EditorApiContext.Provider>
+ );
+}
+
+export function useEditorApi() {
+ const ctx = useContext(EditorApiContext);
+ assert(ctx, "useEditorApi must be used within EditorApiProvider");
+ return ctx;
+}
diff --git a/apps/web/src/dapi/bridge.ts b/apps/web/src/dapi/bridge.ts
new file mode 100644
index 00000000..c640bb56
--- /dev/null
+++ b/apps/web/src/dapi/bridge.ts
@@ -0,0 +1,73 @@
+/* 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 { DAPI_WIRE, isDapiError } from "@diffusionstudio/dapi";
+
+import type { DapiCall, DapiCancel, DapiReply } from "@diffusionstudio/dapi";
+import type { Handlers, ServedToolName, ToolContext } from "./handler";
+
+/** Builds the per-call context; the bridge supplies the abort signal. */
+export type ContextFactory = (signal: AbortSignal) => ToolContext;
+
+/**
+ * Answers renderer tools for the MCP server in main. Main validated the
+ * arguments against the catalog before sending them; this side runs the
+ * handler and replies, honouring cancels. Calls that arrive before the
+ * handlers register (page bootstrap) are held and answered on registration.
+ */
+class ToolBridge {
+ private handlers: Handlers | null = null;
+ private context: ContextFactory | null = null;
+ private held: DapiCall[] = [];
+ private readonly inFlight = new Map<string, AbortController>();
+
+ constructor() {
+ // Bind eagerly so calls during page bootstrap are caught rather than
+ // silently dropped before the handlers register.
+ window.desktop?.on(DAPI_WIRE.CALL, (payload) => void this.dispatch(payload as DapiCall));
+ window.desktop?.on(DAPI_WIRE.CANCEL, (payload) => this.inFlight.get((payload as DapiCancel).id)?.abort());
+ }
+
+ register(handlers: Handlers, context: ContextFactory): () => void {
+ this.handlers = handlers;
+ this.context = context;
+ const held = this.held;
+ this.held = [];
+ for (const call of held) void this.dispatch(call);
+ return () => {
+ if (this.handlers === handlers) {
+ this.handlers = null;
+ this.context = null;
+ }
+ };
+ }
+
+ private async dispatch(call: DapiCall): Promise<void> {
+ if (!this.handlers || !this.context) {
+ this.held.push(call);
+ return;
+ }
+
+ const controller = new AbortController();
+ this.inFlight.set(call.id, controller);
+
+ let reply: DapiReply;
+ try {
+ const handler = this.handlers[call.tool as ServedToolName];
+ if (!handler) throw new Error(`The app has no handler for "${call.tool}"`);
+ // Every handler takes its own parsed args; the map's union type cannot
+ // express that pairing, so the call site widens.
+ const run = handler as (args: unknown, ctx: ToolContext) => Promise<unknown>;
+ reply = { id: call.id, ok: true, data: await run(call.args, this.context(controller.signal)) };
+ } catch (error) {
+ const message = (error as Error).message;
+ reply = { id: call.id, ok: false, error: isDapiError(error) ? { code: error.code, message } : { message } };
+ } finally {
+ this.inFlight.delete(call.id);
+ }
+ if (!controller.signal.aborted) window.desktop?.send(DAPI_WIRE.REPLY, reply);
+ }
+}
+
+export const toolBridge = new ToolBridge();
diff --git a/apps/web/src/dapi/handler.ts b/apps/web/src/dapi/handler.ts
new file mode 100644
index 00000000..22237088
--- /dev/null
+++ b/apps/web/src/dapi/handler.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 { Accessor } from "solid-js";
+import type { User } from "@supabase/supabase-js";
+import type { ToolArgs, ToolName, ToolResult } from "@diffusionstudio/dapi";
+import type { EditorSession } from "./session";
+
+/**
+ * What every handler gets besides its arguments. Built per call by the
+ * bridge from what the app shell provides (see ./api), so handlers are plain
+ * functions with no Solid in them.
+ */
+export type ToolContext = {
+ /** The open project's session, or null at the dashboard. */
+ session: Accessor<EditorSession | null>;
+ /** The session, or a `no-project` error the caller can act on. */
+ requireSession(): EditorSession;
+ /** Fires when the caller cancels or goes away before the reply. */
+ signal: AbortSignal;
+ /** What only the app shell can do: navigate, and know who is signed in. */
+ app: {
+ openProject(dir: string): Promise<ToolResult<"open">>;
+ user(): User | null;
+ /** The signed-in user, or a `sign-in-required` error. */
+ requireUser(): User;
+ };
+};
+
+export type ToolHandler<N extends ToolName> = (args: ToolArgs<N>, ctx: ToolContext) => Promise<ToolResult<N>>;
+
+/** The tools the renderer answers; the rest run in the main process. */
+export type ServedToolName = Exclude<ToolName, "logs" | "fonts" | "fetch" | "report">;
+
+export type Handlers = { readonly [N in ServedToolName]: ToolHandler<N> };
diff --git a/apps/web/src/dapi/handlers/capture.ts b/apps/web/src/dapi/handlers/capture.ts
new file mode 100644
index 00000000..da4d32e8
--- /dev/null
+++ b/apps/web/src/dapi/handlers/capture.ts
@@ -0,0 +1,55 @@
+/* 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 { createImageEncoder, decodePng } from "@diffusionstudio/encoder";
+import { TIME_FPS } from "@diffusionstudio/jsx";
+import { DapiError } from "@diffusionstudio/dapi";
+import { createCapture } from "@/engine/capture";
+import { requireScene } from "../lib/scene";
+import { SheetCollector } from "../lib/sheets";
+
+import type { ToolHandler } from "../handler";
+
+// Ceiling on the height a sheet cell renders a node at.
+const SHEET_CAPTURE_HEIGHT = 1080;
+
+export const capture: ToolHandler<"capture"> = async ({ id, times, separate, perSheet }, ctx) => {
+ const { world, project } = ctx.requireSession();
+ const scene = requireScene(world, id, "capture");
+
+ // Positions arrive in seconds and the encoder samples frame numbers;
+ // none given means the export's first frame (the workarea's start).
+ const shots = times && times.length > 0 ? times.map((t) => Math.round(t * TIME_FPS)) : [0];
+
+ // The project re-rendered into a world of its own, reduced to this scene:
+ // the same arrangement an export runs against, and the encoder's to draw.
+ const target = await createCapture(world, scene, { dir: project.dir() });
+ try {
+ const encoder = await createImageEncoder(target.world, { frames: shots, resolution: 720 });
+
+ // Sheets render at their cell size instead of the flat 720p: with a few
+ // frames that is sharper than a standalone capture, never coarser. A
+ // scene is drawn, not decoded, so a small one is worth rendering past
+ // its own size; beyond SHEET_CAPTURE_HEIGHT that only costs tokens.
+ let sheets: SheetCollector | undefined;
+ if (!separate) {
+ const aspect = encoder.bounds.width / encoder.bounds.height;
+ const height = Math.max(encoder.bounds.height, SHEET_CAPTURE_HEIGHT);
+ sheets = new SheetCollector(shots.length, { width: height * aspect, height }, perSheet);
+ encoder.resize(sheets.cellHeight);
+ }
+
+ const result = await encoder.render();
+ if (result.type === "canceled") throw new DapiError("canceled", "Capture canceled");
+ if (result.type === "error") throw result.error;
+ if (!sheets) return result.data;
+
+ for (const [index, { timecode, png }] of result.data.entries()) {
+ await sheets.add(index, { at: shots[index]!, timecode, image: await decodePng(png) });
+ }
+ return sheets.result();
+ } finally {
+ target.dispose();
+ }
+};
diff --git a/apps/web/src/context/dapi/check.ts b/apps/web/src/dapi/handlers/check.ts
similarity index 95%
rename from apps/web/src/context/dapi/check.ts
rename to apps/web/src/dapi/handlers/check.ts
index 15a59505..03209cb7 100644
--- a/apps/web/src/context/dapi/check.ts
+++ b/apps/web/src/dapi/handlers/check.ts
@@ -8,11 +8,11 @@ import {
SourceError, Workarea, framesToSeconds, getIntrinsicPaint, isText,
} from "@diffusionstudio/runtime";
-import { resolveNode } from "./nodes";
+import { resolveNode } from "../lib/nodes";
-import type { CheckIssue, CheckRequest, CheckResult } from "@diffusionstudio/cli/channels";
+import type { CheckIssue } from "@diffusionstudio/dapi";
import type { Entity } from "koota";
-import type { EditorSession } from "./session";
+import type { ToolHandler } from "../handler";
// Absolute frames, [start, end).
type Interval = { start: number; end: number };
@@ -147,9 +147,8 @@ function findGaps(window: Interval, coverage: Interval[]): Interval[] {
return gaps.filter((gap) => gap.end - gap.start >= 1);
}
-export function handleCheck(session: () => EditorSession) {
- return async ({ id }: CheckRequest): Promise<CheckResult> => {
- const { world } = session();
+export const check: ToolHandler<"check"> = async ({ id }, ctx) => {
+ const { world } = ctx.requireSession();
const target = resolveNode(world, id);
const fps = world.get(FrameRate)?.value ?? 30;
@@ -207,5 +206,4 @@ export function handleCheck(session: () => EditorSession) {
},
issues,
};
- };
-}
+};
diff --git a/apps/web/src/dapi/handlers/context.ts b/apps/web/src/dapi/handlers/context.ts
new file mode 100644
index 00000000..ff5d2bb2
--- /dev/null
+++ b/apps/web/src/dapi/handlers/context.ts
@@ -0,0 +1,82 @@
+/* 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 { AssetId, Computed, Fonts, FrameRate, Generating, getActiveEntity, Library, Name, PendingSource, Source, SourceError } from "@diffusionstudio/runtime";
+import { getProjectsRoot } from "@/projects";
+
+import type { Entity, World } from "koota";
+import type { GenerationRow } from "@diffusionstudio/dapi";
+import type { ToolHandler } from "../handler";
+
+/**
+ * What the project's source cannot say. The JSX is the composition — its
+ * scenes, what is selected, which scene is active, the work area are all in
+ * the file, and a caller that wants them reads it. What is left over is which
+ * folder projects live under, which project folder the app has open, where its
+ * playhead sits, which font families are actually registered in the world
+ * drawing it. With no project open only the root is left to report.
+ */
+export const context: ToolHandler<"context"> = async (_, ctx) => {
+ const rootDir = await getProjectsRoot();
+
+ const open = ctx.session();
+ if (!open) return { rootDir, projectDir: null, currentTime: null, fontFamilies: [], generations: [] };
+
+ const { world, project } = open;
+ const frameRate = world.get(FrameRate)?.value || 30;
+ const active = getActiveEntity(world);
+
+ return {
+ rootDir,
+ projectDir: project.dir(),
+ // Seconds, the unit the source places clips in; null when no scene is
+ // active, which is when there is no playhead to report.
+ currentTime: active ? (active.get(Computed)?.localTime ?? 0) / frameRate : null,
+ // What text can be drawn with right now: registered in the world, not
+ // merely named in the source. The editor default is always among them.
+ fontFamilies: [...new Set(["Inter", ...(world.get(Fonts)?.list ?? []).map((f) => f.family)])],
+ generations: collectGenerations(world),
+ };
+};
+
+function collectGenerations(world: World): GenerationRow[] {
+ const library = world.get(Library);
+ const rows: GenerationRow[] = [];
+ const seen = new Set<string>();
+
+ const push = (row: GenerationRow) => {
+ const key = JSON.stringify(row);
+ if (seen.has(key)) return;
+ seen.add(key);
+ rows.push(row);
+ };
+
+ for (const entity of world.query(Generating)) {
+ push({ ...describeElement(entity), state: "generating" });
+ }
+
+ for (const entity of world.query(SourceError)) {
+ const failure = entity.get(SourceError)!;
+ if (!failure.generated) continue;
+ push({ ...describeElement(entity), state: "failed", error: failure.value });
+ }
+
+ for (const entity of world.query(AssetId)) {
+ // A stale binding — the element is off generating a new answer or failed
+ // getting one — is not a generation that is done.
+ if (entity.has(Generating) || entity.has(PendingSource) || entity.has(SourceError)) continue;
+ const asset = library?.get(entity.get(AssetId)!.value);
+ if (!asset?.generation) continue;
+ push({ ...describeElement(entity), state: "done", asset: asset.path });
+ }
+
+ return rows;
+}
+
+function describeElement(entity: Entity): Pick<GenerationRow, "element" | "name"> {
+ return {
+ element: entity.get(Source)?.value || null,
+ name: entity.get(Name)?.value || null,
+ };
+}
diff --git a/apps/web/src/dapi/handlers/export.ts b/apps/web/src/dapi/handlers/export.ts
new file mode 100644
index 00000000..fc688cc8
--- /dev/null
+++ b/apps/web/src/dapi/handlers/export.ts
@@ -0,0 +1,118 @@
+/* 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 { canEncodeVideo } from "mediabunny";
+import { computeOutputSize } from "@diffusionstudio/encoder";
+import { Computed, FrameRate, Workarea } from "@diffusionstudio/runtime";
+import { DapiError } from "@diffusionstudio/dapi";
+
+import { renderOverlay, renderScene } from "@/context/render";
+import { ElectronWritableFileHandle } from "@/lib/electron-file-writable";
+import { ProjectConfig as ProjectConfigTrait } from "@/engine/traits";
+import { sceneConfigKey } from "@/engine/project-config";
+import { getDefaultExportTemplate, VIDEO_FORMAT_OPTIONS } from "@/components/sidebar-right/inspector/export-templates";
+import { mainBridge } from "@/lib/ipc";
+import { MAIN_CHANNELS } from "@desktop/main-channels";
+import { requireScene } from "../lib/scene";
+
+import type { ExportSettings } from "@diffusionstudio/dapi";
+import type { ContainerFormat, ExportConfig } from "@/engine/project-config";
+import type { ToolHandler } from "../handler";
+
+/**
+ * The container the export writes: the output extension when a path was
+ * given (ffmpeg's rule — the file must be what its name says), the config's
+ * format otherwise, mp4 when neither says. A given path settles it entirely,
+ * so a bad config format only fails an export that would actually use it.
+ */
+function resolveFormat(path: string | undefined, config: ExportConfig): ContainerFormat {
+ const supported = VIDEO_FORMAT_OPTIONS.map((format) => `.${format}`).join(", ");
+ if (path !== undefined) {
+ const extension = /\.([a-z0-9]+)$/i.exec(path)?.[1]?.toLowerCase();
+ if (!extension || !VIDEO_FORMAT_OPTIONS.includes(extension as ContainerFormat)) {
+ throw new DapiError("invalid-input", `The output path must end in a container extension: ${supported}.`);
+ }
+ return extension as ContainerFormat;
+ }
+ const format = config.format ?? "mp4";
+ if (!VIDEO_FORMAT_OPTIONS.includes(format)) {
+ throw new DapiError(
+ "invalid-input",
+ `The export entry names an unknown format "${format}" — use one of ${supported.replaceAll(".", "")}.`,
+ );
+ }
+ return format;
+}
+
+export const exportScene: ToolHandler<"export"> = async ({ id, path }, ctx) => {
+ const { world, project, engine } = ctx.requireSession();
+ const scene = requireScene(world, id, "export");
+
+ // The scene's entry in the project's package.json (`diffusion.export.<id>`)
+ // — the same one the app's export panel writes — so a tool export
+ // reproduces the in-app one; a scene without an entry uses the default
+ // template, the way ⌘E does. `template` is only the preset's label.
+ const base = world.get(ProjectConfigTrait)?.exportOf(scene) ?? getDefaultExportTemplate();
+ const settings: ExportConfig = { format: base.format, video: base.video, audio: base.audio };
+
+ const format = resolveFormat(path, settings);
+ const key = sceneConfigKey(scene) ?? id;
+ const target = path ?? `${project.dir()}/exports/${key.replace(/[^\w.-]+/g, "-")}.${format}`;
+
+ // Fail before the render machinery spins up: an unencodable configuration
+ // is known right away (same precheck the UI export runs).
+ const videoEnabled = format !== "ogg" && settings.video?.enabled !== false;
+ const computed = scene.get(Computed);
+ const { width, height } = computeOutputSize(
+ computed?.width || 1920,
+ computed?.height || 1080,
+ settings.video?.resolution ?? 1080,
+ );
+ if (videoEnabled) {
+ const codec = settings.video?.codec ?? "avc";
+ const encodable = await canEncodeVideo(codec, { width, height, bitrate: settings.video?.bitrate ?? 10e6 });
+ if (!encodable) {
+ throw new DapiError(
+ "unsupported",
+ `Cannot encode ${codec.toUpperCase()} at ${width}×${height}. ` +
+ "Set a lower resolution, a lower bitrate, or another codec in the scene's export entry.",
+ );
+ }
+ }
+
+ const workarea = scene.get(Workarea);
+ const frames = workarea ? workarea.end - workarea.start : computed?.duration ?? 0;
+ const duration = frames / (world.get(FrameRate)?.value || 30);
+
+ // renderScene owns the one render slot (it stops the live engine and
+ // raises the progress overlay), so refuse a second export rather than
+ // interleave. No await sits between this check and renderScene claiming
+ // the overlay, so two racing requests cannot both pass.
+ if (renderOverlay()) {
+ throw new DapiError("busy", "An export is already running — wait for it to finish, or cancel it in the app.");
+ }
+
+ const handle = new ElectronWritableFileHandle(target);
+ try {
+ const result = await renderScene(engine, { scene, target: handle, config: { ...settings, format }, dir: project.dir() });
+ if (result.type === "canceled") throw new DapiError("canceled", "Export canceled in the app");
+ if (result.type === "error") throw result.error;
+ } catch (error) {
+ // Close the fd and drop the partial file; a failed export leaves nothing.
+ await handle.dispose().catch(() => {});
+ throw error;
+ }
+
+ const stat = await mainBridge.call(MAIN_CHANNELS.PROJECTS_FS_STAT, { dir: project.dir(), source: target });
+
+ const config: ExportSettings = { format, video: settings.video, audio: settings.audio };
+ return {
+ path: target,
+ width: videoEnabled ? width : 0,
+ height: videoEnabled ? height : 0,
+ duration,
+ size: stat?.size ?? 0,
+ config,
+ };
+};
diff --git a/apps/web/src/dapi/handlers/index.ts b/apps/web/src/dapi/handlers/index.ts
new file mode 100644
index 00000000..9aa95a0b
--- /dev/null
+++ b/apps/web/src/dapi/handlers/index.ts
@@ -0,0 +1,40 @@
+/* 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 { open } from "./open";
+import { context } from "./context";
+import { capture } from "./capture";
+import { check } from "./check";
+import { exportScene } from "./export";
+import { models } from "./models";
+import { voices } from "./voices";
+import { whoami } from "./whoami";
+import { screenshot } from "./screenshot";
+import { mediaProbe } from "./media-probe";
+import { mediaGrab } from "./media-grab";
+import { mediaTranscribe } from "./media-transcribe";
+import { mediaFilmstrip } from "./media-filmstrip";
+import { mediaWaveform } from "./media-waveform";
+import { mediaListen } from "./media-listen";
+
+import type { Handlers } from "../handler";
+
+/** Every tool the renderer answers, keyed by its catalog name. */
+export const handlers: Handlers = {
+ open,
+ context,
+ capture,
+ check,
+ export: exportScene,
+ models,
+ voices,
+ whoami,
+ screenshot,
+ media_probe: mediaProbe,
+ media_grab: mediaGrab,
+ media_transcribe: mediaTranscribe,
+ media_filmstrip: mediaFilmstrip,
+ media_waveform: mediaWaveform,
+ media_listen: mediaListen,
+};
diff --git a/apps/web/src/dapi/handlers/media-filmstrip.ts b/apps/web/src/dapi/handlers/media-filmstrip.ts
new file mode 100644
index 00000000..7902b328
--- /dev/null
+++ b/apps/web/src/dapi/handlers/media-filmstrip.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 { filmstripAsset } from "@diffusionstudio/runtime";
+import { resolveAsset } from "../lib/assets";
+import { dataUrlToBytes } from "../lib/png";
+
+import type { ToolHandler } from "../handler";
+
+export const mediaFilmstrip: ToolHandler<"media_filmstrip"> = async ({ path, start, end, scale }, ctx) => {
+ const asset = await resolveAsset(ctx, path);
+ const { dataUrl, ...rest } = await filmstripAsset(asset, { start, end, scale });
+ return { png: dataUrlToBytes(dataUrl), ...rest };
+};
diff --git a/apps/web/src/dapi/handlers/media-grab.ts b/apps/web/src/dapi/handlers/media-grab.ts
new file mode 100644
index 00000000..7212d4f1
--- /dev/null
+++ b/apps/web/src/dapi/handlers/media-grab.ts
@@ -0,0 +1,132 @@
+/* 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 { ALL_FORMATS, BlobSource, CanvasSink, Input } from "mediabunny";
+import { encodePng } from "@diffusionstudio/encoder";
+import { formatTimecode, getAssetFile } from "@diffusionstudio/runtime";
+import { DapiError } from "@diffusionstudio/dapi";
+import { pickInformativeTimes } from "../lib/frame-triage";
+import { requireAssetType, resolveAsset } from "../lib/assets";
+import { SheetCollector } from "../lib/sheets";
+
+import type { FrameQuality, TimecodedImage } from "@diffusionstudio/dapi";
+import type { ToolHandler } from "../handler";
+
+// Named quality presets mapped to a per-frame total-pixel budget (aspect ratio
+// preserved). A budget of 0 means native resolution. `small` keeps frames small
+// enough for vision models.
+const FRAME_QUALITY_BUDGETS: Record<FrameQuality, number> = {
+ small: 384 * 384,
+ medium: 768 * 768,
+ large: 1536 * 1536,
+ fullres: 0,
+};
+
+// Default cap on frames returned by auto selection when `count` is not given.
+const AUTO_MAX_FRAMES = 30;
+
+export const mediaGrab: ToolHandler<"media_grab"> = async (args, ctx) => {
+ const { times, count, start, end, quality, auto, separate, perSheet } = args;
+ const asset = await resolveAsset(ctx, args.path);
+ requireAssetType(asset, ["VIDEO"], "a video");
+
+ // `count` samples evenly across a window (default the whole clip); `auto`
+ // scans the window and keeps frames where the footage settles into a new
+ // visual state, capped at `count` (resolved once the track is open).
+ // Otherwise grab the explicit `times` (falling back to a single frame at 0).
+ const from = Math.min(Math.max(start ?? 0, 0), asset.duration);
+ const to = Math.min(Math.max(end ?? asset.duration, from), asset.duration);
+ let requested: number[] = [];
+ if (auto || count !== undefined) {
+ if (to <= from) {
+ throw new DapiError(
+ "invalid-input",
+ `The requested window is empty; start (${from.toFixed(2)}s) is at or past end (${to.toFixed(2)}s).`,
+ );
+ }
+ if (!auto && count !== undefined) {
+ const interval = (to - from) / count;
+ requested = Array.from({ length: count }, (_, i) => from + i * interval);
+ }
+ } else {
+ requested = (times && times.length ? times : [0]).map((t) => resolveTime(t, asset.duration));
+ }
+
+ const budget = FRAME_QUALITY_BUDGETS[quality ?? (separate ? "small" : "fullres")];
+
+ const blob = await getAssetFile(asset);
+ const input = new Input({ formats: ALL_FORMATS, source: new BlobSource(blob) });
+ try {
+ const track = await input.getPrimaryVideoTrack();
+ if (!track) throw new DapiError("wrong-kind", `Asset ${asset.id} has no video track.`);
+
+ // Track timestamps may not start at 0; offset content time by the first.
+ const firstTimestamp = (await track.getFirstTimestamp()) ?? 0;
+
+ if (auto) {
+ const picked = await pickInformativeTimes(track, {
+ from: firstTimestamp + from,
+ to: firstTimestamp + to,
+ max: count ?? AUTO_MAX_FRAMES,
+ });
+ requested = picked.map((t) => Math.max(0, t - firstTimestamp));
+ }
+
+ // Downscale to fit the pixel budget while preserving aspect ratio.
+ const displayWidth = await track.getDisplayWidth();
+ const displayHeight = await track.getDisplayHeight();
+ let sourceWidth = displayWidth;
+ let sourceHeight = displayHeight;
+ if (budget > 0 && displayWidth * displayHeight > budget) {
+ const scale = Math.sqrt(budget / (displayWidth * displayHeight));
+ sourceWidth = Math.max(1, Math.round(displayWidth * scale));
+ sourceHeight = Math.max(1, Math.round(displayHeight * scale));
+ }
+
+ // Lay the sheets out up front: the largest cell across them sets the
+ // decode size, so no frame is decoded bigger than it will be drawn.
+ const sheets = separate ? undefined : new SheetCollector(requested.length, { width: sourceWidth, height: sourceHeight }, perSheet);
+ const width = sheets ? Math.min(sourceWidth, sheets.cellWidth) : sourceWidth;
+
+ // Decode in ascending order (the sink's fast path), remember each
+ // entry's original slot so output mirrors the requested order.
+ const ordered = requested.map((time, index) => ({ time, index })).sort((a, b) => a.time - b.time);
+
+ // No pool: each yielded canvas is fresh, so encoding it can't race the
+ // generator's read-ahead reusing a pooled canvas.
+ const sink = new CanvasSink(track, width < displayWidth ? { width } : undefined);
+ const frames: TimecodedImage[] = new Array(requested.length);
+
+ let i = 0;
+ for await (const wrapped of sink.canvasesAtTimestamps(ordered.map(({ time }) => firstTimestamp + time))) {
+ const { time, index } = ordered[i++]!;
+ if (!wrapped) throw new DapiError("not-found", `No frame found at ${time}s.`);
+ const timecode = formatTimecode(time, asset.frameRate);
+ if (sheets) await sheets.add(index, { at: time, timecode, image: wrapped.canvas });
+ else frames[index] = { timecode, png: await encodePng(wrapped.canvas) };
+ }
+
+ return sheets ? sheets.result() : frames;
+ } finally {
+ input.dispose();
+ }
+};
+
+/**
+ * A time within the clip. A negative time is an offset back from the end:
+ * -1 is one second before the end, -1f one frame before it.
+ */
+function resolveTime(t: number, duration: number): number {
+ if (t >= 0) {
+ if (t > duration) {
+ throw new DapiError("invalid-input", `time ${t}s is past the asset's duration (${duration.toFixed(2)}s).`);
+ }
+ return t;
+ }
+ const resolved = duration + t;
+ if (resolved < 0) {
+ throw new DapiError("invalid-input", `time ${t} counts past the start of the clip (duration ${duration.toFixed(2)}s).`);
+ }
+ return resolved;
+}
diff --git a/apps/web/src/dapi/handlers/media-listen.ts b/apps/web/src/dapi/handlers/media-listen.ts
new file mode 100644
index 00000000..eb3fc85a
--- /dev/null
+++ b/apps/web/src/dapi/handlers/media-listen.ts
@@ -0,0 +1,40 @@
+/* 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 { Project, transcodeForAnalysis } from "@diffusionstudio/runtime";
+import { trpc } from "@/lib/trpc";
+import { startResumableSession, uploadResumableStream } from "@/lib/uploads";
+import { requireAssetType, resolveAsset } from "../lib/assets";
+
+import type { ToolHandler } from "../handler";
+
+export const mediaListen: ToolHandler<"media_listen"> = async ({ path, prompt, start, end }, ctx) => {
+ ctx.app.requireUser();
+ const asset = await resolveAsset(ctx, path);
+ requireAssetType(asset, ["AUDIO", "VIDEO"], "a video or audio asset");
+
+ const hasWindow = start !== undefined || end !== undefined;
+ // A video is stripped to its audio track: the model listens, it does not watch.
+ const audioOnly = asset.type === "VIDEO";
+ const contentType = "audio/ogg";
+
+ // One upload per distinct analysis input, so a repeated question about the
+ // same span reuses the transcode.
+ const window = hasWindow ? `-${start ?? 0}-${end ?? "end"}` : "";
+ const uploadId = `${ctx.session()?.world.get(Project)?.id ?? "project"}-${asset.id}-analyze${audioOnly ? "-audio" : ""}${window}`
+ .replace(/[^A-Za-z0-9._-]/g, "_");
+ const { uploadUrl, fileRef } = await trpc.getUploadUrl.mutate({ action: "resumable", id: uploadId, contentType });
+
+ // An upload URL means the server does not have this input yet.
+ if (uploadUrl) {
+ const transcoder = await transcodeForAnalysis(asset, { start, end, stripVideo: audioOnly });
+ const sessionUrl = await startResumableSession(uploadUrl, contentType);
+ const uploadPromise = uploadResumableStream(transcoder.readable, sessionUrl);
+ await transcoder.run?.();
+ await uploadPromise;
+ }
+
+ const { analysis } = await trpc.analyze.mutate({ media: fileRef, prompt });
+ return { result: analysis, start, end };
+};
diff --git a/apps/web/src/dapi/handlers/media-probe.ts b/apps/web/src/dapi/handlers/media-probe.ts
new file mode 100644
index 00000000..525ddff5
--- /dev/null
+++ b/apps/web/src/dapi/handlers/media-probe.ts
@@ -0,0 +1,73 @@
+/* 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 { ALL_FORMATS, BlobSource, Input } from "mediabunny";
+import { getAssetFile } from "@diffusionstudio/runtime";
+import { assetName } from "@diffusionstudio/assets";
+import { resolveAsset } from "../lib/assets";
+
+import type { ToolHandler } from "../handler";
+
+const PROBE_SAMPLE_PACKETS = 200;
+
+export const mediaProbe: ToolHandler<"media_probe"> = async ({ path }, ctx) => {
+ const asset = await resolveAsset(ctx, path);
+ const blob = await getAssetFile(asset);
+ const base = {
+ id: asset.id,
+ name: assetName(asset),
+ path: asset.path,
+ type: asset.type,
+ mimeType: asset.mimeType,
+ size: blob.size,
+ ...("width" in asset && { width: asset.width, height: asset.height }),
+ };
+
+ const input = new Input({ formats: ALL_FORMATS, source: new BlobSource(blob) });
+ try {
+ const format = await input.getFormat();
+ const mimeType = await input.getMimeType();
+ const duration = await input.computeDuration();
+ const { images, ...tags } = await input.getMetadataTags();
+ delete tags.raw;
+
+ const tracks = [];
+ for (const track of await input.getTracks()) {
+ const stats = await track.computePacketStats(PROBE_SAMPLE_PACKETS);
+ tracks.push({
+ id: track.id,
+ type: track.type,
+ codec: track.codec,
+ language: track.languageCode,
+ firstTimestamp: await track.getFirstTimestamp(),
+ duration: await track.computeDuration(),
+ ...stats,
+ ...(track.isVideoTrack() && {
+ codedWidth: track.codedWidth,
+ codedHeight: track.codedHeight,
+ displayWidth: track.displayWidth,
+ displayHeight: track.displayHeight,
+ rotation: track.rotation,
+ }),
+ ...(track.isAudioTrack() && {
+ sampleRate: track.sampleRate,
+ channels: track.numberOfChannels,
+ }),
+ });
+ }
+
+ return {
+ ...base,
+ format: format.name,
+ mimeType,
+ duration,
+ tags: { ...tags, ...(images?.length && { attachedImages: images.length }) },
+ tracks,
+ };
+ } catch {
+ return { ...base, format: null, tracks: [] };
+ } finally {
+ input.dispose();
+ }
+};
diff --git a/apps/web/src/dapi/handlers/media-transcribe.ts b/apps/web/src/dapi/handlers/media-transcribe.ts
new file mode 100644
index 00000000..234c2632
--- /dev/null
+++ b/apps/web/src/dapi/handlers/media-transcribe.ts
@@ -0,0 +1,37 @@
+/* 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 { transcodeForTranscription } from "@diffusionstudio/runtime";
+import { trpc } from "@/lib/trpc";
+import { uploadBlob } from "@/lib/uploads";
+import { requireAssetType, resolveAsset } from "../lib/assets";
+
+import type { TranscriptSegment } from "@diffusionstudio/dapi";
+import type { ToolHandler } from "../handler";
+
+// Transcripts are remembered per asset for the app's lifetime: the audio
+// does not change, and the transcription is the expensive part.
+const transcripts = new Map<string, TranscriptSegment[]>();
+
+export const mediaTranscribe: ToolHandler<"media_transcribe"> = async ({ path }, ctx) => {
+ const asset = await resolveAsset(ctx, path);
+ requireAssetType(asset, ["AUDIO", "VIDEO"], "a video or audio asset");
+
+ let transcript = transcripts.get(asset.id);
+ if (!transcript) {
+ const uploadId = crypto.randomUUID();
+ const audioFile = await transcodeForTranscription(asset);
+ const fileRef = await uploadBlob(audioFile, uploadId);
+ if (!fileRef) throw new Error(`Failed to upload asset ${asset.id} for transcription.`);
+
+ ({ results: transcript } = await trpc.transcribe.mutate({ audio: fileRef }));
+ if (!transcript.length || transcript.every((s) => s.words.length === 0)) {
+ throw new Error("No speech detected. The audio does not appear to contain recognizable speech.");
+ }
+
+ transcripts.set(asset.id, transcript);
+ }
+
+ return { segments: transcript };
+};
diff --git a/apps/web/src/dapi/handlers/media-waveform.ts b/apps/web/src/dapi/handlers/media-waveform.ts
new file mode 100644
index 00000000..e15591c8
--- /dev/null
+++ b/apps/web/src/dapi/handlers/media-waveform.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 { waveformAsset } from "@diffusionstudio/runtime";
+import { resolveAsset } from "../lib/assets";
+import { dataUrlToBytes } from "../lib/png";
+
+import type { ToolHandler } from "../handler";
+
+export const mediaWaveform: ToolHandler<"media_waveform"> = async ({ path, start, end, scale }, ctx) => {
+ const asset = await resolveAsset(ctx, path);
+ const { dataUrl, ...rest } = await waveformAsset(asset, { start, end, scale });
+ return { png: dataUrlToBytes(dataUrl), ...rest };
+};
diff --git a/apps/web/src/dapi/handlers/models.ts b/apps/web/src/dapi/handlers/models.ts
new file mode 100644
index 00000000..5209511a
--- /dev/null
+++ b/apps/web/src/dapi/handlers/models.ts
@@ -0,0 +1,35 @@
+/* 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 {
+ PROMPT_INPUT_IMAGE_MODEL_OPTIONS,
+ PROMPT_INPUT_VIDEO_MODEL_OPTIONS,
+ PROMPT_INPUT_AUDIO_MODEL_OPTIONS,
+} from "@/components/genai/config";
+
+import type { ModelInfo } from "@diffusionstudio/dapi";
+import type { ToolHandler } from "../handler";
+
+export const models: ToolHandler<"models"> = async ({ type }) => {
+ const out: ModelInfo[] = [];
+ if (!type || type === "image") {
+ for (const { id, name } of PROMPT_INPUT_IMAGE_MODEL_OPTIONS) out.push({ type: "image", id, name });
+ }
+ if (!type || type === "video") {
+ for (const option of PROMPT_INPUT_VIDEO_MODEL_OPTIONS) {
+ out.push({
+ type: "video",
+ id: option.id,
+ name: option.name,
+ durations: option.durations,
+ aspectRatios: option.aspectRatios,
+ features: option.features,
+ });
+ }
+ }
+ if (!type || type === "audio") {
+ for (const { id, name } of PROMPT_INPUT_AUDIO_MODEL_OPTIONS) out.push({ type: "audio", id, name });
+ }
+ return { models: out };
+};
diff --git a/apps/web/src/dapi/handlers/open.ts b/apps/web/src/dapi/handlers/open.ts
new file mode 100644
index 00000000..f4c0dcfb
--- /dev/null
+++ b/apps/web/src/dapi/handlers/open.ts
@@ -0,0 +1,7 @@
+/* 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 { ToolHandler } from "../handler";
+
+export const open: ToolHandler<"open"> = ({ dir }, ctx) => ctx.app.openProject(dir);
diff --git a/apps/web/src/dapi/handlers/screenshot.ts b/apps/web/src/dapi/handlers/screenshot.ts
new file mode 100644
index 00000000..8c9d2c67
--- /dev/null
+++ b/apps/web/src/dapi/handlers/screenshot.ts
@@ -0,0 +1,10 @@
+/* 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 { mainBridge } from "@/lib/ipc";
+import { MAIN_CHANNELS } from "@desktop/main-channels";
+
+import type { ToolHandler } from "../handler";
+
+export const screenshot: ToolHandler<"screenshot"> = () => mainBridge.call(MAIN_CHANNELS.WINDOW_CAPTURE, undefined);
diff --git a/apps/web/src/context/dapi/voices.ts b/apps/web/src/dapi/handlers/voices.ts
similarity index 55%
rename from apps/web/src/context/dapi/voices.ts
rename to apps/web/src/dapi/handlers/voices.ts
index 9109a8d0..65fd8982 100644
--- a/apps/web/src/context/dapi/voices.ts
+++ b/apps/web/src/dapi/handlers/voices.ts
@@ -4,12 +4,8 @@
import { PROMPT_INPUT_VOICE_OPTIONS } from "@/components/genai/config";
-export function handleVoices() {
- return async () => {
- return PROMPT_INPUT_VOICE_OPTIONS.map((v) => ({
- id: v.value,
- label: v.label,
- description: v.description,
- }));
- }
-}
+import type { ToolHandler } from "../handler";
+
+export const voices: ToolHandler<"voices"> = async () => ({
+ voices: PROMPT_INPUT_VOICE_OPTIONS.map((v) => ({ id: v.value, label: v.label, description: v.description })),
+});
diff --git a/apps/web/src/dapi/handlers/whoami.ts b/apps/web/src/dapi/handlers/whoami.ts
new file mode 100644
index 00000000..a23daaa7
--- /dev/null
+++ b/apps/web/src/dapi/handlers/whoami.ts
@@ -0,0 +1,7 @@
+/* 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 { ToolHandler } from "../handler";
+
+export const whoami: ToolHandler<"whoami"> = async (_, ctx) => ({ user: ctx.app.user() });
diff --git a/apps/web/src/context/dapi/index.ts b/apps/web/src/dapi/index.ts
similarity index 75%
rename from apps/web/src/context/dapi/index.ts
rename to apps/web/src/dapi/index.ts
index b86dc190..3d31fac2 100644
--- a/apps/web/src/context/dapi/index.ts
+++ b/apps/web/src/dapi/index.ts
@@ -2,4 +2,4 @@
* 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/. */
-export * from './api';
+export { EditorApi, EditorApiProvider, useEditorApi } from "./api";
diff --git a/apps/web/src/dapi/lib/assets.ts b/apps/web/src/dapi/lib/assets.ts
new file mode 100644
index 00000000..08e54f3c
--- /dev/null
+++ b/apps/web/src/dapi/lib/assets.ts
@@ -0,0 +1,41 @@
+/* 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 { getLibrary } from "@diffusionstudio/runtime";
+import { AssetLibrary, isAbsoluteSource, isUrlSource } from "@diffusionstudio/assets";
+import { DapiError } from "@diffusionstudio/dapi";
+import { createProjectFS } from "@/projects/fs";
+
+import type { Asset } from "@diffusionstudio/assets";
+import type { ToolContext } from "../handler";
+
+/**
+ * Resolves a tool target by path. With a project open, its library answers:
+ * library paths look assets up, absolute paths and URLs are described in place
+ * without being added (transient assets). With none open, a throwaway library
+ * over a project-less FS describes absolute paths and URLs the same way — a
+ * fresh one per request, so nothing is remembered between calls.
+ */
+export function resolveAsset(ctx: ToolContext, path: string): Promise<Asset> {
+ const world = ctx.session()?.world;
+ if (world) return getLibrary(world).resolve(path);
+ if (!isAbsoluteSource(path) && !isUrlSource(path)) {
+ throw new DapiError(
+ "no-project",
+ `Could not resolve "${path}": with no project open only absolute paths and URLs resolve — open a project to use library paths.`,
+ );
+ }
+ return new AssetLibrary(createProjectFS("")).resolve(path);
+}
+
+/** Narrows the asset to one of `types`, or throws a `wrong-kind` error naming what was expected. */
+export function requireAssetType<T extends Asset["type"]>(
+ asset: Asset,
+ types: readonly T[],
+ expected: string,
+): asserts asset is Extract<Asset, { type: T }> {
+ if (!(types as readonly string[]).includes(asset.type)) {
+ throw new DapiError("wrong-kind", `Asset ${asset.id} is not ${expected}.`);
+ }
+}
diff --git a/apps/web/src/context/dapi/frame-triage.ts b/apps/web/src/dapi/lib/frame-triage.ts
similarity index 100%
rename from apps/web/src/context/dapi/frame-triage.ts
rename to apps/web/src/dapi/lib/frame-triage.ts
diff --git a/apps/web/src/context/dapi/nodes.ts b/apps/web/src/dapi/lib/nodes.ts
similarity index 58%
rename from apps/web/src/context/dapi/nodes.ts
rename to apps/web/src/dapi/lib/nodes.ts
index 690fb67d..e93772df 100644
--- a/apps/web/src/context/dapi/nodes.ts
+++ b/apps/web/src/dapi/lib/nodes.ts
@@ -4,10 +4,11 @@
import { AdjustmentLayer, Geometry, Group, Scene, Source } from "@diffusionstudio/runtime";
import { parseSource } from "@diffusionstudio/jsx";
+import { DapiError } from "@diffusionstudio/dapi";
import type { Entity, World } from "koota";
-// Scenes are nodes too, so node-targeting endpoints accept them alongside
+// Scenes are nodes too, so node-targeting tools accept them alongside
// geometry, groups, and adjustment layers.
export function isNode(entity: Entity): boolean {
return entity.has(Geometry)
@@ -16,13 +17,7 @@ export function isNode(entity: Entity): boolean {
|| entity.has(Scene);
}
-/**
- * The entity `id` names. An id is a source id — the durable name an element
- * carries in the project's JSX — not a koota entity number, which is minted
- * anew on every recompile and so names nothing across calls. The bare id is
- * enough while it names one element; `file:id` settles a tie between files,
- * and a positional stamp (`index.tsx:12`) addresses elements that have no id.
- */
+/** The one node an id names, or the error that says why there is not exactly one. */
export function resolveNode(world: World, id: string): Entity {
const matches = world.query(Source).filter((entity) => {
const stamp = entity.get(Source)!.value;
@@ -31,20 +26,23 @@ export function resolveNode(world: World, id: string): Entity {
return parsed !== undefined && String(parsed.locator) === id;
});
if (!matches.length) {
- throw new Error(`No such node: "${id}" — node ids are the id attributes in the project's JSX`);
+ throw new DapiError("not-found", `No such node: "${id}" — node ids are the id attributes in the project's JSX`);
}
const nodes = matches.filter(isNode);
if (!nodes.length) {
- throw new Error(`"${id}" is not a node; target a scene, group, clip, or adjustment layer`);
+ throw new DapiError("wrong-kind", `"${id}" is not a node; target a scene, group, clip, or adjustment layer`);
}
if (nodes.length > 1) {
const stamps = [...new Set(nodes.map((node) => node.get(Source)!.value))];
if (stamps.length === 1) {
// One element, many entities: a loop renders its body once per item.
- throw new Error(`"${id}" renders ${nodes.length} times (it sits in a loop) — target its scene instead`);
+ throw new DapiError("ambiguous", `"${id}" renders ${nodes.length} times (it sits in a loop) — target its scene instead`);
}
- throw new Error(`"${id}" is ambiguous between ${stamps.map((stamp) => `"${stamp}"`).join(", ")} — use the file:id form`);
+ throw new DapiError(
+ "ambiguous",
+ `"${id}" is ambiguous between ${stamps.map((stamp) => `"${stamp}"`).join(", ")} — use the file:id form`,
+ );
}
return nodes[0]!;
}
diff --git a/apps/web/src/dapi/lib/png.ts b/apps/web/src/dapi/lib/png.ts
new file mode 100644
index 00000000..a0973f95
--- /dev/null
+++ b/apps/web/src/dapi/lib/png.ts
@@ -0,0 +1,9 @@
+/* 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/. */
+
+/** The bytes of a `data:` URL, for previews the runtime renders that way. */
+export function dataUrlToBytes(dataUrl: string): Uint8Array {
+ const base64 = dataUrl.slice(dataUrl.indexOf(",") + 1);
+ return Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+}
diff --git a/apps/web/src/dapi/lib/scene.ts b/apps/web/src/dapi/lib/scene.ts
new file mode 100644
index 00000000..d62c79fc
--- /dev/null
+++ b/apps/web/src/dapi/lib/scene.ts
@@ -0,0 +1,37 @@
+/* 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 { getParentNode, isScene, Source } from "@diffusionstudio/runtime";
+import { DapiError } from "@diffusionstudio/dapi";
+import { resolveNode } from "./nodes";
+
+import type { Entity, World } from "koota";
+
+/**
+ * The scene an id names. A scene is the unit an export renders, and capture's
+ * promise is that its frames are an export's frames, so both take scenes only:
+ * framing an arbitrary node would need its bounds measured across the
+ * requested positions first, and that pre-roll runs the project's code ahead
+ * of the frames being drawn, which is exactly what an export never does.
+ *
+ * `verb` names the caller in the error ("capture", "export").
+ */
+export function requireScene(world: World, id: string, verb: string): Entity {
+ const node = resolveNode(world, id);
+ if (isScene(node)) return node;
+
+ let scene = getParentNode(node);
+ while (scene !== null && !isScene(scene)) scene = getParentNode(scene);
+ const stamp = scene?.get(Source)?.value;
+ throw new DapiError(
+ "wrong-kind",
+ stamp
+ ? `"${id}" is not a scene — ${verb} renders what an export renders. ${capitalize(verb)} its scene "${stamp}" instead.`
+ : `"${id}" is not a scene — ${verb} renders what an export renders, so it takes a scene id.`,
+ );
+}
+
+function capitalize(word: string): string {
+ return word.charAt(0).toUpperCase() + word.slice(1);
+}
diff --git a/apps/web/src/dapi/lib/sheets.ts b/apps/web/src/dapi/lib/sheets.ts
new file mode 100644
index 00000000..76647f3b
--- /dev/null
+++ b/apps/web/src/dapi/lib/sheets.ts
@@ -0,0 +1,87 @@
+/* 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 { composeSheet, planSheet, planSheetSizes, sheetTimecode } from "@diffusionstudio/encoder";
+
+import type { SheetPlan } from "@diffusionstudio/encoder";
+import type { TimecodedImage } from "@diffusionstudio/dapi";
+
+export type SheetFrame = {
+ /** Where the frame sits, in the caller's clock; orders cells within a sheet's label. */
+ at: number;
+ timecode: string;
+ image: CanvasImageSource;
+};
+
+/**
+ * Lays `total` frames out over contact sheets and composes each sheet as
+ * soon as its last frame arrives, so a long run never holds every frame at
+ * once. Frames may arrive in any order; sheets come out in order.
+ *
+ * Plans are made up front from the frames' source size so the caller can
+ * decode or render no larger than a cell will be drawn (see `cellWidth`,
+ * `cellHeight`).
+ */
+export class SheetCollector {
+ readonly plans: SheetPlan[];
+ /** The largest cell across sheets: nothing needs to be bigger than this. */
+ readonly cellWidth: number;
+ readonly cellHeight: number;
+
+ private readonly sizes: number[];
+ private readonly sheetOf: number[] = [];
+ private readonly firstIndex: number[] = [];
+ private readonly missing: number[];
+ private readonly frames: Array<SheetFrame | undefined>;
+ private readonly sheets: Array<TimecodedImage | undefined>;
+
+ constructor(total: number, source: { width: number; height: number }, perSheet?: number) {
+ const sizes = planSheetSizes(total, perSheet);
+ this.sizes = sizes;
+ this.plans = sizes.map((size) => planSheet(size, source));
+ this.cellWidth = Math.max(...this.plans.map((plan) => plan.cellWidth));
+ this.cellHeight = Math.max(...this.plans.map((plan) => plan.cellHeight));
+ for (const [sheet, size] of sizes.entries()) {
+ this.firstIndex.push(this.sheetOf.length);
+ for (let k = 0; k < size; k++) this.sheetOf.push(sheet);
+ }
+ this.missing = [...sizes];
+ this.frames = new Array(total);
+ this.sheets = new Array(sizes.length);
+ }
+
+ /**
+ * Adds the frame at `index` (its position in the requested order). When it
+ * completes a sheet, that sheet is composed and its images released:
+ * ImageBitmaps are closed, and every frame image is dropped from memory.
+ */
+ async add(index: number, frame: SheetFrame): Promise<void> {
+ this.frames[index] = frame;
+ const sheet = this.sheetOf[index]!;
+ if (--this.missing[sheet]! > 0) return;
+
+ const from = this.firstIndex[sheet]!;
+ const to = from + this.sizes[sheet]!;
+ const cells = this.frames.slice(from, to).filter((f): f is SheetFrame => f !== undefined);
+ this.sheets[sheet] = {
+ timecode: sheetTimecode(cells),
+ png: await composeSheet(
+ cells.map((cell) => ({ image: cell.image, label: cell.timecode })),
+ this.plans[sheet]!,
+ ),
+ };
+ for (const cell of cells) {
+ if (cell.image instanceof ImageBitmap) cell.image.close();
+ }
+ this.frames.fill(undefined, from, to);
+ }
+
+ /** Every sheet, in order. Only complete once every frame has been added. */
+ result(): TimecodedImage[] {
+ return this.sheets.map((sheet, i) => {
+ if (!sheet) throw new Error(`Contact sheet ${i} is missing frames`);
+ return sheet;
+ });
+ }
+}
diff --git a/apps/web/src/context/dapi/session.ts b/apps/web/src/dapi/session.ts
similarity index 70%
rename from apps/web/src/context/dapi/session.ts
rename to apps/web/src/dapi/session.ts
index 4b4d1429..8a7819ae 100644
--- a/apps/web/src/context/dapi/session.ts
+++ b/apps/web/src/dapi/session.ts
@@ -2,13 +2,13 @@
* 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/. */
-// The CLI router mounts once for the app's lifetime (see ./api); what changes
-// as projects open and close is this slot. The editor publishes its world and
-// project here while it is mounted, and project-bound endpoints read the slot
-// per request instead of closing over a world at registration time.
+// The tool handlers register once for the app's lifetime (see ./api); what
+// changes as projects open and close is this slot. The editor publishes its
+// world and project here while it is mounted, and project-bound handlers read
+// the slot per request instead of closing over a world at registration time.
import { createSignal } from "solid-js";
-import { assert } from "@/utils/common";
+import { DapiError } from "@diffusionstudio/dapi";
import type { Accessor } from "solid-js";
import type { World } from "koota";
@@ -34,9 +34,9 @@ export const editorSession: Accessor<EditorSession | null> = session;
/** Set by the editor while a project is open; cleared on its way out. */
export const setEditorSession = setSession;
-/** The session, or the failure a CLI caller can act on. */
+/** The session, or the failure a caller can act on. */
export function requireEditorSession(): EditorSession {
const current = session();
- assert(current, "No project open — run `dapi open <dir>` first.");
+ if (!current) throw new DapiError("no-project", "No project open — open one first (`dapi open <dir>`).");
return current;
}
diff --git a/apps/web/src/hooks/use-fullscreen-state.ts b/apps/web/src/hooks/use-fullscreen-state.ts
index 8823fcbe..e407d1b1 100644
--- a/apps/web/src/hooks/use-fullscreen-state.ts
+++ b/apps/web/src/hooks/use-fullscreen-state.ts
@@ -4,7 +4,6 @@
import { createEffect, createResource, onCleanup, onMount } from "solid-js";
-import { handleGetFullscreenState, handleWindowFullscreenChange } from "@/context/dapi/window";
import { mainBridge } from "@/lib/ipc";
import { MAIN_CHANNELS } from "@desktop/main-channels";
@@ -18,9 +17,10 @@ import { MAIN_CHANNELS } from "@desktop/main-channels";
* lives here rather than inside the editor-only API provider.
*/
export function useFullscreenState() {
- const [isFullscreen, { mutate }] = createResource(handleGetFullscreenState, {
- initialValue: false,
- });
+ const [isFullscreen, { mutate }] = createResource(
+ () => (window.desktop ? mainBridge.call(MAIN_CHANNELS.WINDOW_IS_FULLSCREEN, undefined) : Promise.resolve(false)),
+ { initialValue: false },
+ );
createEffect(() => {
document.documentElement.dataset.fullscreen = String(isFullscreen());
@@ -29,10 +29,7 @@ export function useFullscreenState() {
onMount(() => {
if (!window.desktop) return;
onCleanup(
- mainBridge.handle(
- MAIN_CHANNELS.WINDOW_FULLSCREEN_CHANGE,
- handleWindowFullscreenChange(mutate),
- ),
+ mainBridge.handle(MAIN_CHANNELS.WINDOW_FULLSCREEN_CHANGE, ({ fullscreen }) => mutate(fullscreen)),
);
});
diff --git a/apps/web/src/lib/cli-rpc.ts b/apps/web/src/lib/cli-rpc.ts
deleted file mode 100644
index dbaf1e12..00000000
--- a/apps/web/src/lib/cli-rpc.ts
+++ /dev/null
@@ -1,45 +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/. */
-
-import { initTRPC } from "@trpc/server";
-import type { AnyTRPCRouter } from "@trpc/server";
-import type { ProcedureCaller, RouterCaller } from "./ipc";
-
-// tRPC instance for the CLI-facing routers. Procedures close over their
-// dependencies (engine, session), so there is no request context. The
-// renderer IS the server here, so opt out of tRPC's browser guard.
-export const t = initTRPC.create({ allowOutsideOfServer: true });
-
-// Inputs come pre-typed from the tRPC client, so parsers are identity casts
-// rather than schemas; validation stays where it always was, in the handlers.
-const input =
- <I,>() =>
- (value: unknown) =>
- value as I;
-
-// Lift an existing unary handler into a procedure, inferring its input and
-// output types. The cast collapses tRPC's conditional input type, which
-// stays unresolved for a generic I. Zero-argument handlers use q0/m0: they
-// skip .input() so the client can call them without an argument.
-export const q = <O, I>(fn: (data: I) => O | Promise<O>) =>
- t.procedure.input(input<I>()).query(({ input: data }) => fn(data as I));
-
-export const m = <O, I>(fn: (data: I) => O | Promise<O>) =>
- t.procedure.input(input<I>()).mutation(({ input: data }) => fn(data as I));
-
-export const q0 = <O,>(fn: () => O | Promise<O>) => t.procedure.query(() => fn());
-
-export const m0 = <O,>(fn: () => O | Promise<O>) => t.procedure.mutation(() => fn());
-
-// Adapts a router for the CLI bridge: resolve a dot-joined procedure path to
-// an invocable, or undefined when this router doesn't own the path (the
-// bridge then tries other routers or holds the request).
-export function createRouterCaller(router: AnyTRPCRouter): RouterCaller {
- const caller = t.createCallerFactory(router)({});
- return (path: string): ProcedureCaller | undefined => {
- if (!(path in router._def.procedures)) return undefined;
- return (data: unknown) =>
- path.split(".").reduce<any>((o, key) => o[key], caller)(data) as Promise<unknown>;
- };
-}
diff --git a/apps/web/src/lib/desktop-app.ts b/apps/web/src/lib/desktop-app.ts
index ba502898..160e4e49 100644
--- a/apps/web/src/lib/desktop-app.ts
+++ b/apps/web/src/lib/desktop-app.ts
@@ -16,7 +16,7 @@ const DOWNLOAD_URL =
"https://github.com/diffusionstudio/editor/releases/latest/download/Diffusion-Studio-arm64.dmg";
/** Where a download was started from, so the promos can be compared. */
-export type DesktopAppDownloadSource = "canvas_banner" | "dashboard_footer" | "main_menu" | "onboarding";
+export type DesktopAppDownloadSource = "canvas_banner" | "dashboard_footer" | "main_menu";
function isMacOS() {
const uaData = (navigator as { userAgentData?: { platform?: string } }).userAgentData;
diff --git a/apps/web/src/lib/ipc.ts b/apps/web/src/lib/ipc.ts
index 98b61761..090b6359 100644
--- a/apps/web/src/lib/ipc.ts
+++ b/apps/web/src/lib/ipc.ts
@@ -12,23 +12,15 @@ import type {
MainRequestChannel,
MainRequestMap,
} from "@desktop/main-channels";
-import { CLI_WIRE } from "@diffusionstudio/cli/channels";
-import type { CliHandshake, CliReply, CliRequest } from "@diffusionstudio/cli/channels";
type EventHandler<C extends MainEventChannel> = (data: MainEventMap[C]) => void;
-export type ProcedureCaller = (input: unknown) => Promise<unknown>;
-
-// Resolves a dot-joined tRPC procedure path to an invocable, or undefined
-// when the router doesn't own that path.
-export type RouterCaller = (path: string) => ProcedureCaller | undefined;
-
type Pending = {
resolve: (value: unknown) => void;
reject: (error: Error) => void;
};
-// Renderer↔main bridge. Symmetric with cliBridge: `handle` registers a
+// Renderer↔main bridge: `handle` registers a
// single-subscriber receiver for inbound channels (events from main); `call`
// sends a request to main and awaits the reply.
class MainBridge {
@@ -94,87 +86,3 @@ class MainBridge {
}
export const mainBridge = new MainBridge();
-
-type PendingCliRequest = { req: CliRequest; ws: WebSocket };
-
-// CLI bridge — answers CLI requests. Each CLI command hosts a short-lived
-// WebSocket server; main relays only the connect info (CLI_WIRE.CONNECT) and
-// we dial the CLI directly, so payloads never pass through main. One request
-// and one reply per connection. The bridge is transport-only: the tRPC
-// router registers as a path resolver, and requests arriving before it
-// mounts (or between remounts on project switches) are held and retried on
-// the next registration — no explicit ready signal needed.
-class CliBridge {
- // Several routers coexist: the shell router (always mounted, owns `ping`
- // and `open`) and the editor router (mounted per open project). Paths are
- // disjoint; a request is answered by whichever router owns its path.
- private routers = new Set<RouterCaller>();
- private pending: PendingCliRequest[] = [];
-
- constructor() {
- // Bind eagerly so CONNECT arrivals during page bootstrap are caught
- // rather than silently dropped before any router registers.
- if (window.desktop) {
- window.desktop.on(CLI_WIRE.CONNECT, (payload) => {
- const { port, token } = payload as CliHandshake;
- const ws = new WebSocket(`ws://127.0.0.1:${port}/?token=${token}`);
- ws.onmessage = (event) => {
- try {
- const req = JSON.parse(event.data as string) as CliRequest;
- void this.dispatch({ req, ws });
- } catch (err) {
- console.error("[cli-bridge] malformed CLI request", err);
- ws.close();
- }
- };
- });
- }
- }
-
- private resolve(path: string): ProcedureCaller | undefined {
- for (const router of this.routers) {
- const proc = router(path);
- if (proc) return proc;
- }
- return undefined;
- }
-
- private async dispatch(pending: PendingCliRequest): Promise<void> {
- const { req, ws } = pending;
- const proc = this.resolve(req.path);
- if (!proc) {
- this.pending.push(pending);
- return;
- }
- let reply: CliReply;
- try {
- const data = await proc(req.input);
- reply = { ok: true, data };
- } catch (err) {
- reply = { ok: false, error: (err as Error).message };
- }
- try {
- ws.send(JSON.stringify(reply));
- } catch (err) {
- ws.send(
- JSON.stringify({
- ok: false,
- error: `Failed to serialize reply for ${req.path}: ${(err as Error).message}`,
- }),
- );
- }
- }
-
- register(router: RouterCaller): () => void {
- if (!window.desktop) return () => {};
- this.routers.add(router);
- const held = this.pending;
- this.pending = [];
- for (const pending of held) void this.dispatch(pending);
- return () => {
- this.routers.delete(router);
- };
- }
-}
-
-export const cliBridge = new CliBridge();
diff --git a/apps/web/src/pages/editor.tsx b/apps/web/src/pages/editor.tsx
index 81e054ef..1c3d9437 100644
--- a/apps/web/src/pages/editor.tsx
+++ b/apps/web/src/pages/editor.tsx
@@ -8,7 +8,7 @@ import { Timeline, Layers } from "@/components/timeline";
import { Soundboard, Inspector } from "@/components/sidebar-right";
import { FloatingProjectHeader, SidebarLeft } from "@/components/sidebar-left";
import { useLayout, MIN_TIMELINE_HEIGHT } from "@/context/layout";
-import { useEditorApi } from "@/context/dapi";
+import { useEditorApi } from "@/dapi";
import { RULER_HEIGHT } from "@/engine/timeline";
import { createEffect, onCleanup, untrack } from 'solid-js';
import { toast } from 'somoto';
diff --git a/apps/web/src/pages/onboarding.tsx b/apps/web/src/pages/onboarding.tsx
deleted file mode 100644
index 268dc3e9..00000000
--- a/apps/web/src/pages/onboarding.tsx
+++ /dev/null
@@ -1,260 +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/. */
-
-import { createSignal, onMount, Show } from 'solid-js';
-import type { JSX } from 'solid-js';
-import { toast } from 'somoto';
-
-import { MAIN_CHANNELS } from '@desktop/main-channels';
-import { Button } from '@/components/ui/button';
-import { Icon } from '@/components/ui/icon';
-import { downloadDesktopApp } from '@/lib/desktop-app';
-import { createStoredSignal } from '@/lib/store';
-import { mainBridge } from '@/lib/ipc';
-import { track } from '@/lib/analytics';
-import { store } from '@/init';
-
-const SKILLS_COMMAND = 'npx skills add diffusionstudio/skills -g -y --all';
-
-const [onboardingCompleted, setOnboardingCompleted] = createStoredSignal(
- store.define('onboarding.completed', false),
-);
-
-export { onboardingCompleted };
-
-type StepState = 'todo' | 'busy' | 'done';
-
-type SetupRowProps = {
- title: string;
- description: string;
- action: JSX.Element;
-};
-
-function SetupRow(props: SetupRowProps) {
- return (
- <div class="flex items-center gap-4">
- <div class="flex min-w-0 flex-1 flex-col gap-1">
- <p class="text-xs text-foreground">{props.title}</p>
- <p class="text-xs text-muted-foreground">{props.description}</p>
- </div>
- {props.action}
- </div>
- );
-}
-
-type StepButtonProps = {
- state: StepState;
- label: string;
- busyLabel?: string;
- doneLabel: string;
- onClick: () => void;
-};
-
-function StepButton(props: StepButtonProps) {
- return (
- <Show
- when={props.state !== 'done'}
- fallback={
- <Button variant="on" class="pointer-events-none">
- {props.doneLabel}
- </Button>
- }
- >
- <Button
- variant="secondary"
- disabled={props.state === 'busy'}
- onClick={props.onClick}
- >
- {props.state === 'busy' ? props.busyLabel ?? props.label : props.label}
- </Button>
- </Show>
- );
-}
-
-/**
- * Post-signup screen for setting up the agent dependencies: the dapi CLI and
- * the agent skills. Shown by AuthGate until dismissed; the dismissal is
- * per-device (same store as the promo banners).
- *
- * On desktop the CLI button links the bundled CLI into PATH via main (the
- * same flow as the "Install dapi Command Line Tool…" menu item); on the web,
- * where the CLI can't be installed, it offers the desktop app instead.
- */
-export function OnboardingPage() {
- const isDesktop = !!window.desktop;
- const [cliState, setCliState] = createSignal<StepState>('todo');
- const [skillsState, setSkillsState] = createSignal<StepState>('todo');
-
- onMount(async () => {
- if (!isDesktop) return;
- try {
- const [cli, skills] = await Promise.all([
- mainBridge.call(MAIN_CHANNELS.CLI_IS_INSTALLED, undefined),
- mainBridge.call(MAIN_CHANNELS.SKILLS_IS_INSTALLED, undefined),
- ]);
- if (cli) setCliState('done');
- if (skills) setSkillsState('done');
- } catch {
- // Can't tell — leave the install buttons available.
- }
- });
-
- const installCli = async () => {
- setCliState('busy');
- try {
- const result = await mainBridge.call(MAIN_CHANNELS.CLI_INSTALL, undefined);
- if (result.status === 'installed') {
- track('onboarding_cli_installed');
- setCliState('done');
- } else {
- setCliState('todo');
- if (result.status === 'error') {
- toast('Could not install the dapi CLI', { description: result.error });
- }
- }
- } catch (error) {
- setCliState('todo');
- toast('Could not install the dapi CLI', {
- description: error instanceof Error ? error.message : 'Unknown error',
- });
- }
- };
-
- const downloadApp = () => {
- downloadDesktopApp('onboarding');
- setCliState('done');
- };
-
- const copySkillsCommand = async () => {
- try {
- await navigator.clipboard.writeText(SKILLS_COMMAND);
- track('onboarding_skills_copied');
- setSkillsState('done');
- toast('Copied!', {
- description: 'Run the command in your terminal to install the agent skills.',
- });
- } catch (error) {
- toast('Failed to copy', {
- description: error instanceof Error ? error.message : 'Unknown error',
- });
- }
- };
-
- const installSkills = async () => {
- setSkillsState('busy');
- try {
- const result = await mainBridge.call(MAIN_CHANNELS.SKILLS_INSTALL, undefined);
- if (result.status === 'installed') {
- track('onboarding_skills_installed');
- setSkillsState('done');
- return;
- }
- setSkillsState('todo');
- toast('Could not install the agent skills', { description: result.error });
- } catch (error) {
- setSkillsState('todo');
- toast('Could not install the agent skills', {
- description: error instanceof Error ? error.message : 'Unknown error',
- });
- }
- };
-
- const allDone = () => cliState() === 'done' && skillsState() === 'done';
-
- const finish = (event: 'onboarding_completed' | 'onboarding_skipped') => {
- track(event);
- setOnboardingCompleted(true);
- };
-
- return (
- <div class="flex flex-col bg-background fixed inset-0 z-999">
- <Show when={!isDesktop}>
- <div class="flex items-center gap-1 p-4">
- <Icon name="diffusion-logo" class="size-6" />
- <span class="text-sm font-450 text-foreground">Diffusion Studio</span>
- </div>
- </Show>
-
- <div class="flex flex-1 items-center justify-center pb-16">
- <div class="flex w-124 max-w-[calc(100vw-2rem)] flex-col gap-6">
- <div class="flex flex-col">
- <div class="flex flex-col gap-1 px-2 pt-2 pb-3">
- <h2 class="text-[12px] font-450 text-foreground">Connect your agent</h2>
- <p class="text-xs text-muted-foreground">
- Edit videos with coding agents like Claude Code, Codex, or Cursor.
- </p>
- </div>
-
- <div class="flex flex-col gap-3 rounded-xl bg-accent/40 p-4">
- <SetupRow
- title="dapi CLI"
- description={
- isDesktop
- ? 'The command line tool for agents to control the editor.'
- : 'The command line tool for agents. Ships with the desktop app.'
- }
- action={
- isDesktop ? (
- <StepButton
- state={cliState()}
- label="Install"
- busyLabel="Installing…"
- doneLabel="Installed"
- onClick={installCli}
- />
- ) : (
- <StepButton
- state={cliState()}
- label="Get app"
- doneLabel="Downloaded"
- onClick={downloadApp}
- />
- )
- }
- />
-
- <div class="h-px w-full bg-border" />
-
- <SetupRow
- title="Agent skills"
- description="Instructions that help agents edit videos through dapi."
- action={
- isDesktop ? (
- <StepButton
- state={skillsState()}
- label="Install"
- busyLabel="Installing…"
- doneLabel="Installed"
- onClick={installSkills}
- />
- ) : (
- <StepButton
- state={skillsState()}
- label="Copy command"
- doneLabel="Copied"
- onClick={copySkillsCommand}
- />
- )
- }
- />
- </div>
- </div>
-
- <div class="flex items-center gap-2 px-2">
- <Button disabled={!allDone()} onClick={() => finish('onboarding_completed')}>
- Get started
- </Button>
- <Button
- variant="ghost"
- class="text-muted-foreground"
- onClick={() => finish('onboarding_skipped')}
- >
- Setup later
- </Button>
- </div>
- </div>
- </div>
- </div>
- );
-}
diff --git a/apps/web/src/pages/project.tsx b/apps/web/src/pages/project.tsx
index f6cf3ada..f0ff44ca 100644
--- a/apps/web/src/pages/project.tsx
+++ b/apps/web/src/pages/project.tsx
@@ -7,7 +7,7 @@ import { Navigate, useNavigate } from '@solidjs/router';
import { EditorPage } from './editor';
import { LayoutProvider } from "@/context/layout";
import { PromptInputProvider } from "@/context/prompt-input";
-import { EditorApiProvider } from '@/context/dapi';
+import { EditorApiProvider } from '@/dapi';
import { ExportProvider } from '@/context/export';
import { ProjectProvider } from '@/context/project';
import { projectRoute, useProjectRef } from '@/hooks/use-project-route';
diff --git a/knowledge/INSTRUCTIONS.md b/knowledge/INSTRUCTIONS.md
new file mode 100644
index 00000000..6143e6d0
--- /dev/null
+++ b/knowledge/INSTRUCTIONS.md
@@ -0,0 +1,5 @@
+Diffusion Studio, a video editor, is running on this machine and you are connected to it.
+
+Projects are folders of JSX; `open` a folder once, then write its files and save — the app recompiles and re-renders.
+
+The tools are the whole API, and their descriptions are authoritative. The same tools exist as `dapi` commands for shells and scripts: `media_grab` is `dapi media grab`, a field like `perSheet` is `--per-sheet`, and the result is the same JSON either way. Each tool is documented once for both under `dapi://reference/tools/`.
diff --git a/knowledge/brand/README.md b/knowledge/brand/README.md
new file mode 100644
index 00000000..fb49048d
--- /dev/null
+++ b/knowledge/brand/README.md
@@ -0,0 +1,26 @@
+# Diffusion Studio brand
+
+The fallback brand system: use it only when the brief, the project, or the user
+supplies no branding of their own. Any branding they do specify wins.
+
+When it applies, these references are the source of truth, and the bundled
+library comes before anything newly made.
+
+## Read the relevant references
+
+| Task | Read |
+| --- | --- |
+| Visual design or graphics | `design.md` |
+| Copy or writing | `voice.md` |
+| Video | `design.md`, `video.md`, `library.md` |
+| Assets, components, or compositions | `library.md` and the reference for its medium |
+
+When work spans multiple rows, use each relevant reference.
+
+## Apply the system
+
+1. Check `library.md` before creating a brand asset, component, or composition.
+2. Reuse the closest existing item and change its content or inputs.
+3. Use relative paths to bundled assets instead of external file-share links.
+4. Do not invent product facts, claims, assets, or brand rules.
+5. Report missing inputs, deliberate exceptions, and reusable work that should join the library.
diff --git a/knowledge/brand/assets/audio/music/.gitkeep b/knowledge/brand/assets/audio/music/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/knowledge/brand/assets/audio/music/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/knowledge/brand/assets/audio/sfx/.gitkeep b/knowledge/brand/assets/audio/sfx/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/knowledge/brand/assets/audio/sfx/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/knowledge/brand/assets/audio/voiceovers/.gitkeep b/knowledge/brand/assets/audio/voiceovers/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/knowledge/brand/assets/audio/voiceovers/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/knowledge/brand/assets/components/callout.tsx b/knowledge/brand/assets/components/callout.tsx
new file mode 100644
index 00000000..93da2806
--- /dev/null
+++ b/knowledge/brand/assets/components/callout.tsx
@@ -0,0 +1,67 @@
+import type { Time } from "@diffusionstudio/jsx";
+import { colors, fonts, frameMetrics, typography } from "./tokens";
+
+export type CalloutProps = {
+ width: number;
+ height: number;
+ start: Time;
+ end: Time;
+ label: string;
+ value: string;
+};
+
+export function Callout(props: CalloutProps) {
+ const frame = frameMetrics(props.width, props.height);
+ const panelWidth = Math.min(560 * frame.scale, frame.right - frame.left);
+ const panelHeight = 152 * frame.scale;
+ const panelTop = frame.bottom - panelHeight;
+
+ return (
+ <>
+ <rect
+ name="Callout panel"
+ start={props.start}
+ end={props.end}
+ x={frame.left}
+ y={panelTop}
+ width={panelWidth}
+ height={panelHeight}
+ fill={colors.surface}
+ />
+ <text
+ name="Callout label"
+ start={props.start}
+ end={props.end}
+ x={frame.left + 24 * frame.scale}
+ y={panelTop + 24 * frame.scale}
+ width={panelWidth - 48 * frame.scale}
+ height={32 * frame.scale}
+ textAlign="left"
+ textBaseline="top"
+ fontFamily={fonts.sans}
+ fontSize={typography.label.size * frame.scale}
+ fontWeight={typography.label.weight}
+ color={colors.textSecondary}
+ >
+ {props.label}
+ </text>
+ <text
+ name="Callout value"
+ start={props.start}
+ end={props.end}
+ x={frame.left + 24 * frame.scale}
+ y={panelTop + 72 * frame.scale}
+ width={panelWidth - 48 * frame.scale}
+ height={56 * frame.scale}
+ textAlign="left"
+ textBaseline="top"
+ fontFamily={fonts.sans}
+ fontSize={typography.lowerThirdName.size * frame.scale}
+ fontWeight={typography.lowerThirdName.weight}
+ color={colors.text}
+ >
+ {props.value}
+ </text>
+ </>
+ );
+}
diff --git a/knowledge/brand/assets/components/lower-third.tsx b/knowledge/brand/assets/components/lower-third.tsx
new file mode 100644
index 00000000..667db4fc
--- /dev/null
+++ b/knowledge/brand/assets/components/lower-third.tsx
@@ -0,0 +1,69 @@
+import type { Time } from "@diffusionstudio/jsx";
+import { colors, fonts, frameMetrics, typography } from "./tokens";
+
+export type LowerThirdProps = {
+ width: number;
+ height: number;
+ start: Time;
+ end: Time;
+ name: string;
+ detail: string;
+};
+
+export function LowerThird(props: LowerThirdProps) {
+ const frame = frameMetrics(props.width, props.height);
+ const panelHeight = 172 * frame.scale;
+ const nameHeight = 60 * frame.scale;
+ const detailHeight = 40 * frame.scale;
+ const panelTop = frame.bottom - panelHeight;
+ const contentWidth = frame.right - frame.left;
+
+ return (
+ <>
+ <rect
+ name="Lower third panel"
+ start={props.start}
+ end={props.end}
+ x={0}
+ y={panelTop}
+ width={props.width}
+ height={panelHeight}
+ fill={colors.surface}
+ />
+ <text
+ name="Lower third name"
+ start={props.start}
+ end={props.end}
+ x={frame.left}
+ y={panelTop + 32 * frame.scale}
+ width={contentWidth}
+ height={nameHeight}
+ textAlign="left"
+ textBaseline="bottom"
+ fontFamily={fonts.sans}
+ fontSize={typography.lowerThirdName.size * frame.scale}
+ fontWeight={typography.lowerThirdName.weight}
+ color={colors.text}
+ >
+ {props.name}
+ </text>
+ <text
+ name="Lower third detail"
+ start={props.start}
+ end={props.end}
+ x={frame.left}
+ y={panelTop + 108 * frame.scale}
+ width={contentWidth}
+ height={detailHeight}
+ textAlign="left"
+ textBaseline="top"
+ fontFamily={fonts.sans}
+ fontSize={typography.lowerThirdDetail.size * frame.scale}
+ fontWeight={typography.lowerThirdDetail.weight}
+ color={colors.textSecondary}
+ >
+ {props.detail}
+ </text>
+ </>
+ );
+}
diff --git a/knowledge/brand/assets/components/media-grid.tsx b/knowledge/brand/assets/components/media-grid.tsx
new file mode 100644
index 00000000..ff98c914
--- /dev/null
+++ b/knowledge/brand/assets/components/media-grid.tsx
@@ -0,0 +1,113 @@
+import type { Fit, Time } from "@diffusionstudio/jsx";
+import { layoutMetrics } from "./tokens";
+
+export type MediaGridItem = {
+ name: string;
+ src: string;
+ sourceIn?: Time;
+ objectFit?: Fit;
+ muted: boolean;
+};
+
+export type MediaGridProps = {
+ width: number;
+ height: number;
+ start: Time;
+ end: Time;
+ items: readonly MediaGridItem[];
+ name?: string;
+};
+
+type Slot = {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ cornerRadius: number;
+};
+
+export function mediaGridSlots(width: number, height: number, count: number): Slot[] {
+ if (count !== 1 && count !== 2 && count !== 4) {
+ throw new Error(`MediaGrid needs 1, 2, or 4 items; received ${count}.`);
+ }
+
+ if (count === 1) {
+ return [{ x: 0, y: 0, width, height, cornerRadius: 0 }];
+ }
+
+ const { margin, gap, cornerRadius } = layoutMetrics(width, height);
+ const availableWidth = width - margin * 2;
+ const availableHeight = height - margin * 2;
+
+ if (count === 2) {
+ const isPortrait = height > width;
+ const size = isPortrait
+ ? Math.min(availableWidth, (availableHeight - gap) / 2)
+ : Math.min((availableWidth - gap) / 2, availableHeight);
+ const gridWidth = isPortrait ? size : size * 2 + gap;
+ const gridHeight = isPortrait ? size * 2 + gap : size;
+ const left = (width - gridWidth) / 2;
+ const top = (height - gridHeight) / 2;
+
+ return [
+ { x: left, y: top, width: size, height: size, cornerRadius },
+ {
+ x: isPortrait ? left : left + size + gap,
+ y: isPortrait ? top + size + gap : top,
+ width: size,
+ height: size,
+ cornerRadius,
+ },
+ ];
+ }
+
+ const size = Math.min((availableWidth - gap) / 2, (availableHeight - gap) / 2);
+ const gridSize = size * 2 + gap;
+ const left = (width - gridSize) / 2;
+ const top = (height - gridSize) / 2;
+
+ return [
+ { x: left, y: top, width: size, height: size, cornerRadius },
+ { x: left + size + gap, y: top, width: size, height: size, cornerRadius },
+ { x: left, y: top + size + gap, width: size, height: size, cornerRadius },
+ {
+ x: left + size + gap,
+ y: top + size + gap,
+ width: size,
+ height: size,
+ cornerRadius,
+ },
+ ];
+}
+
+export function MediaGrid(props: MediaGridProps) {
+ const slots = mediaGridSlots(props.width, props.height, props.items.length);
+ const gridName = props.name ?? "Media grid";
+
+ return (
+ <>
+ {props.items.map((item, index) => {
+ const slot = slots[index];
+
+ return (
+ <sequence name={`${gridName} — ${item.name}`}>
+ <video
+ name={item.name}
+ src={item.src}
+ start={props.start}
+ end={props.end}
+ sourceIn={item.sourceIn}
+ x={slot.x}
+ y={slot.y}
+ width={slot.width}
+ height={slot.height}
+ cornerRadius={slot.cornerRadius}
+ objectFit={item.objectFit ?? "contain"}
+ muted={item.muted}
+ />
+ </sequence>
+ );
+ })}
+ </>
+ );
+}
diff --git a/knowledge/brand/assets/components/title-card.tsx b/knowledge/brand/assets/components/title-card.tsx
new file mode 100644
index 00000000..5b2c9bbc
--- /dev/null
+++ b/knowledge/brand/assets/components/title-card.tsx
@@ -0,0 +1,63 @@
+import type { Time } from "@diffusionstudio/jsx";
+import { colors, fonts, frameMetrics, typography } from "./tokens";
+
+export type TitleCardProps = {
+ width: number;
+ height: number;
+ start: Time;
+ end: Time;
+ title: string;
+ subtitle?: string;
+};
+
+export function TitleCard(props: TitleCardProps) {
+ const frame = frameMetrics(props.width, props.height);
+ const titleHeight = 240 * frame.scale;
+ const subtitleHeight = 80 * frame.scale;
+ const gap = 24 * frame.scale;
+ const blockBottom = frame.bottom - 36 * frame.scale;
+ const subtitleTop = blockBottom - subtitleHeight;
+ const titleBottom = props.subtitle ? subtitleTop - gap : blockBottom;
+ const contentWidth = frame.right - frame.left;
+
+ return (
+ <>
+ <text
+ name="Title"
+ start={props.start}
+ end={props.end}
+ x={frame.left}
+ y={titleBottom - titleHeight}
+ width={contentWidth}
+ height={titleHeight}
+ textAlign="left"
+ textBaseline="bottom"
+ fontFamily={fonts.sans}
+ fontSize={typography.title.size * frame.scale}
+ fontWeight={typography.title.weight}
+ color={colors.text}
+ >
+ {props.title}
+ </text>
+ {props.subtitle ? (
+ <text
+ name="Subtitle"
+ start={props.start}
+ end={props.end}
+ x={frame.left}
+ y={subtitleTop}
+ width={contentWidth}
+ height={subtitleHeight}
+ textAlign="left"
+ textBaseline="top"
+ fontFamily={fonts.sans}
+ fontSize={typography.subtitle.size * frame.scale}
+ fontWeight={typography.subtitle.weight}
+ color={colors.textSecondary}
+ >
+ {props.subtitle}
+ </text>
+ ) : null}
+ </>
+ );
+}
diff --git a/knowledge/brand/assets/components/tokens.ts b/knowledge/brand/assets/components/tokens.ts
new file mode 100644
index 00000000..7a84e2f6
--- /dev/null
+++ b/knowledge/brand/assets/components/tokens.ts
@@ -0,0 +1,54 @@
+export const colors = {
+ background: "#000000",
+ surface: "#161616",
+ text: "#F8F8F8",
+ textSecondary: "#A4A4A4",
+ brandRed: "#F43535",
+} as const;
+
+export const fonts = {
+ sans: "Geist",
+ mono: "Geist Mono",
+} as const;
+
+export const typography = {
+ title: { size: 96, weight: 600 },
+ subtitle: { size: 60, weight: 400 },
+ lowerThirdName: { size: 48, weight: 500 },
+ lowerThirdDetail: { size: 30, weight: 400 },
+ label: { size: 24, weight: 500 },
+} as const;
+
+export const spacing = {
+ labelToValue: 16,
+ stackedLines: 24,
+ separateBlocks: 40,
+ margin: 64,
+ mediaGap: 40,
+ mediaCornerRadius: 24,
+} as const;
+
+export function layoutMetrics(width: number, height: number) {
+ const scale = Math.min(width, height) / 1080;
+
+ return {
+ scale,
+ margin: spacing.margin * scale,
+ gap: spacing.mediaGap * scale,
+ cornerRadius: spacing.mediaCornerRadius * scale,
+ };
+}
+
+export function frameMetrics(width: number, height: number) {
+ const { scale, margin } = layoutMetrics(width, height);
+ const isNineBySixteen = Math.abs(width / height - 9 / 16) < 0.02;
+
+ return {
+ scale,
+ margin,
+ left: margin,
+ right: isNineBySixteen ? width - 180 * scale : width - margin,
+ top: isNineBySixteen ? 200 * scale : margin,
+ bottom: isNineBySixteen ? height - 400 * scale : height - margin,
+ };
+}
diff --git a/knowledge/brand/assets/compositions/end-card.tsx b/knowledge/brand/assets/compositions/end-card.tsx
new file mode 100644
index 00000000..42b218c6
--- /dev/null
+++ b/knowledge/brand/assets/compositions/end-card.tsx
@@ -0,0 +1,37 @@
+import { TitleCard } from "../components/title-card";
+import { colors } from "../components/tokens";
+
+const WIDTH = 1080;
+const HEIGHT = 1920;
+const DURATION = 4;
+
+const inputs = {
+ title: "",
+ cta: "",
+};
+
+function requireInput(value: string, name: string) {
+ if (!value.trim()) {
+ throw new Error(`Set inputs.${name} before mounting end-card.tsx.`);
+ }
+
+ return value;
+}
+
+export default function EndCard() {
+ const title = requireInput(inputs.title, "title");
+ const cta = requireInput(inputs.cta, "cta");
+
+ return (
+ <scene id="end-card" name="End card" width={WIDTH} height={HEIGHT} fill={colors.background}>
+ <TitleCard
+ width={WIDTH}
+ height={HEIGHT}
+ start={0}
+ end={DURATION}
+ title={title}
+ subtitle={cta}
+ />
+ </scene>
+ );
+}
diff --git a/knowledge/brand/assets/compositions/product-demo.tsx b/knowledge/brand/assets/compositions/product-demo.tsx
new file mode 100644
index 00000000..fff1be84
--- /dev/null
+++ b/knowledge/brand/assets/compositions/product-demo.tsx
@@ -0,0 +1,56 @@
+import { LowerThird } from "../components/lower-third";
+import { colors } from "../components/tokens";
+
+const WIDTH = 1080;
+const HEIGHT = 1920;
+const DURATION = 6;
+
+const inputs = {
+ videoSrc: "",
+ name: "",
+ detail: "",
+};
+
+function requireInput(value: string, name: string) {
+ if (!value.trim()) {
+ throw new Error(`Set inputs.${name} before mounting product-demo.tsx.`);
+ }
+
+ return value;
+}
+
+export default function ProductDemo() {
+ const videoSrc = requireInput(inputs.videoSrc, "videoSrc");
+ const name = requireInput(inputs.name, "name");
+ const detail = requireInput(inputs.detail, "detail");
+
+ return (
+ <scene
+ id="product-demo"
+ name="Product demo"
+ width={WIDTH}
+ height={HEIGHT}
+ fill={colors.background}
+ >
+ <sequence name="Product footage">
+ <video
+ name="Product footage"
+ src={videoSrc}
+ width={WIDTH}
+ height={HEIGHT}
+ start={0}
+ end={DURATION}
+ objectFit="contain"
+ />
+ </sequence>
+ <LowerThird
+ width={WIDTH}
+ height={HEIGHT}
+ start={3}
+ end={DURATION}
+ name={name}
+ detail={detail}
+ />
+ </scene>
+ );
+}
diff --git a/knowledge/brand/assets/compositions/product-tour.tsx b/knowledge/brand/assets/compositions/product-tour.tsx
new file mode 100644
index 00000000..dd7fade3
--- /dev/null
+++ b/knowledge/brand/assets/compositions/product-tour.tsx
@@ -0,0 +1,98 @@
+import { LowerThird } from "../components/lower-third";
+import { MediaGrid } from "../components/media-grid";
+import { colors } from "../components/tokens";
+
+// Use 1920×1080, 1080×1920, or 1080×1080.
+const WIDTH = 1920;
+const HEIGHT = 1080;
+const PHASE = 3;
+const DURATION = PHASE * 4;
+
+const inputs = {
+ primaryVideoSrc: "",
+ secondaryVideoSrc: "",
+ detailVideoSrc: "",
+ fourthVideoSrc: "",
+ name: "",
+ detail: "",
+};
+
+function requireInput(value: string, name: string) {
+ if (!value.trim()) {
+ throw new Error(`Set inputs.${name} before mounting product-tour.tsx.`);
+ }
+
+ return value;
+}
+
+export default function ProductTour() {
+ const primary = requireInput(inputs.primaryVideoSrc, "primaryVideoSrc");
+ const secondary = requireInput(inputs.secondaryVideoSrc, "secondaryVideoSrc");
+ const detailVideo = requireInput(inputs.detailVideoSrc, "detailVideoSrc");
+ const fourth = requireInput(inputs.fourthVideoSrc, "fourthVideoSrc");
+ const name = requireInput(inputs.name, "name");
+ const detail = requireInput(inputs.detail, "detail");
+
+ return (
+ <scene
+ id="product-tour"
+ name="Product tour"
+ width={WIDTH}
+ height={HEIGHT}
+ fill={colors.background}
+ >
+ <MediaGrid
+ name="Full product view"
+ width={WIDTH}
+ height={HEIGHT}
+ start={0}
+ end={PHASE}
+ items={[{ name: "Primary product view", src: primary, sourceIn: 0, muted: false }]}
+ />
+
+ <MediaGrid
+ name="Two product views"
+ width={WIDTH}
+ height={HEIGHT}
+ start={PHASE}
+ end={PHASE * 2}
+ items={[
+ { name: "Primary product view", src: primary, sourceIn: PHASE, muted: false },
+ { name: "Secondary product view", src: secondary, sourceIn: 0, muted: true },
+ ]}
+ />
+
+ <MediaGrid
+ name="Four product details"
+ width={WIDTH}
+ height={HEIGHT}
+ start={PHASE * 2}
+ end={PHASE * 3}
+ items={[
+ { name: "Primary product detail", src: primary, sourceIn: PHASE * 2, muted: false },
+ { name: "Secondary product detail", src: secondary, sourceIn: 0, muted: true },
+ { name: "Third product detail", src: detailVideo, sourceIn: 0, muted: true },
+ { name: "Fourth product detail", src: fourth, sourceIn: 0, muted: true },
+ ]}
+ />
+
+ <MediaGrid
+ name="Final product view"
+ width={WIDTH}
+ height={HEIGHT}
+ start={PHASE * 3}
+ end={DURATION}
+ items={[{ name: "Primary product view", src: primary, sourceIn: PHASE * 3, muted: false }]}
+ />
+
+ <LowerThird
+ width={WIDTH}
+ height={HEIGHT}
+ start={PHASE * 3}
+ end={DURATION}
+ name={name}
+ detail={detail}
+ />
+ </scene>
+ );
+}
diff --git a/knowledge/brand/assets/fonts/.gitkeep b/knowledge/brand/assets/fonts/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/knowledge/brand/assets/fonts/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/knowledge/brand/assets/imagery/.gitkeep b/knowledge/brand/assets/imagery/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/knowledge/brand/assets/imagery/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/knowledge/brand/assets/logos/icon-white.svg b/knowledge/brand/assets/logos/icon-white.svg
new file mode 100644
index 00000000..6772da3f
--- /dev/null
+++ b/knowledge/brand/assets/logos/icon-white.svg
@@ -0,0 +1,3 @@
+<svg width="150" height="150" viewBox="0 0 150 150" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M63.0888 31.3278C70.7687 26.8907 80.2313 26.8907 87.9111 31.3278L107.089 42.4086C114.769 46.8457 119.5 55.0458 119.5 63.9196V86.0804C119.5 94.9539 114.769 103.154 107.089 107.591L87.9111 118.672C80.2313 123.109 70.7687 123.109 63.0888 118.672L43.9105 107.591C36.2309 103.154 31.5 94.9539 31.5 86.0804V63.9196C31.5 55.0458 36.2308 46.8457 43.9105 42.4086L63.0888 31.3278ZM81.8278 42.2313C77.9879 40.0131 73.2566 40.0131 69.4173 42.2313L50.2553 53.3032C46.4155 55.5218 44.0494 59.6218 44.0494 64.0586V86.1999C44.0494 90.637 46.4154 94.7369 50.2553 96.9554L69.4173 108.026C73.2566 110.245 77.9879 110.245 81.8278 108.026L100.989 96.9554C104.829 94.7369 107.195 90.637 107.195 86.1999V64.0586C107.195 59.6218 104.829 55.5217 100.989 53.3032L81.8278 42.2313Z" fill="white"/>
+</svg>
diff --git a/knowledge/brand/assets/logos/logo-white.svg b/knowledge/brand/assets/logos/logo-white.svg
new file mode 100644
index 00000000..0a88cd37
--- /dev/null
+++ b/knowledge/brand/assets/logos/logo-white.svg
@@ -0,0 +1,20 @@
+<svg width="786" height="156" viewBox="0 0 786 156" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M63.9286 33.1456C71.8245 28.5869 81.5532 28.5869 89.4492 33.1456L109.167 44.53C117.063 49.0887 121.927 57.5135 121.927 66.6305V89.3987C121.927 98.5154 117.063 106.941 109.167 111.499L89.4492 122.884C81.5532 127.442 71.8245 127.442 63.9286 122.884L44.2108 111.499C36.3152 106.941 31.4512 98.5154 31.4512 89.3987V66.6305C31.4512 57.5136 36.3151 49.0888 44.2108 44.53L63.9286 33.1456ZM83.1947 44.3479C79.2468 42.0689 74.3824 42.0688 70.4351 44.3479L50.7341 55.7232C46.7862 58.0026 44.3536 62.215 44.3536 66.7733V89.5215C44.3536 94.0801 46.7861 98.2924 50.7341 100.572L70.4351 111.946C74.3824 114.225 79.2468 114.225 83.1947 111.946L102.895 100.572C106.843 98.2924 109.276 94.0801 109.276 89.5215V66.7733C109.276 62.2149 106.843 58.0025 102.895 55.7232L83.1947 44.3479Z" fill="white"/>
+<path d="M560.702 45.6675C565.496 45.6675 569.584 46.5463 572.967 48.3042C576.349 50.062 579.021 52.4657 580.983 55.5142C582.946 58.5626 584.153 62.0481 584.606 65.9702L574.558 66.5376C574.263 64.1665 573.54 62.0764 572.39 60.2671C571.239 58.4579 569.679 57.0434 567.707 56.0249C565.735 55.0065 563.342 54.4976 560.527 54.4976C557.009 54.4976 554.223 55.3162 552.17 56.9526C550.117 58.589 549.09 60.7351 549.09 63.3911C549.09 65.164 549.514 66.6329 550.363 67.7974C551.212 68.9619 552.711 69.9805 554.857 70.853C557.004 71.7255 560.064 72.6398 564.038 73.5952C569.46 74.824 573.764 76.3324 576.949 78.1206C580.134 79.9088 582.405 81.9917 583.761 84.3696C585.117 86.7476 585.795 89.4609 585.795 92.5093C585.795 96.2282 584.842 99.4519 582.938 102.179C581.035 104.906 578.381 107.002 574.978 108.468C571.574 109.934 567.608 110.667 563.078 110.667C558.065 110.667 553.721 109.762 550.047 107.952C546.372 106.141 543.48 103.628 541.372 100.41C539.264 97.1918 538.041 93.4379 537.705 89.1489L547.797 88.5601C548.178 91.403 549.006 93.8176 550.281 95.8032C551.557 97.7889 553.272 99.2915 555.427 100.31C557.582 101.329 560.191 101.837 563.253 101.837C565.893 101.837 568.137 101.503 569.984 100.835C571.832 100.167 573.243 99.1802 574.219 97.8745C575.194 96.5688 575.683 94.9696 575.683 93.0776C575.683 91.3466 575.271 89.8131 574.45 88.478C573.629 87.1431 572.06 85.9176 569.744 84.8022C567.428 83.6868 564.005 82.5857 559.476 81.4995C554.477 80.2872 550.481 78.9404 547.487 77.4595C544.494 75.9785 542.327 74.1449 540.987 71.9585C539.648 69.772 538.978 67.047 538.978 63.7837C538.978 60.1956 539.848 57.0411 541.59 54.3208C543.331 51.6005 545.827 49.4779 549.076 47.9536C552.325 46.4295 556.201 45.6675 560.702 45.6675Z" fill="white"/>
+<path d="M375.09 61.5796C379.138 61.5796 382.542 62.2687 385.302 63.6479C388.062 65.0274 390.222 66.8764 391.781 69.1948C393.341 71.5133 394.339 74.1074 394.778 76.9761L384.884 77.5015C384.589 75.9083 384.02 74.5153 383.177 73.3228C382.333 72.1303 381.229 71.1969 379.865 70.5229C378.501 69.8491 376.873 69.5122 374.98 69.5122C372.058 69.5123 369.875 70.0881 368.432 71.2397C366.988 72.3914 366.267 73.883 366.267 75.7144C366.267 77.0786 366.596 78.1973 367.256 79.0698C367.916 79.9423 368.993 80.6535 370.488 81.2036C371.983 81.7538 373.985 82.2339 376.491 82.645C381.334 83.4205 385.132 84.4071 387.886 85.603C390.64 86.7991 392.589 88.2825 393.731 90.0532C394.874 91.8239 395.444 93.9849 395.444 96.5356C395.444 99.4672 394.617 101.961 392.962 104.018C391.307 106.075 389.037 107.64 386.153 108.712C383.27 109.785 379.936 110.321 376.154 110.321C371.728 110.321 367.996 109.645 364.958 108.295C361.92 106.945 359.573 105.084 357.918 102.711C356.263 100.339 355.319 97.6275 355.085 94.5767L365.043 94.0718C365.482 96.6506 366.575 98.6814 368.319 100.164C370.064 101.646 372.683 102.387 376.176 102.387C379.007 102.387 381.252 101.929 382.912 101.012C384.572 100.095 385.402 98.6375 385.402 96.6401C385.402 95.512 385.131 94.5704 384.589 93.8159C384.047 93.0615 382.996 92.4024 381.436 91.8384C379.875 91.2742 377.563 90.7276 374.501 90.1997C369.852 89.3681 366.201 88.3577 363.549 87.1675C360.896 85.9773 359.012 84.4777 357.896 82.6685C356.781 80.8592 356.224 78.6719 356.224 76.1069C356.224 71.8203 357.834 68.3277 361.053 65.6284C364.272 62.9292 368.951 61.5796 375.09 61.5796Z" fill="white"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M441.527 61.5796C446.001 61.5797 449.906 62.5828 453.243 64.5894C456.58 66.596 459.17 69.4166 461.013 73.0513C462.856 76.6861 463.777 80.9857 463.777 85.9497C463.777 90.8694 462.856 95.1616 461.013 98.8257C459.17 102.489 456.58 105.321 453.243 107.321C449.906 109.32 446.001 110.321 441.527 110.321C437.054 110.321 433.137 109.32 429.778 107.321C426.419 105.321 423.818 102.49 421.975 98.8257C420.131 95.1616 419.21 90.8694 419.21 85.9497C419.21 80.9857 420.131 76.6861 421.975 73.0513C423.818 69.4165 426.419 66.596 429.778 64.5894C433.137 62.5828 437.054 61.5796 441.527 61.5796ZM441.527 69.8276C437.657 69.8276 434.642 71.2552 432.486 74.1108C430.33 76.9666 429.252 80.9132 429.252 85.9497C429.252 91 430.33 94.9496 432.486 97.7983C434.642 100.647 437.657 102.072 441.527 102.072C445.398 102.072 448.4 100.647 450.534 97.7983C452.668 94.9496 453.735 91.0001 453.735 85.9497C453.735 80.9132 452.668 76.9666 450.534 74.1108C448.4 71.2553 445.398 69.8277 441.527 69.8276Z" fill="white"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M763.724 61.5796C768.197 61.5796 772.102 62.5827 775.439 64.5894C778.776 66.596 781.367 69.4165 783.21 73.0513C785.053 76.6861 785.975 80.9857 785.975 85.9497C785.975 90.8694 785.053 95.1616 783.21 98.8257C781.367 102.49 778.776 105.321 775.439 107.321C772.102 109.32 768.197 110.321 763.724 110.321C759.25 110.321 755.334 109.32 751.975 107.321C748.616 105.321 746.014 102.49 744.171 98.8257C742.328 95.1616 741.406 90.8694 741.406 85.9497C741.406 80.9857 742.328 76.6861 744.171 73.0513C746.014 69.4165 748.615 66.596 751.975 64.5894C755.334 62.5827 759.25 61.5796 763.724 61.5796ZM763.724 69.8276C759.853 69.8276 756.84 71.2553 754.684 74.1108C752.527 76.9666 751.449 80.9132 751.449 85.9497C751.449 91.0002 752.527 94.9495 754.684 97.7983C756.84 100.647 759.853 102.072 763.724 102.072C767.594 102.072 770.596 100.647 772.73 97.7983C774.864 94.9495 775.932 91.0002 775.932 85.9497C775.932 80.9132 774.864 76.9666 772.73 74.1108C770.597 71.2554 767.594 69.8276 763.724 69.8276Z" fill="white"/>
+<path d="M319.208 90.1919C319.208 94.3383 319.916 97.3861 321.333 99.3354C322.75 101.285 324.933 102.259 327.884 102.259C331.171 102.259 333.739 101.182 335.589 99.0269C337.439 96.8719 338.364 93.8124 338.364 89.8481V62.6294H348.035V109.268H339.051L338.96 101.663C338.02 103.841 336.72 105.628 335.057 107.02C332.429 109.219 329.031 110.319 324.863 110.319C320.166 110.319 316.437 108.757 313.677 105.632C310.917 102.508 309.537 98.1797 309.537 92.6479V62.6294H319.208V90.1919Z" fill="white"/>
+<path d="M636.149 90.1919C636.149 94.3382 636.858 97.386 638.274 99.3354C639.691 101.285 641.875 102.259 644.825 102.259C648.112 102.259 650.681 101.182 652.531 99.0269C654.381 96.8719 655.306 93.8122 655.306 89.8481V62.6294H664.978V109.268H655.993L655.901 101.665C654.961 103.842 653.661 105.628 651.998 107.02C649.37 109.219 645.972 110.319 641.805 110.319C637.107 110.319 633.378 108.757 630.618 105.632C627.858 102.508 626.479 98.1796 626.479 92.6479V62.6294H636.149V90.1919Z" fill="white"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M715.41 109.258H706.377L706.113 102.292C704.828 104.804 702.89 106.768 700.297 108.185C697.704 109.602 694.772 110.31 691.502 110.31C687.5 110.31 684.038 109.313 681.117 107.321C678.196 105.328 675.951 102.511 674.381 98.8696C672.811 95.2278 672.026 90.917 672.026 85.939C672.026 80.9611 672.815 76.651 674.392 73.0093C675.968 69.3675 678.221 66.5507 681.149 64.5581C684.078 62.5655 687.528 61.5688 691.502 61.5688C694.695 61.5689 697.549 62.2368 700.062 63.5718C702.576 64.9068 704.468 66.7787 705.738 69.187V47.062H715.41V109.258ZM694.126 69.8169C690.445 69.817 687.514 71.2519 685.336 74.1216C683.158 76.9913 682.068 80.9307 682.068 85.939C682.068 90.875 683.161 94.7966 685.347 97.7026C687.532 100.609 690.459 102.061 694.126 102.061C696.619 102.061 698.726 101.423 700.449 100.148C702.172 98.8725 703.484 97.0265 704.386 94.6099C705.287 92.1933 705.738 89.3028 705.738 85.939C705.738 82.4865 705.287 79.5628 704.386 77.1685C703.484 74.7742 702.172 72.95 700.449 71.6968C698.726 70.4436 696.618 69.8169 694.126 69.8169Z" fill="white"/>
+<path d="M493.952 61.5796C497.444 61.5796 500.358 62.3467 502.692 63.8813C505.027 65.4161 506.789 67.5122 507.977 70.1694C509.164 72.8267 509.759 75.8604 509.759 79.271V109.269H500.088V82.2778C500.088 79.5566 499.801 77.2594 499.228 75.3872C498.654 73.5149 497.718 72.0879 496.419 71.1079C495.12 70.128 493.4 69.6382 491.261 69.6382C488.035 69.6382 485.433 70.7173 483.456 72.8745C481.479 75.0318 480.489 78.1664 480.489 82.2778V109.269H470.818V62.6304H479.603L479.839 70.7056C480.351 69.3574 480.994 68.1721 481.771 67.1519C483.224 65.2445 485.002 63.8391 487.104 62.9351C489.205 62.0311 491.488 61.5796 493.952 61.5796Z" fill="white"/>
+<path d="M607.444 62.6294H619.797V70.436H607.444V95.7495C607.444 97.9078 607.915 99.3995 608.856 100.224C609.798 101.049 611.24 101.461 613.181 101.461H619.797V109.268H610.84C606.369 109.268 603.074 108.237 600.954 106.177C598.834 104.117 597.773 100.882 597.773 96.4712V70.436H590.646V62.6294H597.773V51.7036H607.444V62.6294Z" fill="white"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M192.892 47.062C202.68 47.062 210.211 49.7635 215.484 55.1655C220.758 60.5675 223.394 68.2614 223.395 78.2476C223.395 88.1757 220.801 95.8268 215.615 101.2C210.429 106.572 203.03 109.258 193.418 109.258H172.758V47.062H192.892ZM182.604 100.366H192.892C199.687 100.366 204.767 98.5313 208.131 94.8628C211.495 91.1941 213.177 85.6486 213.177 78.2271C213.177 70.7167 211.495 65.1272 208.131 61.4585C204.767 57.7898 199.687 55.9556 192.892 55.9556H182.604V100.366Z" fill="white"/>
+<path d="M274.701 54.8687H267.742C265.932 54.8687 264.591 55.3474 263.721 56.3052C262.851 57.2629 262.416 58.6325 262.416 60.4126V63.3345H280.056V59.8442C280.056 55.9225 281.157 52.8119 283.359 50.5122C285.562 48.2124 288.984 47.062 293.623 47.062H302.032V54.8687H295.073C293.263 54.8687 291.923 55.3477 291.053 56.3052C290.183 57.2629 289.747 58.6325 289.747 60.4126V63.3345H301.398V71.1421H289.747V109.258H280.056V71.1421H262.416V109.258H252.724V71.1421H246.206V63.3345H252.724V59.8442C252.724 55.9224 253.826 52.8119 256.028 50.5122C258.231 48.2125 261.652 47.0621 266.291 47.062H274.701V54.8687Z" fill="white"/>
+<path d="M239.931 109.255H230.259V62.6167H239.931V109.255Z" fill="white"/>
+<path d="M412.15 109.255H402.479V62.6167H412.15V109.255Z" fill="white"/>
+<path d="M734.348 109.255H724.677V62.6167H734.348V109.255Z" fill="white"/>
+<path d="M240.127 55.9556H230.063V46.5718H240.127V55.9556Z" fill="white"/>
+<path d="M412.347 55.9556H402.283V46.5718H412.347V55.9556Z" fill="white"/>
+<path d="M734.544 55.9556H724.48V46.5718H734.544V55.9556Z" fill="white"/>
+</svg>
diff --git a/knowledge/brand/design.md b/knowledge/brand/design.md
new file mode 100644
index 00000000..6fcb6a76
--- /dev/null
+++ b/knowledge/brand/design.md
@@ -0,0 +1,103 @@
+# Diffusion Studio visual guide
+
+Define color, type, identity, imagery, layout, safe areas, and captions. Use `video.md` for motion and sound, `voice.md` for words, and `library.md` for reusable files.
+
+Scale every pixel value below from a short edge of 1080.
+
+## Visual principles
+
+- Build structure with scale, weight, spacing, and luminance.
+- Keep the frame near-achromatic. Use color only when it carries meaning.
+- Show the product clearly. Do not decorate over controls or content the viewer must read.
+- Prefer one clear focal point to several equal points.
+
+## Color
+
+Use these hex values in Diffusion Studio source.
+
+| Role | Value |
+| --- | --- |
+| Background | `#000000` |
+| Surface | `#161616` |
+| Text | `#F8F8F8` |
+| Text, secondary | `#A4A4A4` |
+| Brand red | `#F43535` |
+
+Default to leaving red out. It lives on the app icon. At most one element may carry it. Never
+use it for a title or a large fill. The app's destructive state is `#E62D2D`, so red beside
+product UI may read as an error.
+
+`#008CFF` is the product blue. Use it only when it already appears in real product UI. Never
+use it as a brand accent.
+
+Place text on `#000000` or `#161616`. Do not rely on a shadow or stroke for contrast.
+
+## Typography
+
+Use `Geist`. Use `Geist Mono` for code and figures. Do not use italic.
+
+| Role | Size | Weight | Copy limit |
+| --- | ---: | ---: | ---: |
+| Title | 96 | 600 | 32 characters |
+| Subtitle | 60 | 400 | 64 characters |
+| Lower-third name | 48 | 500 | 28 characters |
+| Lower-third detail | 30 | 400 | 40 characters |
+| Label | 24 | 500 | 16 characters |
+
+Rewrite copy that exceeds a limit. Do not shrink the type. Confirm that Geist and Geist Mono
+are available before final output; no font files are bundled yet.
+
+## Logo and icon
+
+Use `assets/logos/logo-white.svg` or `assets/logos/icon-white.svg` on a dark, quiet background. Use the wordmark when the name must be clear. Use the icon only when the product is already named or the small space cannot hold the wordmark.
+
+Do not tint, outline, stretch, crop, rotate, rebuild, or place either mark over busy footage.
+No dark mark, minimum size, clear-space rule, or video-scale logo bug has been supplied. Do not
+invent one.
+
+## Product imagery
+
+- Show real product UI. Do not reconstruct or recolor it.
+- Use `contain` when viewers must read the whole interface.
+- Use `cover` only when the crop cannot hide a control, label, or result needed for the point.
+- Keep product captures sharp and at their native aspect ratio.
+- Use a plain surface around captures instead of stretching them to fill a frame.
+- Add photography or illustration only when the request or library supplies a suitable asset.
+
+## Layout and aspect ratios
+
+Use a margin of 64 and a gap of 40. Use other spacing in multiples of 8: 16 between a label and
+value, 24 between lines in one block, and 40 between separate blocks.
+
+Use a corner radius of 24 on framed media panels. Do not round full-frame media.
+
+Left-align copy and anchor it low. Center copy only when it stands alone on a plain background.
+Use at most two text elements in one shot: a primary line and its qualifier.
+
+Use these media forms:
+
+- **Full frame:** one product view or one dominant subject.
+- **Two-up:** two states, inputs, speakers, or before-and-after views.
+- **Four-up:** a set of equal details that remain legible at delivery size.
+
+Keep two-up panels square when the source allows it. Place them side by side in 16:9 and 1:1,
+and stack them in 9:16. Use a centered 2×2 grid for four-up. Use
+`assets/components/media-grid.tsx` for the tested geometry.
+
+### 9:16 text safe area
+
+At 1080×1920, keep readable content inside `x 64–900`, `y 200–1520`. The right 180 is the platform action rail and the bottom 400 is the caption reserve. Graphics may cross these bounds; text may not.
+
+## Captions
+
+Use `stark` for 9:16 output and `cascade` for other ratios. Pass no `colors`; neither preset
+exposes color slots. On 9:16, do not add another bottom offset to the preset.
+
+A preset carries its own legibility. Never put a band, plate, or gradient behind captions. When one
+does not read over the footage, change the preset or its `verticalAlign` or `offsetY`; if it still does not read,
+that is the answer for that stretch, not a reason to dim the picture.
+
+## Known gaps
+
+The brand has no bundled fonts, dark logo, approved video logo bug, image library, shared code
+text size, or measured minimum logo size. Name the gap when a task depends on one.
diff --git a/knowledge/brand/library.md b/knowledge/brand/library.md
new file mode 100644
index 00000000..f113d2df
--- /dev/null
+++ b/knowledge/brand/library.md
@@ -0,0 +1,57 @@
+# Diffusion Studio brand library
+
+Use this catalog before selecting or making a brand file. References define the brand; bundled
+files apply it. Keep one-off project media with its project.
+
+## Components and shared values
+
+| File | Use | Notes |
+| --- | --- | --- |
+| `assets/components/tokens.ts` | Share brand color, type, spacing, and safe-area values | Keep it in sync with `design.md` |
+| `assets/components/title-card.tsx` | Add a title and optional qualifier | Follow title and subtitle limits in `design.md` |
+| `assets/components/lower-third.tsx` | Add a name and detail over footage | Keep both lines inside the text safe area |
+| `assets/components/callout.tsx` | Add a short label and value | Use it for one fact, not a paragraph |
+| `assets/components/media-grid.tsx` | Place one, two, or four media sources | A two-up layout stacks in portrait and sits side by side otherwise |
+
+Components do not own a `<scene>`. Read the matching source for its inputs and copy only the
+files the project needs.
+
+## Compositions
+
+| File | Use | Format | Required inputs |
+| --- | --- | --- | --- |
+| `assets/compositions/product-demo.tsx` | A single product capture with a lower third | 9:16 | `videoSrc`, `name`, `detail` |
+| `assets/compositions/product-tour.tsx` | Full frame to two-up to four-up and back | 16:9 by default; may use 9:16 or 1:1 | Four media sources, `name`, `detail` |
+| `assets/compositions/end-card.tsx` | A plain branded end card | 9:16 | `title`, `cta` |
+
+Compositions own `<scene>`, timing, and editable inputs. They are starting points, not a second
+component system in the Diffusion Studio app.
+
+## Logos
+
+| File | Use |
+| --- | --- |
+| `assets/logos/logo-white.svg` | Wordmark on a dark, quiet background |
+| `assets/logos/icon-white.svg` | Product icon when the name is already clear |
+
+No dark mark is bundled.
+
+## Fonts, imagery, and audio
+
+No font, reusable image, music, sound-effect, or voiceover file is bundled yet. Do not replace a
+missing asset with an unlicensed or unrelated file.
+
+Keep reusable fonts in `assets/fonts/`, imagery in `assets/imagery/`, music in
+`assets/audio/music/`, sound effects in `assets/audio/sfx/`, and voiceovers in
+`assets/audio/voiceovers/`. Reuse a recording only when its words, delivery, and usage rights fit.
+
+## Select media
+
+Use catalog entries and filenames to shortlist likely matches. Inspect those candidates first,
+and widen the search only when needed.
+
+## Add to the library
+
+When adding media, record its source and usage rights in this catalog. Add a reusable item only
+after it has a clear repeated use. Give a component one job and a small input set. Add a
+composition when the scene flow repeats. Do not add a one-off choice as a brand rule.
diff --git a/knowledge/brand/video.md b/knowledge/brand/video.md
new file mode 100644
index 00000000..733fce9c
--- /dev/null
+++ b/knowledge/brand/video.md
@@ -0,0 +1,74 @@
+# Diffusion Studio video guide
+
+Define how the brand behaves over time. Use `design.md` for visual rules, `voice.md` for words,
+and `library.md` for reusable source.
+
+Work at 30 fps.
+
+## Scene and media structure
+
+Use full frame while one product state carries the point. Move to two-up to compare or connect
+two views. Move to four-up only when all four details remain readable. Return to full frame
+when one view becomes primary again.
+
+Change the layout because the idea changes, not to add motion. Prefer a hard cut between layout
+forms. Carry one element across the cut only when it represents the same object or state.
+
+In 9:16, hold split layouts longer because each panel is smaller. In 1:1, check that both copy
+and product UI still have one clear focal point.
+
+## Timing
+
+Enter over 400 ms (`"12f"`). Exit over 200 ms (`"6f"`). Stagger support by 100 ms (`"3f"`).
+Keep a single entrance or exit under 600 ms (`"18f"`).
+
+## Easing
+
+Use the nearest anchor and change it only when the motion needs a different quality. Do not use
+`linear` unless the movement is mechanical.
+
+| Anchor | Use | Easing |
+| --- | --- | --- |
+| Entrance | arriving | `cubicBezier(0.2,0.75,0.34,0.94)` |
+| Settle | landing or resolving | `cubicBezier(0,0.65,0.51,0.99)` |
+| Travel | moving between states | `cubicBezier(1,0.49,0,0.55)` |
+| Exit | leaving | `cubicBezier(1,0.02,0.54,0.42)` |
+
+Do not use the `bouncy` or `strong` spring presets.
+
+## Movement
+
+Lead with one element and delay its support by `"3f"`. Stagger repeated items from a meaningful
+origin: first, center, or focal point. Let opacity finish before movement so text becomes
+readable before it settles.
+
+Use one flourish per beat. Treat a busy scene as a layout problem.
+
+## Cuts and transitions
+
+| Method | Use |
+| --- | --- |
+| Hard cut on action | energy while authored motion is still moving |
+| Jump cut | matched direction and speed across the seam |
+| Continuous carry | the same object or state across two beats |
+| Hold cut | read-critical text, product UI, and final lockups |
+
+Use a 300 ms `dissolve` only between two shots of the same subject. Use `fadeToBlack` only to
+end a video. Do not use `fadeToWhite`, `slideFromLeft`, or `slideFromRight`.
+
+Cut product captures after the needed action or label has been visible long enough to read.
+Tighten a slow cut before adding motion.
+
+## Captions
+
+Add captions after the edit and final audio placement. Keep each caption on screen long enough
+to read without racing the voice. Use the visual treatment in `design.md`.
+
+## Sound
+
+Use audio supplied for the project or approved in `library.md`.
+
+Give speech priority. Use one clear source for product audio when several copies of the same
+capture appear on screen; mute the rest.
+
+No house mix level has been supplied. Do not invent one.
diff --git a/knowledge/brand/voice.md b/knowledge/brand/voice.md
new file mode 100644
index 00000000..120fe069
--- /dev/null
+++ b/knowledge/brand/voice.md
@@ -0,0 +1,45 @@
+# Diffusion Studio language and voice guide
+
+Use this guide for what Diffusion Studio says and how it says it. Apply it to titles, labels,
+scripts, captions, calls to action, and product descriptions.
+
+## Approved product language
+
+| Name | Copy | Use |
+| --- | --- | --- |
+| Product name | `Diffusion Studio` | Every product reference |
+| One-line description | The video editor for teams creating with agents. | Short introductions and summaries |
+
+Keep `video editor`, `teams`, and `agents` when adapting the one-line description. Do not broaden
+a product claim beyond what the request or supplied evidence supports.
+
+## Writing
+
+- Lead with the result or action.
+- Use short words, short sentences, and active voice.
+- Cut any word that adds no meaning.
+- State what the product does. Do not add hype or an unsupported claim.
+- Keep code, product names, technical terms, and interface labels exact.
+- Avoid familiar figures of speech and vague claims.
+- Rewrite copy that breaks a length limit. Do not shrink the type.
+- Break a writing rule when accuracy or clarity requires it.
+
+Review every prose output against these rules before delivering it.
+
+## Tone
+
+Sound clear, calm, and sure. Let the work supply the energy. Do not sound grand, cute, vague,
+or eager to impress.
+
+Avoid claims such as `effortless`, `magical`, `revolutionary`, or `all-in-one` unless the team
+has approved and proved the claim.
+
+## Calls to action
+
+Write a direct action that matches the destination. Name the action rather than promising an
+outcome. Keep it short enough to work without punctuation.
+
+## Spoken copy
+
+Apply the same writing and tone rules to scripts and narration. No house delivery or
+pronunciation guide has been supplied. Do not invent one.
diff --git a/examples/01-basics.tsx b/knowledge/examples/01-basics.tsx
similarity index 98%
rename from examples/01-basics.tsx
rename to knowledge/examples/01-basics.tsx
index b5761d27..5ad421f2 100644
--- a/examples/01-basics.tsx
+++ b/knowledge/examples/01-basics.tsx
@@ -1,4 +1,3 @@
-/* @jsxImportSource @diffusionstudio/jsx */
/* The everyday composition: sequenced A-roll, an image overlay, data-driven
* titles via <For>, and a music bed under everything.
*
diff --git a/examples/02-genai.tsx b/knowledge/examples/02-genai.tsx
similarity index 98%
rename from examples/02-genai.tsx
rename to knowledge/examples/02-genai.tsx
index 1bd95863..68012163 100644
--- a/examples/02-genai.tsx
+++ b/knowledge/examples/02-genai.tsx
@@ -1,4 +1,3 @@
-/* @jsxImportSource @diffusionstudio/jsx */
/* Multi-stage generation: text-to-image keyframes, image-to-video motion,
* a text-to-speech voiceover, generated ambience, and captions on top.
*
diff --git a/examples/03-ticker.tsx b/knowledge/examples/03-ticker.tsx
similarity index 98%
rename from examples/03-ticker.tsx
rename to knowledge/examples/03-ticker.tsx
index dbff834b..8cb20f41 100644
--- a/examples/03-ticker.tsx
+++ b/knowledge/examples/03-ticker.tsx
@@ -1,4 +1,3 @@
-/* @jsxImportSource @diffusionstudio/jsx */
/* Declarative animation: useTicker exposes the playhead as reactive
* accessors, createMemo derives values from it, and props consume the memos.
*
diff --git a/examples/04-html-in-canvas.tsx b/knowledge/examples/04-html-in-canvas.tsx
similarity index 98%
rename from examples/04-html-in-canvas.tsx
rename to knowledge/examples/04-html-in-canvas.tsx
index 13772c1c..049ba1af 100644
--- a/examples/04-html-in-canvas.tsx
+++ b/knowledge/examples/04-html-in-canvas.tsx
@@ -1,4 +1,3 @@
-/* @jsxImportSource @diffusionstudio/jsx */
/* An AI prompt box as real HTML, centered in the frame.
*
* cp examples/04-html-in-canvas.tsx ~/Projects/html-in-canvas/index.tsx
diff --git a/examples/05-anime-timeline.tsx b/knowledge/examples/05-anime-timeline.tsx
similarity index 98%
rename from examples/05-anime-timeline.tsx
rename to knowledge/examples/05-anime-timeline.tsx
index 511cca76..03b8e339 100644
--- a/examples/05-anime-timeline.tsx
+++ b/knowledge/examples/05-anime-timeline.tsx
@@ -1,4 +1,3 @@
-/* @jsxImportSource @diffusionstudio/jsx */
/* Anime.js timeline scrubbed by the playhead: one clock, two render worlds.
*
* cp examples/05-anime-timeline.tsx ~/Projects/anime-timeline/index.tsx
diff --git a/examples/06-three.tsx b/knowledge/examples/06-three.tsx
similarity index 99%
rename from examples/06-three.tsx
rename to knowledge/examples/06-three.tsx
index 748febcd..3ff1bcce 100644
--- a/examples/06-three.tsx
+++ b/knowledge/examples/06-three.tsx
@@ -1,4 +1,3 @@
-/* @jsxImportSource @diffusionstudio/jsx */
/* Three.js owning a <surface>: a glTF helmet spun by the playhead.
*
* cp examples/06-three.tsx ~/Projects/three/index.tsx
diff --git a/examples/07-webgpu.tsx b/knowledge/examples/07-webgpu.tsx
similarity index 99%
rename from examples/07-webgpu.tsx
rename to knowledge/examples/07-webgpu.tsx
index 0714b5bb..c955d74b 100644
--- a/examples/07-webgpu.tsx
+++ b/knowledge/examples/07-webgpu.tsx
@@ -1,4 +1,3 @@
-/* @jsxImportSource @diffusionstudio/jsx */
/* WebGPU owning a <surface>: a triangle whose colors cycle with the playhead.
*
* cp examples/07-webgpu.tsx ~/Projects/webgpu/index.tsx
diff --git a/examples/08-shader-paint.tsx b/knowledge/examples/08-shader-paint.tsx
similarity index 97%
rename from examples/08-shader-paint.tsx
rename to knowledge/examples/08-shader-paint.tsx
index 534893b2..0512afce 100644
--- a/examples/08-shader-paint.tsx
+++ b/knowledge/examples/08-shader-paint.tsx
@@ -1,4 +1,3 @@
-/* @jsxImportSource @diffusionstudio/jsx */
/* A shader paint post-processing a video: chromatic aberration pulsing with
* the playhead plus a vignette, driven by two uniforms.
*
diff --git a/examples/09-inspect-variables.tsx b/knowledge/examples/09-inspect-variables.tsx
similarity index 97%
rename from examples/09-inspect-variables.tsx
rename to knowledge/examples/09-inspect-variables.tsx
index f5379407..97a9f4d4 100644
--- a/examples/09-inspect-variables.tsx
+++ b/knowledge/examples/09-inspect-variables.tsx
@@ -1,4 +1,3 @@
-/* @jsxImportSource @diffusionstudio/jsx */
/* `@inspect` variables: annotate a top-level const and the editor's right
* sidebar grows a control for it (stage level, under the background picker).
* Moving the control moves the composition live — no remount — and the value
diff --git a/examples/10-typegpu.tsx b/knowledge/examples/10-typegpu.tsx
similarity index 99%
rename from examples/10-typegpu.tsx
rename to knowledge/examples/10-typegpu.tsx
index a4d9a544..53bd2903 100644
--- a/examples/10-typegpu.tsx
+++ b/knowledge/examples/10-typegpu.tsx
@@ -1,4 +1,3 @@
-/* @jsxImportSource @diffusionstudio/jsx */
/* TypeGPU on a <surface>: an underwater caustics shader written in TypeScript.
*
* The shader is TypeGPU's caustics example (docs.swmansion.com/TypeGPU,
diff --git a/examples/11-redraw.tsx b/knowledge/examples/11-redraw.tsx
similarity index 99%
rename from examples/11-redraw.tsx
rename to knowledge/examples/11-redraw.tsx
index 4800560c..f20ef8a8 100644
--- a/examples/11-redraw.tsx
+++ b/knowledge/examples/11-redraw.tsx
@@ -1,4 +1,3 @@
-/* @jsxImportSource @diffusionstudio/jsx */
/* Redraw on a <surface>: the "hello" write-on stroke from redraw's docs.
*
* Redraw (redraw.dev) is a 2D renderer on WebGPU: a Library declares custom
diff --git a/examples/README.md b/knowledge/examples/README.md
similarity index 97%
rename from examples/README.md
rename to knowledge/examples/README.md
index 5eb0fb02..4fd1c4d7 100644
--- a/examples/README.md
+++ b/knowledge/examples/README.md
@@ -3,7 +3,7 @@
Self-contained compositions demonstrating the JSX API (see [reference/jsx](../reference/jsx/README.md)).
Each one is a whole project entry file: it default-exports a component rendering a
`<stage>` with one `<scene>` in it. To run one, copy it into a project folder as the
-entry and open that folder:
+entry and [`open`](../reference/tools/open.md) that folder — from a shell:
```sh
cp examples/01-basics.tsx ~/Projects/basics/index.tsx
diff --git a/examples/tsconfig.json b/knowledge/examples/tsconfig.json
similarity index 83%
rename from examples/tsconfig.json
rename to knowledge/examples/tsconfig.json
index bbcb6f5a..a6d24286 100644
--- a/examples/tsconfig.json
+++ b/knowledge/examples/tsconfig.json
@@ -1,5 +1,5 @@
{
- "extends": "../tsconfig.base.json",
+ "extends": "../../tsconfig.base.json",
"compilerOptions": {
"jsx": "preserve",
"jsxImportSource": "@diffusionstudio/jsx",
diff --git a/knowledge/guides/motion/easings.md b/knowledge/guides/motion/easings.md
new file mode 100644
index 00000000..677718e1
--- /dev/null
+++ b/knowledge/guides/motion/easings.md
@@ -0,0 +1,22 @@
+# Easings
+
+Six go-to cubic beziers, in mirrored pairs. Choose from the intended weight, energy, and continuity of the action — never leave a move on linear or a default curve.
+
+| Easing | Value | Use for |
+| --- | --- | --- |
+| `snappyOut` | `cubicBezier(0,0.6,0.4,1)` | Energetic entrances that settle softly |
+| `expoOut` | `cubicBezier(0,1,0,1)` | Dramatic reveals, scale pops, counters |
+| `snappyIn` | `cubicBezier(0.6,0,1,0.4)` | Wind-ups that exit at full speed |
+| `expoIn` | `cubicBezier(1,0,1,0)` | Anticipation into a hard exit or cut |
+| `outIn` | `cubicBezier(0,0.7,1,0.3)` | Motion carried across a cut, whip feel |
+| `inOut` | `cubicBezier(0.7,0,0.3,1)` | A-to-B moves at rest on both ends |
+
+Across a cut, alternate them so objects are at their highest velocity at the moment of the cut: ease in to animate out, followed by ease out for the reveal.
+
+Motion graphics are motion: this is not a presentation or a static website. Elements that fade in, sit still, and fade out read as slides. Keep energy in the frame — overlap entrances and exits, stagger siblings by a few frames, keep something moving during holds (a slow drift, scale, or counter), and drive every move with one of these curves.
+
+## Pixel snapping
+
+There is no sub-pixel rendering: everything lands on whole pixels, so a move slower than roughly one pixel per frame sits still and then jumps rather than gliding. Before committing to a move, divide its travel in pixels by its duration in frames — `y: -10` over `3400ms` is a tenth of a pixel per frame, a stutter, not a drift. The same math applies to scale and rotation: measure the travel of the edge that moves most, not the property value.
+
+Slow holds are where this bites. Keep the drift above the limit by moving further or over a shorter stretch, or carry the hold with something that isn't tied to position at all — opacity, blur, color, a counter.
diff --git a/knowledge/guides/prompts/media-listen.md b/knowledge/guides/prompts/media-listen.md
new file mode 100644
index 00000000..75ce57cc
--- /dev/null
+++ b/knowledge/guides/prompts/media-listen.md
@@ -0,0 +1,12 @@
+# Writing prompts for `media_listen`
+
+[`media_listen`](../../reference/tools/media/listen.md) puts a multimodal model in front of an audio track and answers a prompt about it. A good prompt is specific about what you want and asks for timestamps so the answer lines up with the timeline. With no prompt it returns a general description; the examples below shape that into something more useful.
+
+## Examples
+When you refer to a specific moment inside a prompt, use `MM:SS` (e.g. `01:15` for one minute fifteen seconds).
+
+- Summarize the footage in 3 sentences.
+- What are the examples given at 00:05 and 00:10 supposed to tell us?
+- Describe the key events in this footage. Include timestamps for salient moments.
+- Transcribe the speech in the audio. Include timestamps as provided.
+- Tell me the name of the music track playing and include the timestamps for start and end.
diff --git a/knowledge/guides/walkthroughs/podcast-clip.md b/knowledge/guides/walkthroughs/podcast-clip.md
new file mode 100644
index 00000000..8b9268a9
--- /dev/null
+++ b/knowledge/guides/walkthroughs/podcast-clip.md
@@ -0,0 +1,114 @@
+# Example: podcast clipping
+
+A long two-or-more-speaker conversation — one to three hours — cut down to a single vertical short. The work is mostly search: the clip-worthy moment has to be found before anything is edited. Audio carries everything you need for that search, so the whole discovery pass runs on an audio-only download; video is only fetched once the moment is known.
+
+## 1. Brief
+
+Write the brief first: the source URL or file, how many clips are wanted, the target duration (25–35 s unless told otherwise), the delivery format (1080×1920), and any editorial steer — a topic to favour, a speaker to feature, moments to avoid. A clip has no surrounding context to lean on, so **self-containment is the hard requirement**; record it in the brief and check the result against it.
+
+## 2. Audio-only pass
+
+Download the audio track alone with `fetch` (`audio: true`, `output: podcast.m4a`). It is a fraction of the bytes, and the best moments are found without visuals. From a shell:
+
+```bash
+dapi fetch <url> -a -o podcast.m4a
+```
+
+## 3. Segment the audio
+
+A three-hour track is too long for one analysis pass, so split it into segments and analyze each. Segments are **windows**, not files: `media_listen` takes the range as `start`/`end`, and the timestamps it returns are relative to `start`. Pick one of three ways to choose the boundaries:
+
+1. **Waveform.** `media_waveform` renders loudness over the whole track and returns the silent spans as second ranges. Cut segments at those spans — the boundaries land between thoughts instead of inside them.
+2. **Naive.** Fixed 15–30 minute segments. Nothing to parse, and good enough because the analysis reports its own timestamps; a moment straddling a boundary is the only loss.
+3. **Source transcript.** Many platforms publish one (YouTube captions, show notes with chapter markers). Parse its timestamps and use chapters or topic shifts as boundaries — the cheapest option when it exists, since it needs no decoding at all.
+
+## 4. Find the clip-worthy moments
+
+Run `media_listen` on each segment (`start` 15:00, `end` 45:00, and so on) with a prompt that spells out the criteria and demands timestamps:
+
+```text
+This is a podcast. Find the 3 most clip-worthy self-contained moments in this segment for a vertical social short. Criteria: a complete thought, punchline, or surprising revelation that works with NO prior context; roughly 25-35 seconds long; opens on a strong hook line and lands on a clean button. For each give: exact start and end timestamp (MM:SS, relative to this segment), who is speaking, a one-line summary of what is said, and a hook-strength rating 1-10. Be strict about self-containment.
+```
+
+Asking for a rating and a one-line summary is what makes the candidates comparable across segments. Add the segment's `start` offset back to each returned timestamp to get absolute positions in the source, then pick the winner on hook strength and self-containment — not on how interesting the topic is.
+
+## 5. Lock the exact cut points
+
+The analysis gives you seconds; a clip needs the frame. Tighten both ends against the real audio:
+
+- `media_transcribe` returns word-level start/end times (use ffmpeg to shorten). Put the in-point on the first word of the hook line and the out-point after the last word of the button.
+- `media_waveform` with `start`/`end` around the cut shows the breaths around those words, so you can open the in-point a beat early and let the out-point land on the silence after the line instead of clipping its tail.
+
+## 6. Download the segment and lay it out
+
+Now fetch the video, and **download with padding** — a few seconds either side of the locked range — so the trim can still be nudged without downloading again.
+
+`media_probe` on the download gives the source dimensions (a podcast is almost always 1920×1080) and confirms where the padded range actually starts, since a keyframe-aligned download can begin slightly early.
+
+Give the node the **source's own aspect ratio**, scaled to the scene height, rather than the scene's box: the node is then wider than the scene, and the scene crops it. That geometry is what makes the framing in the next step possible.
+
+```tsx
+const raw = "/Downloads/clip-raw.mp4";
+
+// Locked range, expressed in the padded download's own time.
+const IN = 6.4; // first word of the hook
+const OUT = 36.1; // after the button lands
+
+const SCENE_W = 1080;
+const NODE_H = 1920;
+const NODE_W = NODE_H * (1920 / 1080); // source aspect, scaled to scene height ≈ 3413
+
+export default function Project() {
+ return (
+ <stage camera={[0.25, 0, 0, 0.25, 235, 70]}>
+ <scene name="Podcast clip" width={SCENE_W} height={1920} fill="black" active>
+ <sequence name="A-roll">
+ <video src={raw} width={NODE_W} height={NODE_H} x={(SCENE_W - NODE_W) / 2}
+ start={0} sourceIn={IN} sourceOut={OUT} />
+ </sequence>
+ </scene>
+ </stage>
+ );
+}
+```
+
+Save the file and get the trim right before framing or captions — `capture` at the in-point and the out-point is the check.
+
+## 7. Frame the active speaker (optional if necessary)
+
+
+```tsx
+import { useTicker } from "@diffusionstudio/jsx";
+
+const turns = [
+ { at: 0, fx: 0.30 },
+ { at: 8.2, fx: 0.70 },
+ { at: 24.5, fx: 0.30 },
+];
+
+const { time } = useTicker();
+// time() is the scene playhead; the clip starts at 0, so it is already node-local.
+const speakerX = () =>
+ centerOn((turns.findLast((s) => time() >= s.at) ?? turns[0]).fx);
+
+// ...
+<video src={raw} width={NODE_W} height={NODE_H}
+ start={0} sourceIn={IN} sourceOut={OUT} x={speakerX()} />
+```
+
+
+## 8. Captions
+
+Add captions last, after the trim and framing are verified. Use the **`classic`** preset centred — it is the first choice for vertical content.
+
+```tsx
+<captions preset="classic" verticalAlign="center" />
+```
+
+If the caption block lands on the speakers' faces, push it off with `offsetY` rather than changing the framing you just verified:
+
+```tsx
+<captions preset="classic" verticalAlign="center" offsetY={420} />
+```
+
+Capture a frame per caption line with `capture` and check readability at delivery size — a caption over a mouth is worse than no caption.
diff --git a/knowledge/guides/walkthroughs/talking-head.md b/knowledge/guides/walkthroughs/talking-head.md
new file mode 100644
index 00000000..3d384225
--- /dev/null
+++ b/knowledge/guides/walkthroughs/talking-head.md
@@ -0,0 +1,105 @@
+# Example: long-form talking head
+
+A single speaker to camera — an explainer, a podcast solo, a course lesson. The recording is long and raw: restarts, flubbed lines, and dead air between thoughts. The edit cuts it down to the clean story, back-to-back, never mid-word. The transcript drives the A-roll; the waveform separates silence from performance.
+
+## 1. Brief
+
+Write the brief first. It records the source files, the target duration (or "keep everything good"), and any editorial instruction. Absent a target length or explicit direction, **make no editorial cuts**: keep every good part, drop only silences and double takes, and keep the story chronological.
+
+## 2. Analysis
+
+The transcript is the spine, so transcribe everything with speech.
+
+- **Transcribe every video and any external audio.** `media_transcribe` returns word-level start/end times — the times you cut on. Run it on each camera take and on any separate recording (a lav or interface track you will sync to).
+- **Render the waveform to read the gaps.** `media_waveform` marks silence in red and returns it as second ranges. A transcript marks only speech, so a gap in it can be silence *or* something to keep — a laugh, a breath. The waveform tells them apart: red is dead air to cut; a gap that still shows signal is performance to keep.
+- **Resolve double takes visually.** The transcript shows repeated lines; usually the **last** take is the keeper. When takes read equally well, `media_grab` the first word of each and keep the sharpest — motion blur means a bad take.
+
+## 3. Lay out the A-roll
+
+Drop **every** double take and silence, and put the good parts in chronological order.
+
+```tsx
+import { For } from "solid-js";
+
+const raw = "/Recordings/take.mp4";
+
+// Kept stretches, in order — source range only.
+const takes = [
+ { src: raw, sourceIn: 48.2, sourceOut: 53.9 }, // opener — third take, sourceIn on the first word
+ { src: raw, sourceIn: 61.7, sourceOut: 69.4 }, // next sentence — sourceIn opens ~0.4 s early for a breath
+ { src: raw, sourceIn: 74.0, sourceOut: 78.1 }, // mid-sentence pickup — flubbed clause dropped
+ { src: raw, sourceIn: 95.2, sourceOut: 102.8 }, // closer — trailing air left in sourceOut
+];
+
+// Chain them back-to-back: each start is the sum of the durations before it.
+let cursor = 0;
+const aRoll = takes.map((t) => {
+ const start = cursor;
+ cursor += t.sourceOut - t.sourceIn;
+ return { ...t, start };
+});
+
+export default function Project() {
+ return (
+ <stage camera={[0.25, 0, 0, 0.25, 235, 70]}>
+ <scene name="Talking head" width={1080} height={1920} fill="black" active>
+ <sequence name="A-roll">
+ <For each={aRoll}>
+ {(clip) => (
+ <video src={clip.src} width={1080} height={1920}
+ start={clip.start} sourceIn={clip.sourceIn} sourceOut={clip.sourceOut} />
+ )}
+ </For>
+ </sequence>
+ </scene>
+ </stage>
+ );
+}
+```
+
+The silence you *keep* between sentences lives inside the clips, not in a timeline gap — a gap in a sequence freezes or blanks the frame. Carry a pause by extending a clip's `sourceOut` (or opening the next `sourceIn`) into the real silence, and keep the timeline gapless.
+
+Save the file — the app recompiles and re-renders it — and get the spine right before layering anything on top.
+
+## 4. Cut points
+
+- **Open tight.** Set the first `sourceIn` on the first word — dead air at the top kills retention.
+- **Between sentences, leave 0.3–0.5 s of silence.** Enough to breathe, not to drag. Tune it with each clip's `sourceOut` / next `sourceIn`.
+- **Mid-sentence, butt the words together.** When you drop a clause inside a sentence, close the gap as far as it goes — never mid-word. Grab the frames around the join to confirm the word is whole.
+- **End on up to 0.8 s.** Leave a little trailing air in the last `sourceOut` so the video doesn't stop abruptly.
+
+## 5. Verification
+
+Run `check` on the scene first: on a long timeline of many clips, a `sourceOut`/`start` that don't meet leaves a gap no sampled frame would land on, and the check names those spans outright.
+
+Then the cut points, which matter most. Capture the **first frame of every clip** with `capture` at each clip's `start`, and check the cut didn't land on a bad frame — motion blur is the usual tell; nudge `sourceIn` a few frames to a settled one. Reconcile against the brief, and re-check neighbouring cuts after any structural change.
+
+## 6. Visual hook (optional)
+
+A hook makes the video readable at a glance. Aim for a frame you could lift out and use as a thumbnail.
+
+- **Just a title.** One line of large Inter at medium weight, in a single colour. That is the whole hook: **no sub-header, eyebrow, or secondary line**, and **no background, box, panel, or fill** — the text sits directly on the A-roll.
+- **Placement.** Beside the speaker's head or below it, **never covering the head**. A popular strategy is to place it A-roll aware.
+- **Duration.** Keep it on screen as long as the viewer needs to read it.
+
+One line of copy is a job for the native `<text>` tag:
+
+```tsx
+<text
+ x={80} y={1240} width={920} height={260}
+ start={0} end={3}
+ fontFamily="Inter" fontSize={84} fontWeight={500} color="#fff"
+ textAlign="left" textBaseline="top"
+>
+ The one editing trick
+</text>
+```
+
+## 7. Captions (optional)
+
+Add captions **last**, after every cut and overlay is verified, so they transcribe the final audio at its final placement. Use the **`whisper`** preset aligned to the bottom, and start it where the hook ends — set both `start` and `sourceIn` to that timestamp so the transcript stays aligned (see `reference/jsx/captions.md` in the project's docs). Keep captions off overlays and off the important part of the A-roll.
+
+```tsx
+{/* Hook holds until 00:03; captions begin there. */}
+<captions preset="whisper" verticalAlign="bottom" start={3} sourceIn={3} />
+```
diff --git a/reference/jsx/README.md b/knowledge/reference/jsx/README.md
similarity index 98%
rename from reference/jsx/README.md
rename to knowledge/reference/jsx/README.md
index fc4887dd..6608dee3 100644
--- a/reference/jsx/README.md
+++ b/knowledge/reference/jsx/README.md
@@ -34,7 +34,7 @@ export default function Project() {
| [scene.md](./scene.md) | `<scene>`: the clipped, playable frame and the timeline its children sit on |
| [elements.md](./elements.md) | Element-to-node mapping, coordinates and sizing, the shared property table |
| [group.md](./group.md), [rect.md](./rect.md), [text.md](./text.md), [video.md](./video.md), [image.md](./image.md), [audio.md](./audio.md) | Per-element props |
-| [fonts.md](./fonts.md) | Fonts for `<text>` and HTML: local families, `dapi fonts` |
+| [fonts.md](./fonts.md) | Fonts for `<text>` and HTML: local families, the `fonts` tool |
| [paints.md](./paints.md) | `<solidPaint>`, gradients, `<colorStop>`, `<imagePaint>` / `<videoPaint>` |
| [styles.md](./styles.md) | `<stroke>`, `<shadow>`, `<effect>`: outlines, drop shadows and filters |
| [html.md](./html.md) | `<html>`: reactive HTML children drawn into the box |
@@ -62,7 +62,7 @@ Everything below runs in the app, on open and again on every save of a project f
2. **Compile**: the entry file bundles with esbuild + `babel-preset-solid` in `universal` mode, so JSX compiles against the editor's renderer runtime instead of the DOM. `solid-js`, `solid-js/store` and `@diffusionstudio/jsx` are external — the app supplies its own instances; everything else is bundled. A compile error is reported and the canvas keeps the last good render.
3. **Evaluate**: the app imports the module. Top-level code runs to completion. The module's **default export** is the project component.
4. **Mount**: the component tree renders **directly into the world**. There is no staging tree: each element materializes as an entity as it is created, and the root `<stage>` is the one already there. Mounting is synchronous, and a throw part-way through leaves nothing behind — the document is disposed and the previous render stays on the canvas.
-5. **Resolve**: every `src` resolves in the background — a path or asset id is loaded, a `generate.*` declaration is generated in dependency order, a `<captions>` without a `src` transcribes its scene. Each element renders a generating state until its asset lands, and an element that fails carries the reason (see [generate.md](./generate.md), [errors.md](./errors.md)). Non-blocking: the composition is on the canvas and editable while this runs, and [`dapi context`](../context.md) reports where each generation stands.
+5. **Resolve**: every `src` resolves in the background — a path or asset id is loaded, a `generate.*` declaration is generated in dependency order, a `<captions>` without a `src` transcribes its scene. Each element renders a generating state until its asset lands, and an element that fails carries the reason (see [generate.md](./generate.md), [errors.md](./errors.md)). Non-blocking: the composition is on the canvas and editable while this runs, and [`context`](../tools/context.md) reports where each generation stands.
6. **Live**: the reactive graph keeps running for as long as the project is open — signals, effects, `useTicker` (see [lifecycle.md](./lifecycle.md)). Export, capture and the next open re-execute the same module.
A save replaces the whole run: the old mount is disposed and the new one takes the stage. Scenes are rebuilt rather than accumulated, and the entities the previous render owned go with it.
diff --git a/reference/jsx/adjustment-layer.md b/knowledge/reference/jsx/adjustment-layer.md
similarity index 100%
rename from reference/jsx/adjustment-layer.md
rename to knowledge/reference/jsx/adjustment-layer.md
diff --git a/reference/jsx/animations.md b/knowledge/reference/jsx/animations.md
similarity index 100%
rename from reference/jsx/animations.md
rename to knowledge/reference/jsx/animations.md
diff --git a/reference/jsx/audio-sync.md b/knowledge/reference/jsx/audio-sync.md
similarity index 100%
rename from reference/jsx/audio-sync.md
rename to knowledge/reference/jsx/audio-sync.md
diff --git a/reference/jsx/audio.md b/knowledge/reference/jsx/audio.md
similarity index 100%
rename from reference/jsx/audio.md
rename to knowledge/reference/jsx/audio.md
diff --git a/reference/jsx/captions.md b/knowledge/reference/jsx/captions.md
similarity index 100%
rename from reference/jsx/captions.md
rename to knowledge/reference/jsx/captions.md
diff --git a/reference/jsx/elements.md b/knowledge/reference/jsx/elements.md
similarity index 98%
rename from reference/jsx/elements.md
rename to knowledge/reference/jsx/elements.md
index 66309a4d..5be77819 100644
--- a/reference/jsx/elements.md
+++ b/knowledge/reference/jsx/elements.md
@@ -81,7 +81,7 @@ Every node accepts:
| Prop | Type | Default | Meaning |
| ---- | ---- | ------- | ------- |
-| `id` | `string` | stamped | How the element is addressed — by the editor writing back to it, by `dapi capture`, by [`syncTo`](./audio-sync.md). Written into your source if you leave it out (see [module.md](./module.md#ids)). |
+| `id` | `string` | stamped | How the element is addressed — by the editor writing back to it, by `capture`, by [`syncTo`](./audio-sync.md). Written into your source if you leave it out (see [module.md](./module.md#ids)). |
| `ref` | `SceneNode` variable or `(node: SceneNode) => void` | none | SolidJS-style ref; receives the element's node when it is created. For `<surface>`/`<surfacePaint>` the node's `element` is the backing canvas (see [surface-paint.md](./surface-paint.md)). |
| `name` | `string` | none | Human-readable node name; what labels the node in the editor. |
| `x`, `y` | `number` | `0` | Position relative to the parent, px. |
diff --git a/reference/jsx/errors.md b/knowledge/reference/jsx/errors.md
similarity index 83%
rename from reference/jsx/errors.md
rename to knowledge/reference/jsx/errors.md
index 1ba9689b..5b2148f6 100644
--- a/reference/jsx/errors.md
+++ b/knowledge/reference/jsx/errors.md
@@ -4,9 +4,9 @@ Where each [pipeline](./README.md#pipeline) stage fails, and with what effect:
| Stage | Where it surfaces | Effect |
| ----- | ----------------- | ------ |
-| **Compile** (syntax, an unresolved import, a PascalCase composition tag, a control-flow component with no import) | A "Project failed to compile" toast, with the compiler's message; also on the app console ([`dapi logs`](../logs.md)) | Nothing is remounted. The canvas keeps the last good render, so a project in the middle of an edit is never blanked. |
+| **Compile** (syntax, an unresolved import, a PascalCase composition tag, a control-flow component with no import) | A "Project failed to compile" toast, with the compiler's message; also on the app console ([`logs`](../tools/logs.md)) | Nothing is remounted. The canvas keeps the last good render, so a project in the middle of an edit is never blanked. |
| **Evaluate / mount** (a throw at module scope or during render, a root that is not `<stage>`, a tag the host does not know, an element parented into its own subtree) | A "Project failed to render" toast with the thrown message | The half-built document is disposed — **nothing is left behind** — and the previous render stays on the canvas. |
-| **Source resolution** (a path that does not exist, an unreachable URL, a per-model constraint on `aspectRatio` / `duration` / a feature flag, a caption with no audible audio in its scene) | The element on the canvas, and `generations` in [`dapi context`](../context.md) | Per element, not per mount: everything else stays mounted and playable. The element stops showing its generating state and is left without a paint, carrying the reason — see below. |
+| **Source resolution** (a path that does not exist, an unreachable URL, a per-model constraint on `aspectRatio` / `duration` / a feature flag, a caption with no audible audio in its scene) | The element on the canvas, and `generations` in [`context`](../tools/context.md) | Per element, not per mount: everything else stays mounted and playable. The element stops showing its generating state and is left without a paint, carrying the reason — see below. |
Runtime errors are reported against the compiled module. Since types are stripped rather than checked, run `npx tsc --noEmit` in the project folder to catch what the compile will not.
@@ -31,4 +31,4 @@ A composition that looks right in the viewport but captures black, frozen, or pa
1. **A stateful animation seek.** anime.js records a tween's start values at the tween's *first* render, and captures/exports sample frames out of order — so a tween whose target was written to outside the timeline before its first render bakes that mutated state in as its starting values and replays it at every subsequent frame. Symptom: deterministic but *order-dependent* wrong frames — the same time renders when requested first and comes out wrong when requested after a later frame. See the caveat in [html.md](./html.md): give tweens explicit start values with `{ from, to }`, never write to or reset tween targets between seeks, and derive capture-critical values statelessly from `time()`.
2. **`scale()` on a large or clipped subtree.** The rasterizer renders these as empty (see [html.md limitations](./html.md#requirements-and-limitations)). Symptom: one wrapper's entire subtree missing at every sampled time while siblings render. Fix: translate/opacity animation; `scale` only on small content-sized leaves without inner clips.
3. **Fractional `opacity` nested under fractional `opacity`.** The rasterizer drops the ancestor's whole subtree while its opacity is between 0 and 1 if any descendant carries its own `opacity` < 1 (see [html.md limitations](./html.md#requirements-and-limitations)). Symptom: an element blank at every time its entrance/exit fade is mid-flight, rendering normally the moment the animated opacity reaches exactly 1 — deterministic per time and independent of sampling order. Fix: animate `opacity` on one level only; dim children with `rgba()`/`hsl()` alpha colors.
-4. **`Error drawing <HtmlPaint> content: … No cached paint record for element`** in `dapi logs`, or html content missing from the first sampled frame(s) of a capture while later frames render: the offline draw raced the browser's paint snapshot for a freshly mounted host. Engine-side, not a composition bug — until the `whenReady` paint-snapshot fix ships, re-request the affected time or lead the capture with a throwaway frame.
+4. **`Error drawing <HtmlPaint> content: … No cached paint record for element`** in `logs`, or html content missing from the first sampled frame(s) of a capture while later frames render: the offline draw raced the browser's paint snapshot for a freshly mounted host. Engine-side, not a composition bug — until the `whenReady` paint-snapshot fix ships, re-request the affected time or lead the capture with a throwaway frame.
diff --git a/reference/jsx/fonts.md b/knowledge/reference/jsx/fonts.md
similarity index 65%
rename from reference/jsx/fonts.md
rename to knowledge/reference/jsx/fonts.md
index dce05467..edb0d727 100644
--- a/reference/jsx/fonts.md
+++ b/knowledge/reference/jsx/fonts.md
@@ -1,10 +1,10 @@
# Fonts
-Both text paths draw with fonts **installed on the machine**. Discover what is available with [`dapi fonts`](../fonts.md) (filter by family, weight, or style); the active project's families are also on [`dapi context`](../context.md) as `fontFamilies`. macOS resolves these families for both the native renderer and the browser, so there is nothing to bundle or load.
+Both text paths draw with fonts **installed on the machine**. Discover what is available with [`fonts`](../tools/fonts.md) (filter by family, weight, or style); the active project's families are also on [`context`](../tools/context.md) as `fontFamilies`. macOS resolves these families for both the native renderer and the browser, so there is nothing to bundle or load.
## Native `<text>`
-Name a family on the [`<text>`](./text.md) element with `fontFamily`; pick the variant with `fontWeight` and `fontStyle`. The value must be a family present in `dapi fonts`; an unknown family falls back to the editor default.
+Name a family on the [`<text>`](./text.md) element with `fontFamily`; pick the variant with `fontWeight` and `fontStyle`. The value must be a family listed by `fonts`; an unknown family falls back to the editor default.
```tsx
<text fontFamily="Inter" fontWeight={700} fontSize={128} textAlign="center" textBaseline="middle">
@@ -22,9 +22,9 @@ In [`<html>`](./html.md) you style text with ordinary CSS, so **use a locally in
</html>
```
-Remote web fonts work too (a Google Fonts `<link>`, or an `@font-face` with a `url()` source). However the cost is that every render then depends on the network and on the font host staying up, so a local family from [`dapi fonts`](../fonts.md) is the safer default for anything you have to be able to re-render on demand.
+Remote web fonts work too (a Google Fonts `<link>`, or an `@font-face` with a `url()` source). However the cost is that every render then depends on the network and on the font host staying up, so a local family from [`fonts`](../tools/fonts.md) is the safer default for anything you have to be able to re-render on demand.
-If you want to pin an exact variant, declare an `@font-face` whose source is the CSS `local()` string that `dapi fonts` reports for that variant (never a `url()`):
+If you want to pin an exact variant, declare an `@font-face` whose source is the CSS `local()` string that `fonts` reports for that variant (never a `url()`):
```tsx
<html width={700} height={110}>
diff --git a/reference/jsx/generate.md b/knowledge/reference/jsx/generate.md
similarity index 84%
rename from reference/jsx/generate.md
rename to knowledge/reference/jsx/generate.md
index 70e24003..f2b7286a 100644
--- a/reference/jsx/generate.md
+++ b/knowledge/reference/jsx/generate.md
@@ -34,18 +34,18 @@ export default function Project() {
Declarations are **pure**: calling `generate.*` validates its options and returns a ref; nothing is requested until an element carrying it mounts. A ref that is never used by a mounted element (directly or as an input to another asset) is never generated. Declarations may live at module scope or inside components.
-Generation is **asynchronous and non-blocking**: the element is on the canvas immediately, showing a generating state, and its paint attaches when the asset lands. [`dapi context`](../context.md) reports where each one stands — generating, failed with the reason, or done with the library path it landed as — and a declaration that fails leaves its element carrying an [`error`](./errors.md#failed-sources).
+Generation is **asynchronous and non-blocking**: the element is on the canvas immediately, showing a generating state, and its paint attaches when the asset lands. [`context`](../tools/context.md) reports where each one stands — generating, failed with the reason, or done with the library path it landed as — and a declaration that fails leaves its element carrying an [`error`](./errors.md#failed-sources).
## Declaration options
-Run [`dapi models <type>`](../models.md) to discover valid `model` ids and per-model constraints; [`dapi voices`](../voices.md) lists voices.
+[`models`](../tools/models.md) lists valid `model` ids and per-model constraints; [`voices`](../tools/voices.md) lists voices.
```ts
type AssetInput = string | AssetRef; // path, URL, asset id, or another declaration
generate.image(opts: {
prompt: string; // required
- model?: string; // default: first model from `dapi models image`
+ model?: string; // default: the first image model from `models`
aspectRatio?: "1:1" | "4:3" | "3:4" | "16:9" | "9:16"; // default "16:9"
refs?: AssetInput[]; // image references
seed?: number; // reproducible generation
@@ -53,7 +53,7 @@ generate.image(opts: {
generate.video(opts: {
prompt: string; // required
- model?: string; // default: first model from `dapi models video`
+ model?: string; // default: the first video model from `models`
aspectRatio?: "1:1" | "4:3" | "3:4" | "16:9" | "9:16"; // default "16:9"
duration?: number; // whole seconds; default 5
audio?: boolean; // generate audio alongside; models with the `audio` feature only
@@ -64,13 +64,13 @@ generate.video(opts: {
generate.voice(opts: {
prompt: string; // required: the text to speak
- voice?: string; // default: first voice from `dapi voices`
+ voice?: string; // default: the first voice from `voices`
seed?: number;
}): AssetRef;
generate.audio(opts: {
prompt: string; // required
- model?: string; // default: first model from `dapi models audio`
+ model?: string; // default: the first audio model from `models`
duration?: number; // seconds; default 30 for music, the model's own default for sfx
seed?: number;
}): AssetRef;
diff --git a/reference/jsx/group.md b/knowledge/reference/jsx/group.md
similarity index 100%
rename from reference/jsx/group.md
rename to knowledge/reference/jsx/group.md
diff --git a/reference/jsx/html.md b/knowledge/reference/jsx/html.md
similarity index 94%
rename from reference/jsx/html.md
rename to knowledge/reference/jsx/html.md
index 229cfcf6..112d31a3 100644
--- a/reference/jsx/html.md
+++ b/knowledge/reference/jsx/html.md
@@ -75,7 +75,7 @@ Like all paints, `<htmlPaint>` stacks with siblings in document order and clips
## Persistence and export
-The module is re-executed in every context: on reload, export, and [`dapi capture`](../capture.md) the engine re-executes it and rebuilds the DOM content in that context. Exports wait for the browser's rendering update before sampling each frame, so the drawn HTML appears in the output; ticker-driven signals follow the playhead and animate frame-accurately. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree).
+The module is re-executed in every context: on reload, export, and [`capture`](../tools/capture.md) the engine re-executes it and rebuilds the DOM content in that context. Exports wait for the browser's rendering update before sampling each frame, so the drawn HTML appears in the output; ticker-driven signals follow the playhead and animate frame-accurately. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree).
## Requirements and limitations
diff --git a/reference/jsx/image.md b/knowledge/reference/jsx/image.md
similarity index 100%
rename from reference/jsx/image.md
rename to knowledge/reference/jsx/image.md
diff --git a/reference/jsx/keyframes.md b/knowledge/reference/jsx/keyframes.md
similarity index 100%
rename from reference/jsx/keyframes.md
rename to knowledge/reference/jsx/keyframes.md
diff --git a/reference/jsx/lifecycle.md b/knowledge/reference/jsx/lifecycle.md
similarity index 100%
rename from reference/jsx/lifecycle.md
rename to knowledge/reference/jsx/lifecycle.md
diff --git a/reference/jsx/media.md b/knowledge/reference/jsx/media.md
similarity index 96%
rename from reference/jsx/media.md
rename to knowledge/reference/jsx/media.md
index fc639481..3d68c203 100644
--- a/reference/jsx/media.md
+++ b/knowledge/reference/jsx/media.md
@@ -58,7 +58,7 @@ mkdir -p assets/b-roll && ln -s ~/Movies/drone.mp4 assets/b-roll/
<video src="b-roll/drone.mp4" width={1920} height={1080} />
```
-Link rather than copy: the bytes stay where they are, the project holds nothing but a name for them, and the library still gets a portable path to reach them by. Give `ln -s` an absolute target — a relative link is read against the folder the link sits in, so it breaks as soon as the project moves. A directory of numbered frames is taken in whole, as one [image sequence](#image-sequences), rather than as a file each, and a link to that directory does the same. [`dapi fetch`](../fetch.md) writes to disk and nothing else, so `-o assets/b-roll/` is how a download becomes an asset; `generate.*` results arrive under `assets/generated/` on their own.
+Link rather than copy: the bytes stay where they are, the project holds nothing but a name for them, and the library still gets a portable path to reach them by. Give `ln -s` an absolute target — a relative link is read against the folder the link sits in, so it breaks as soon as the project moves. A directory of numbered frames is taken in whole, as one [image sequence](#image-sequences), rather than as a file each, and a link to that directory does the same. [`fetch`](../tools/fetch.md) writes to disk and nothing else, so an `output` under `assets/b-roll/` is how a download becomes an asset; `generate.*` results arrive under `assets/generated/` on their own.
A link is the project's, and what it points at is not. Deleting a linked asset in the panel removes the link and stops there.
diff --git a/reference/jsx/module.md b/knowledge/reference/jsx/module.md
similarity index 91%
rename from reference/jsx/module.md
rename to knowledge/reference/jsx/module.md
index cf067bc3..e204e442 100644
--- a/reference/jsx/module.md
+++ b/knowledge/reference/jsx/module.md
@@ -14,7 +14,7 @@ export default function Project() {
}
```
-The component receives no props. [`dapi open <dir>`](../open.md) opens the folder — creating it, and an `index.tsx` holding an empty stage, if it is not a project yet.
+The component receives no props. [`open`](../tools/open.md) opens the folder — creating it, and an `index.tsx` holding an empty stage, if it is not a project yet.
## The folder
@@ -28,10 +28,9 @@ The component receives no props. [`dapi open <dir>`](../open.md) opens the folde
| `assets.yml` | The asset library (see [media.md](./media.md#the-library)). |
| `assets/` | The library's files: symlinks to media brought in from elsewhere, plus what the app produced itself, generations under `assets/generated/`. Media imported through the app is linked where it lies, never copied. |
| `cache/` | Derived data (thumbnails, waveforms). Disposable. |
-| `AGENTS.md` | The agent entry point: what to read in `.diffusion/docs/`. |
-| `.diffusion/docs/` | App-owned copy of this reference and the examples, stamped with the app version and regenerated when it changes. Read it, never edit it. |
+| `README.md` | What the folder holds and how to work in it — including, for agents, that the app's MCP server carries this reference. |
-Everything but `.diffusion/` is written once and is yours from then on.
+Everything is written once and is yours from then on. The reference itself is not copied into the project: the app serves the installed version's as MCP resources under `dapi://reference/`.
## Ids
@@ -41,7 +40,7 @@ Every composition element carries an `id`, and the app stamps one onto every ele
<rect id="k3f9x1" x={40} y={40} width={640} height={360} fill="#FF0055" />
```
-An id is what makes an element addressable: it is how an entity is traced back to the JSX that produced it, so a change made on the canvas can be written to the element it came from, and it is what [`dapi capture`](../capture.md) takes to render one node. It is also how elements point at each other within a render — [`syncTo`](./audio-sync.md) names the id of the clip it aligns against.
+An id is what makes an element addressable: it is how an entity is traced back to the JSX that produced it, so a change made on the canvas can be written to the element it came from, and it is what [`capture`](../tools/capture.md) takes to render one node. It is also how elements point at each other within a render — [`syncTo`](./audio-sync.md) names the id of the clip it aligns against.
**Ids are yours to write.** Any string is valid, and `id="hero"` is worth more to read than anything minted. The stamp only fills in elements that have none, so renaming one by hand is safe. Ids are stripped at compile time and never reach the runtime as a prop; what survives is the stamp that carries them.
diff --git a/reference/jsx/paints.md b/knowledge/reference/jsx/paints.md
similarity index 100%
rename from reference/jsx/paints.md
rename to knowledge/reference/jsx/paints.md
diff --git a/reference/jsx/rect.md b/knowledge/reference/jsx/rect.md
similarity index 100%
rename from reference/jsx/rect.md
rename to knowledge/reference/jsx/rect.md
diff --git a/reference/jsx/scene.md b/knowledge/reference/jsx/scene.md
similarity index 93%
rename from reference/jsx/scene.md
rename to knowledge/reference/jsx/scene.md
index c7b029f8..1235b501 100644
--- a/reference/jsx/scene.md
+++ b/knowledge/reference/jsx/scene.md
@@ -18,7 +18,7 @@ A scene is the **clipped, playable frame** a composition is made in, and the onl
| `fill` | `string` | none | Background fill, any CSS color; alpha is ignored. A scene without one is transparent, and exports with alpha. |
| `name` | `string` | none | Human-readable node name; what labels the scene in the editor. Recommended. |
| `volume` | `number` | `0` | Decibels on the scene's own bus, which everything in it mixes into — the master fader. `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. A clip's own `volume` composes with this one. |
-| `active` | `boolean` | absent | Whether this is the scene the playhead, the timeline and `dapi capture` operate on. |
+| `active` | `boolean` | absent | Whether this is the scene the playhead, the timeline and `capture` operate on. |
| `workarea` | `[in, out] \| null` | `null` | The stretch of the scene that plays and exports, in any [time format](./timing.md#time-formats). |
| `selected` | `boolean` | absent | Whether the editor has the scene selected. |
| `timeline` | `[zoom, x, y]` | absent | Where the scene's timeline is looking: `zoom` in pixels per second of timeline, horizontal scroll in seconds, vertical scroll in pixels. Absent means the default zoom, at the beginning. |
@@ -31,7 +31,7 @@ A scene also takes paints as children, exactly as a `<rect>` does (see [paints.m
Two rules the runtime holds for `active`: **at most one element is active**, and **only a root** — a direct child of `<stage>` — can be. A nested `active` is dropped, and when a file names more than one the last one rendered wins.
-**Mark one scene `active` in every project you author.** Nothing activates on its own, and a project that opens with no active scene opens on an empty timeline: there is no playhead to scrub, `dapi capture` has nothing pointed at it, and an export has no scene to render. One scene, one `active`; with several, the one the project should open on — pair it with the [`<stage>`](./stage.md) `camera` that frames it.
+**Mark one scene `active` in every project you author.** Nothing activates on its own, and a project that opens with no active scene opens on an empty timeline: there is no playhead to scrub, `capture` has nothing pointed at it, and an export has no scene to render. One scene, one `active`; with several, the one the project should open on — pair it with the [`<stage>`](./stage.md) `camera` that frames it.
`workarea` is the exception among them: it is carried by the source the way `active` is (the timeline's brackets have nowhere else to go), but it is read wherever the file is, so **what it says is what comes out of a render**. Playback loops within it, and an export is of it and nothing else.
diff --git a/reference/jsx/sequences.md b/knowledge/reference/jsx/sequences.md
similarity index 100%
rename from reference/jsx/sequences.md
rename to knowledge/reference/jsx/sequences.md
diff --git a/reference/jsx/shader-paint.md b/knowledge/reference/jsx/shader-paint.md
similarity index 96%
rename from reference/jsx/shader-paint.md
rename to knowledge/reference/jsx/shader-paint.md
index 965ca2a0..9fbceed4 100644
--- a/reference/jsx/shader-paint.md
+++ b/knowledge/reference/jsx/shader-paint.md
@@ -96,7 +96,7 @@ Swapping `wgsl` recompiles the pipeline asynchronously; the media shows unshaded
## Errors and limitations
-- WGSL compile errors are reported on the app console ([`dapi logs`](../logs.md)) with line numbers relative to your source; the paint renders as passthrough until a fix lands.
+- WGSL compile errors are reported on the app console ([`logs`](../tools/logs.md)) with line numbers relative to your source; the paint renders as passthrough until a fix lands.
- Pipeline compilation is asynchronous. Live playback may show the first frames unshaded; exports wait for compilation, so rendered output is always shaded.
- One shader reads one media paint; shaders do not chain and do not read solid/gradient/html/surface paints or the composited stack (over those the shader runs procedurally and stacks on top).
- For full custom pipelines (own vertex stage, WebGL, three.js) use [`<surface>`](./surface-paint.md), which owns its canvas outright.
diff --git a/reference/jsx/stage.md b/knowledge/reference/jsx/stage.md
similarity index 94%
rename from reference/jsx/stage.md
rename to knowledge/reference/jsx/stage.md
index 7e2c1634..f69900b9 100644
--- a/reference/jsx/stage.md
+++ b/knowledge/reference/jsx/stage.md
@@ -42,4 +42,4 @@ The stage takes no timing, no transform and no paints — it is not a node, it i
A root's place on the canvas is its own `x`/`y`, in the same document space the camera matrix moves through. Roots that do not say where they sit all sit at the origin, on top of each other; give each after the first an `x` clear of the ones before it, as the example above does.
-Which scene the playhead, the timeline and [`dapi capture`](../capture.md) are pointed at is a scene's `active`, not the stage's business. At most one scene carries it, and only a direct child of `<stage>` can.
+Which scene the playhead, the timeline and [`capture`](../tools/capture.md) are pointed at is a scene's `active`, not the stage's business. At most one scene carries it, and only a direct child of `<stage>` can.
diff --git a/reference/jsx/styles.md b/knowledge/reference/jsx/styles.md
similarity index 100%
rename from reference/jsx/styles.md
rename to knowledge/reference/jsx/styles.md
diff --git a/reference/jsx/surface-paint.md b/knowledge/reference/jsx/surface-paint.md
similarity index 94%
rename from reference/jsx/surface-paint.md
rename to knowledge/reference/jsx/surface-paint.md
index 843d6ed6..6ee46bae 100644
--- a/reference/jsx/surface-paint.md
+++ b/knowledge/reference/jsx/surface-paint.md
@@ -126,7 +126,7 @@ Like all paints it stacks with siblings in document order and clips to the paren
## Persistence and export
-The module is re-executed in every context, so the drawing is reproducible rather than ephemeral: on reload, export, and [`dapi capture`](../capture.md) the engine re-runs your drawing code against a fresh canvas driven by that context's playhead, so ticker surfaces animate in exports. The bitmap itself is not stored; your code reproduces it. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree; using them inside a draw effect is fine).
+The module is re-executed in every context, so the drawing is reproducible rather than ephemeral: on reload, export, and [`capture`](../tools/capture.md) the engine re-runs your drawing code against a fresh canvas driven by that context's playhead, so ticker surfaces animate in exports. The bitmap itself is not stored; your code reproduces it. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree; using them inside a draw effect is fine).
**Async setup has to be held.** Because that re-execution is a fresh mount, a model, a texture, or a device your drawing waits for is fetched again there — and sampling begins as soon as the render returns, so the first frames are written from a canvas nothing has drawn into yet. Hand the promise to [`useTicker().hold`](./lifecycle.md#hold) and those frames wait for it:
diff --git a/reference/jsx/text.md b/knowledge/reference/jsx/text.md
similarity index 98%
rename from reference/jsx/text.md
rename to knowledge/reference/jsx/text.md
index b93ed70e..1ffc6bb2 100644
--- a/reference/jsx/text.md
+++ b/knowledge/reference/jsx/text.md
@@ -18,7 +18,7 @@ All [common props](./elements.md#common-props), plus:
| ---- | ---- | ------- | ------- |
| children | `string` (or expressions resolving to strings) | **required** | The text content, alongside any `<textRange>`, paint, `<stroke>`, `<shadow>`, `<effect>`, `<animation>` and `<keyframeTrack>` children. |
| `color` | `string` | none | The glyph color; any CSS color, alpha ignored (use `opacity`). Drawn beneath any paint children (see [paints.md](./paints.md)); animate it with a `color` [keyframe track](./keyframes.md). A text with neither `color` nor a paint child draws no glyphs. |
-| `fontFamily` | `string` | `Inter` | A family available on the machine ([`dapi fonts`](../fonts.md)); see [fonts.md](./fonts.md). |
+| `fontFamily` | `string` | `Inter` | A family available on the machine ([`fonts`](../tools/fonts.md)); see [fonts.md](./fonts.md). |
| `fontSize` | `number` | `16` | Px. |
| `fontWeight` | `number \| "normal" \| "bold"` | `"normal"` | CSS weights `100`–`900`. |
| `fontStyle` | `"normal" \| "italic" \| "oblique"` | `"normal"` | |
diff --git a/reference/jsx/timing.md b/knowledge/reference/jsx/timing.md
similarity index 95%
rename from reference/jsx/timing.md
rename to knowledge/reference/jsx/timing.md
index adbed9f6..92542d0b 100644
--- a/reference/jsx/timing.md
+++ b/knowledge/reference/jsx/timing.md
@@ -62,4 +62,4 @@ The canonical internal unit is frames at **30 fps**; all formats are converted o
| `"MM:SS"` | `"02:30"` | Minutes and seconds. |
| `"HH:MM:SS"` | `"01:02:30"` | Hours, minutes, seconds. |
-CLI flags documented as taking a `Time` value (e.g. `--time` on [`capture`](../capture.md) and [`media grab`](../media/grab.md)) accept the same formats. Times in command **output** are plain seconds.
+CLI flags documented as taking a `Time` value (e.g. `--times` on [`capture`](../tools/capture.md) and [`media grab`](../tools/media/grab.md)) accept the same formats. Times in command **output** are plain seconds.
diff --git a/reference/jsx/transitions.md b/knowledge/reference/jsx/transitions.md
similarity index 100%
rename from reference/jsx/transitions.md
rename to knowledge/reference/jsx/transitions.md
diff --git a/reference/jsx/variables.md b/knowledge/reference/jsx/variables.md
similarity index 100%
rename from reference/jsx/variables.md
rename to knowledge/reference/jsx/variables.md
diff --git a/reference/jsx/video.md b/knowledge/reference/jsx/video.md
similarity index 100%
rename from reference/jsx/video.md
rename to knowledge/reference/jsx/video.md
diff --git a/knowledge/reference/tools/README.md b/knowledge/reference/tools/README.md
new file mode 100644
index 00000000..c2efeafd
--- /dev/null
+++ b/knowledge/reference/tools/README.md
@@ -0,0 +1,70 @@
+# Tool reference
+
+Diffusion Studio exposes one set of tools, reachable two ways:
+
+- **MCP.** The running app serves an MCP server at `http://127.0.0.1:3274/mcp` (Streamable HTTP) and on a local socket; `dapi mcp` pipes that socket to stdio for clients that only spawn processes. A connected agent gets every tool in `tools/list`, with the descriptions on these pages, this knowledge base as resources under `dapi://`, and two live resources, `dapi://context` and `dapi://logs`.
+- **CLI.** `dapi`, the command-line client shipped with the app, wraps every tool as a command for shells, scripts and CI. `dapi <command> --help` prints the same description and the same field help.
+
+Both validate against the same schemas and return the same result, so each tool is documented once, on its own page. The catalog behind all three (server, CLI, these pages) lives in `packages/dapi`.
+
+The JSX code syntax specified in [jsx/](../jsx/README.md) is **pseudo-SVG**, mirroring SVG's shape-and-paint model with the editor's own tags and props rather than the SVG spec. A project is a folder of that JSX, and **the source is the document**: the app compiles the entry file and renders every element into an editable node, and edits made on the canvas are written back to the element that authored them. So the loop is [`open`](./open.md) once, then edit the files — there is no tool that pushes content into the app. What the tools do is read the running app ([`context`](./context.md), [`capture`](./capture.md), [`logs`](./logs.md)), inspect media, and list what a declaration may name.
+
+## Names
+
+A tool is named as MCP lists it, and the CLI spelling follows from the name:
+
+- `_` in a tool name is a space on the command line: `media_grab` is `dapi media grab`. The `media` group is also `m`.
+- A tool's first field is the positional argument: `capture`'s `id` is `dapi capture <id>`.
+- Every other field is an option in kebab-case: `perSheet` is `--per-sheet`, `separate` is `--separate`. Short forms are listed on each page.
+- Times are written the same way everywhere: seconds (`1.5`), frames at the project's rate (`45f`), or a clock string (`1:30`, `00:01:30`). Times in **results** are plain seconds.
+
+## Results
+
+Every tool returns one JSON object, its *structured content*. Over MCP that is the result's `structuredContent`, repeated as a text block for clients that ignore structured content; the CLI prints it to stdout, unchanged. Tools that render images (`capture`, `media_grab`, `media_filmstrip`, `media_waveform`, `screenshot`) write PNGs to disk and return their paths; over MCP a result of at most four images, none over a megabyte, also carries them inline as image content, so a contact sheet arrives in context without opening anything.
+
+## Errors
+
+A failure is a sentence written to be read, e.g. `No project open — run open first`. Over MCP it arrives as a tool result with `isError: true`, not as a protocol error; the CLI prints it to stderr and exits `1`. Each page's Errors section lists what the tool fails on; only the delivery differs by surface.
+
+Every tool runs inside the app, so the app has to be running. Over MCP that is a given — the connection is to the app. From a shell, `dapi open` launches it (macOS) or surfaces the running instance; every other command prints a launch instruction and exits `1` while the app is down.
+
+## The tools
+
+| Tool | CLI | Does |
+| --- | --- | --- |
+| [`open`](./open.md) | `dapi open` | Open project |
+| [`context`](./context.md) | `dapi context` | App context |
+| [`capture`](./capture.md) | `dapi capture` | Capture frames |
+| [`check`](./check.md) | `dapi check` | Check structure |
+| [`export`](./export.md) | `dapi export` | Export scene |
+| [`media_probe`](./media/probe.md) | `dapi media probe` | Probe media |
+| [`media_grab`](./media/grab.md) | `dapi media grab` | Grab frames |
+| [`media_transcribe`](./media/transcribe.md) | `dapi media transcribe` | Transcribe speech |
+| [`media_filmstrip`](./media/filmstrip.md) | `dapi media filmstrip` | Filmstrip preview |
+| [`media_waveform`](./media/waveform.md) | `dapi media waveform` | Waveform preview |
+| [`media_listen`](./media/listen.md) | `dapi media listen` | Listen to audio |
+| [`models`](./models.md) | `dapi models` | Generation models |
+| [`voices`](./voices.md) | `dapi voices` | Speech voices |
+| [`whoami`](./whoami.md) | `dapi whoami` | Signed-in account |
+| [`logs`](./logs.md) | `dapi logs` | App logs |
+| [`screenshot`](./screenshot.md) | `dapi screenshot` | Window screenshot |
+| [`fonts`](./fonts.md) | `dapi fonts` | Local fonts |
+| [`fetch`](./fetch.md) | `dapi fetch` | Fetch video |
+| [`report`](./report.md) | `dapi report` | Report a bug |
+
+How the surface is divided:
+
+- **The project loop.** [`open`](./open.md) a folder, edit its JSX, [`context`](./context.md) for what the source cannot say, [`capture`](./capture.md) and [`check`](./check.md) to verify, [`export`](./export.md) when asked.
+- **Media inspection** (`media_*`): a file by path, without adding it to the project. Absolute paths and URLs work with or without an open project; library paths (`b-roll/clip.mp4`) need one.
+- **What a declaration may name.** [`models`](./models.md), [`voices`](./voices.md), [`fonts`](./fonts.md). Generation itself is declared in the project module (`generate.*`, see [jsx/generate.md](../jsx/generate.md)); no tool generates.
+- **The app and the machine.** [`whoami`](./whoami.md), [`logs`](./logs.md), [`screenshot`](./screenshot.md), [`report`](./report.md), and [`fetch`](./fetch.md) for downloads.
+
+## Shared types
+
+```ts
+Asset = { id: string; path: string; type: string } // asset ids are content hashes; `path` is the library path
+Time = number | `${number}f` | "MM:SS" // seconds, frames at the project's rate ("45f"), or a clock string; see jsx/timing.md
+NodeId = string // an element's `id` in the project's JSX; `file:id` when two files collide
+```
+
+Time inputs take the `Time` format unless noted otherwise.
diff --git a/knowledge/reference/tools/capture.md b/knowledge/reference/tools/capture.md
new file mode 100644
index 00000000..3546987b
--- /dev/null
+++ b/knowledge/reference/tools/capture.md
@@ -0,0 +1,57 @@
+# capture
+
+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 (separate: true 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.
+
+| | |
+| --- | --- |
+| MCP tool | `capture` |
+| CLI | `dapi capture <id> [options]` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `id` | `string`, required | `<id>` | scene id from the project's JSX, or `file:id` when two files use the same id |
+| `times` | `Time[]` | `-t, --times <time...>` | positions to capture, relative to the export's first frame, the workarea's start (0 = the export's frame 0) — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: [0]) |
+| `separate` | `boolean` | `-S, --separate` | write one image per position instead of merging them into contact sheets of up to 12 cells, each labelled with its timecode |
+| `perSheet` | `integer` | `--per-sheet <n>` | positions per contact sheet, 1-12; fewer means a larger cell each (default: as many as fit) |
+| `output` | `string` | `-o, --output <dir>` | absolute directory to write the PNGs into (default: a fresh directory under the system temp dir) |
+
+## Frames
+
+Each frame is **the frame an export of that scene would encode**: the scene is re-rendered from a fresh mount at its own size, position `0` is the workarea's first frame, and the requested positions are evaluated in timeline order, forward only — the way an export advances — so a composition whose look depends on having played (an `<html>` node's own animation state, for instance) captures exactly as it exports.
+
+Scenes only: a single element renders inside its scene, so capture the scene at the times the element plays. To grab a video asset's own pixels instead of a composited frame, use [`media_grab`](./media/grab.md).
+
+With `separate`, each position is rendered at 720p height and named after its timecode (e.g. `01s12f.png`). Without an `output` directory the images land in a fresh `dapi-capture-*` directory under the system temp directory, so runs never overwrite each other. Writing into the same directory twice overwrites images whose name matches; with `separate`, requested times that land on the same frame share one file.
+
+## Timecodes
+
+Cell labels, the `timecode` field, and the filenames all use the same stamp, which drops its zero segments: `08s10f` is 8 seconds and 10 frames, `01m05s` is 65 seconds, and the export's first frame is `0f`. Each segment carries its unit, so nothing is ambiguous once the empty ones are gone.
+
+## Layout
+
+A sheet never exceeds 2576x1456, the largest image a vision model reads at full detail. Within that budget the grid is the one that draws each frame largest, and the last row may be partially filled. Cells render at their own size rather than the flat 720p of `separate`, so a few positions are sharper than a standalone capture and never coarser; a scene smaller than 1080p tall is rendered up to that height, and nothing is rendered beyond it. Sheets are named after the span they cover, e.g. `0f-11s.png`. For a 16:9 scene the cell sizes are:
+
+| Positions | Grid | Per-frame |
+|---|---|---|
+| 1 | 1x1 | 1920x1080 |
+| 2-4 | 2x1, 2x2 | 1280x720 |
+| 5-9 | 3x2, 3x3 | 850x478 |
+| 10-12 | 4x3 | 636x357 |
+
+Sheets are opaque: a scene's transparent background composites onto flat grey, and the gutters between cells use the same grey.
+
+## Output
+
+One JSON object with one entry per written image: a contact sheet by default, a position with `separate`.
+
+```ts
+{ images: Array<{ timecode: string; path: string }> } // e.g. { "images": [{ "timecode": "0f-01s15f", "path": "/tmp/dapi-capture-3f2c1a8e/0f-01s15f.png" }] }
+```
+
+A sheet's timecode is the span it covers; a single position's is its own. Sheets come in timeline order, and their cells in the order the positions were requested in. Over MCP, up to four images of at most a megabyte each also arrive inline.
+
+## Errors
+
+Fails when no project is open (`No project open` — run [`open`](./open.md) first), the id is unknown, the id is ambiguous (two files use it — pass `file:id`), the id names a node that is not a scene (the error names the scene to capture instead), `perSheet` is outside 1 to 12 or combined with `separate`, or a PNG can't be written.
diff --git a/reference/check.md b/knowledge/reference/tools/check.md
similarity index 60%
rename from reference/check.md
rename to knowledge/reference/tools/check.md
index e09a3f0d..cd6e4bbe 100644
--- a/reference/check.md
+++ b/knowledge/reference/tools/check.md
@@ -1,12 +1,21 @@
-# `dapi check <id>`
+# check
-Checks a node's subtree for obvious structural mistakes, without rendering: spans of the node's play window 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. Alongside the issues it reports subtree stats — node count by kind, nesting depth, and played duration — so it doubles as a quick structural summary of a scene.
+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.
-The analysis is structural, from the resolved timeline alone, so it is instant and costs no credits — and it can only say *nothing is scheduled*, not *the frame is black*. A scheduled clip can still render black (dark footage, content smaller than the canvas, a transparent asset); confirm suspicious spans visually with [`capture`](./capture.md) at a time inside the range.
+| | |
+| --- | --- |
+| MCP tool | `check` |
+| CLI | `dapi check <id>` |
## Input
-- `<id>`: node id to check (required) — the element's `id` attribute in the project's JSX, or `file:id` when two files use the same id. Same resolution rules as [`capture`](./capture.md).
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `id` | `string`, required | `<id>` | node id from the project's JSX, or `file:id` when two files use the same id |
+
+## What it can and cannot see
+
+The analysis is structural, from the resolved timeline alone, so it is instant and costs no credits — and it can only say *nothing is scheduled*, not *the frame is black*. A scheduled clip can still render black (dark footage, content smaller than the canvas, a transparent asset); confirm suspicious spans visually with [`capture`](./capture.md) at a time inside the range. Alongside the issues it reports subtree stats — node count by kind, nesting depth, and played duration — so it doubles as a quick structural summary of a scene. The `id` resolves by the same rules as [`capture`](./capture.md)'s.
## What counts as visual coverage
@@ -29,7 +38,7 @@ One JSON object:
severity: "error" | "warning";
message: string;
node?: string; // source stamp of the offending node; absent for subtree-wide issues
- ranges?: Array<{ start: number; end: number }>; // seconds relative to the node's start — for a scene whose workarea starts at 0, the clock `capture --time` uses
+ ranges?: Array<{ start: number; end: number }>; // seconds relative to the node's start — for a scene whose workarea starts at 0, the clock `capture` positions use
}>;
}
```
@@ -45,6 +54,10 @@ One JSON object:
| `transparent` | warning | A node with static opacity 0 (nodes with keyframes are given the benefit of the doubt) |
| `source-error` | error | An asset that failed to load or generate, with the failure message |
-## Exit code
+## Severity and the shell
+
+Finding issues is not a failure: the result is the same object either way, and the caller reads `issues`. From a shell, `dapi check` additionally exits `1` when an error-severity issue is found (warnings alone stay `0`), so it can gate a script.
+
+## Errors
-`0` when no error-severity issue is found (warnings alone stay `0`), `1` when one is — or when the check itself can't run (no project open, unknown id).
+Fails when the check itself can't run: no project is open, or the id is unknown or ambiguous.
diff --git a/knowledge/reference/tools/context.md b/knowledge/reference/tools/context.md
new file mode 100644
index 00000000..7445751e
--- /dev/null
+++ b/knowledge/reference/tools/context.md
@@ -0,0 +1,49 @@
+# context
+
+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.
+
+| | |
+| --- | --- |
+| MCP tool | `context` |
+| CLI | `dapi context` |
+| CLI aliases | `dapi ctx` |
+
+## Input
+
+None.
+
+## What it does not say
+
+The composition itself — its scenes, what is selected, which scene is active, the work area — is all in the JSX, and a caller that wants any of it reads the file. This report is only what the source cannot say. Over MCP it is also the live resource `dapi://context`.
+
+## Output
+
+One JSON object:
+
+```ts
+{
+ rootDir: string | null; // absolute folder projects live under; null until one is picked
+ projectDir: string | null; // absolute open project folder — where the JSX being edited lives; null when none is open
+ currentTime: number | null; // playhead in the active scene, in seconds; null if no scene is active
+ fontFamilies: string[]; // families registered in the running world, valid as `fontFamily`
+ generations: { // every generated source in the project, and where it stands
+ element: string | null; // the element's source stamp, `<file>:<id>`; null for an entity no element produced
+ name: string | null; // the element's `name`, when it has one
+ state: "generating" | "failed" | "done";
+ error?: string; // what it failed with, on `failed` rows
+ asset?: string; // the library path it landed as, on `done` rows
+ }[];
+}
+```
+
+With no project open (the app sits at the dashboard) the report is just `{ rootDir, projectDir: null }`: there is no playhead, no world, and no fonts to speak of. Open one with [`open`](./open.md).
+
+`rootDir` is reported whether or not a project is open — it is where a caller with nothing open goes to create or find one.
+
+`currentTime` is local to the active scene, the same origin a clip's `start` and `end` are placed against, and in the same unit.
+
+`projectDir` is the folder the app is editing, which is not necessarily the one a command was run from: check it before writing to source files.
+
+`fontFamilies` is what text can be drawn with right now — loaded into the world, not merely named in the source — and always includes the editor default. For every family installed on the machine, see [`fonts`](./fonts.md).
+
+`generations` is how a caller waits for `generate.*` declarations without blocking: generation is asynchronous, so poll this until nothing is `generating`. A `done` row's `asset` is a library path, ready for [`media_probe`](./media/probe.md) and its siblings; a `failed` row's `error` is the same message the element carries as its `error` prop, which is what keeps it from being generated again (see [jsx/errors.md](../jsx/errors.md#failed-sources)).
diff --git a/knowledge/reference/tools/export.md b/knowledge/reference/tools/export.md
new file mode 100644
index 00000000..84f5be57
--- /dev/null
+++ b/knowledge/reference/tools/export.md
@@ -0,0 +1,85 @@
+# export
+
+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.
+
+| | |
+| --- | --- |
+| MCP tool | `export` |
+| CLI | `dapi export <id> [output]` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `id` | `string`, required | `<id>` | scene id from the project's JSX, or `file:id` when two files use the same id |
+| `path` | `string` | `[output]` | absolute output file path, ffmpeg-style; its extension picks the container (default: exports/<id>.<format> in the project folder) |
+
+## Rendering
+
+The full render the app's own export runs: the scene re-rendered from a fresh mount at its own size, the workarea from start to end, video and audio, streamed to the output file as it encodes. What [`capture`](./capture.md) shows one frame of, `export` writes all of.
+
+**The settings live in the project, not on the call.** The export is made with the scene's entry in the project's `package.json` — the same entry the app's export panel writes — so a tool export reproduces the in-app one exactly, and the settings version with the project. The call decides only what to export and where to put it; a hand edit to `package.json` is picked up by the running app immediately, no reload needed.
+
+Renders take as long as the scene demands: the CLI waits up to 60 minutes, and an MCP client should give the call a comparable timeout. The app shows the export's progress overlay while it runs, with a working Cancel button; one export runs at a time. Verify frames with [`capture`](./capture.md) and structure with [`check`](./check.md) before spending the render time.
+
+Scenes only: a scene is the unit an export renders, and the error names the scene to export when the id is some other node's.
+
+## Output path
+
+The `path` extension picks the container — `.mp4`, `.webm`, `.ogg` (audio only), `.mov` — overriding the configured format, so the file is always what its name says. A path without one of those extensions is an error. Omitted, the file lands at `exports/<id>.<format>` in the project folder (parent directories are created); an existing file is overwritten. From a shell, a relative path resolves against the working directory.
+
+## Settings
+
+The scene's entry under `diffusion.export.<id>` in the project's `package.json`:
+
+```jsonc
+{
+ "diffusion": {
+ "export": {
+ "intro": {
+ "format": "mp4", // mp4 | webm | ogg | mov
+ "video": {
+ "enabled": true, // false encodes audio only
+ "codec": "avc", // avc | hevc | vp9 | av1 | vp8
+ "bitrate": 12000000, // bits per second
+ "fps": 30, // capture rate; default: the project's
+ "resolution": 1080 // shorter-side "p" number: 720 | 1080 | 1440 | 2160
+ },
+ "audio": {
+ "enabled": true,
+ "codec": "aac", // aac | opus
+ "sampleRate": 48000,
+ "bitrate": 128000
+ }
+ }
+ }
+ }
+}
+```
+
+Every field is optional; the encoder fills what the entry leaves out. A scene without an entry exports with the defaults — 1080p H.264 MP4 with AAC audio, the app's default template. `resolution` scales the scene uniformly until its shorter side reaches the number, so a portrait 1080×1920 scene at `2160` encodes as 2160×3840.
+
+## Output
+
+One JSON object once the file is written:
+
+```ts
+{
+ path: string; // absolute path of the written file
+ width: number; // encoded pixel size (0×0 for an audio-only export)
+ height: number;
+ duration: number; // seconds encoded (the workarea's length)
+ size: number; // bytes written
+ config: { // the settings the export was made with — the package.json
+ format: string; // entry (or the defaults), with the container the
+ video?: {...}; // extension resolved to. Fields the entry left out are
+ audio?: {...}; // absent; the encoder used its defaults for them.
+ }
+}
+```
+
+The echoed `config` is the confirmation of what a `package.json` edit actually did: fields of the wrong type are dropped when the entry is read, so a typoed key shows up here as the default it fell back to.
+
+## Errors
+
+Fails when no project is open (`No project open` — run [`open`](./open.md) first), the id is unknown or ambiguous (pass `file:id`), the id names a node that is not a scene (the error names the scene to export instead), the output path lacks a container extension, the entry's format is unknown, the configuration is unencodable on this machine (codec × resolution × bitrate — the error says what to lower), another export is already running, or the export is canceled in the app. A failed or canceled export deletes the partial file.
diff --git a/knowledge/reference/tools/fetch.md b/knowledge/reference/tools/fetch.md
new file mode 100644
index 00000000..e35544c0
--- /dev/null
+++ b/knowledge/reference/tools/fetch.md
@@ -0,0 +1,48 @@
+# fetch
+
+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).
+
+| | |
+| --- | --- |
+| MCP tool | `fetch` |
+| CLI | `dapi fetch <url> [options]` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `url` | `string`, required | `<url>` | video or page URL to download |
+| `output` | `string` | `-o, --output <path>` | output file path or directory (yt-dlp -o template; default: yt-dlp's default) |
+| `format` | `string` | `-f, --format <selector>` | yt-dlp format selector (default: prefer mp4), e.g. "bv*+ba/b" |
+| `audio` | `boolean` | `-a, --audio` | extract audio only (yt-dlp -x) |
+| `raw` | `string[]` | `-- <yt-dlp flags...>` | raw yt-dlp flags passed through, e.g. ["--sponsorblock-remove", "all"] |
+
+[yt-dlp](https://github.com/yt-dlp/yt-dlp) is not bundled: install it separately (`brew install yt-dlp`, or `pipx install yt-dlp`). The download runs in the app's main process, so no project needs to be open; yt-dlp is looked up on the app's `PATH`, or at `YT_DLP_PATH` in the app's environment when set. Without it the call fails with an install hint before anything is downloaded.
+
+This writes files to disk only; it does not touch the open project. A download becomes an asset by landing under the project's `assets/` folder (see [jsx/media.md](../jsx/media.md)).
+
+## Format
+
+Without `format`, the download prefers mp4/m4a streams and remuxes the result to `.mp4` (`--merge-output-format mp4`), falling back to the best available if no mp4 source exists. `audio` extracts audio only (yt-dlp `-x`) and takes precedence over the mp4 default; an explicit `format` opts out of both.
+
+## Passthrough
+
+`raw` is a list of yt-dlp flags appended verbatim. From a shell they go after `--`:
+
+```sh
+dapi fetch https://youtu.be/xyz -f "bv*+ba/b" -- --sponsorblock-remove all --limit-rate 2M
+```
+
+## Output
+
+One JSON object (a single URL can yield several files, e.g. a playlist):
+
+```ts
+{ paths: string[] } // absolute paths of the files on disk, after any extraction / rename
+```
+
+The resolved path comes from yt-dlp's `after_move:filepath`, so it reflects the real name after audio extraction or renaming, not a guess.
+
+## Errors
+
+Fails when yt-dlp is not installed or not runnable, or when yt-dlp itself fails; its `ERROR` line is the message. Canceling the call kills the download.
diff --git a/knowledge/reference/tools/fonts.md b/knowledge/reference/tools/fonts.md
new file mode 100644
index 00000000..d7aa766c
--- /dev/null
+++ b/knowledge/reference/tools/fonts.md
@@ -0,0 +1,36 @@
+# fonts
+
+List the local fonts available on this machine (macOS only). These family names are valid `fontFamily` values on <text>; each family lists its variants.
+
+| | |
+| --- | --- |
+| MCP tool | `fonts` |
+| CLI | `dapi fonts [options]` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `family` | `string` | `-f, --family <pattern>` | filter to families whose name contains this (case-insensitive) |
+| `weights` | `string[]` | `-w, --weights <weights...>` | filter to variants with the given CSS weights, e.g. ["400", "700"] |
+| `style` | `"normal" \| "italic"` | `-s, --style <style>` | filter to variants with the given style, normal or italic |
+| `limit` | `integer` | `-l, --limit <n>` | return at most this many families |
+
+Font families listed here are valid `fontFamily` values on [`<text>`](../jsx/text.md); see [jsx/fonts.md](../jsx/fonts.md) for how a family and variant are named in a composition, and [`context`](./context.md) for the families the open project has actually registered. Runs in the app's main process, so no project needs to be open.
+
+## Output
+
+One JSON object:
+
+```ts
+{
+ families: Array<{
+ family: string;
+ variants: Array<{
+ weight: string; // CSS weight, e.g. "400"
+ style: "normal" | "italic";
+ source: string; // CSS local() source
+ }>;
+ }>;
+}
+```
diff --git a/knowledge/reference/tools/logs.md b/knowledge/reference/tools/logs.md
new file mode 100644
index 00000000..c7d8ca17
--- /dev/null
+++ b/knowledge/reference/tools/logs.md
@@ -0,0 +1,36 @@
+# logs
+
+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.
+
+| | |
+| --- | --- |
+| MCP tool | `logs` |
+| CLI | `dapi logs [options]` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `tail` | `integer` | `-n, --tail <n>` | return only the last n entries |
+| `level` | `"debug" \| "info" \| "warning" \| "error"` | `-l, --level <level>` | minimum level to include: debug, info, warning, or error |
+
+The buffer lives in the app's main process, so the log survives page reloads and project switches. Over MCP the same entries are the live resource `dapi://logs`. Progress of long operations — an export's percentage, a generation landing — shows up here, so polling `logs` is how a caller follows work it started.
+
+## Output
+
+One JSON object, the entries oldest first:
+
+```ts
+{
+ entries: Array<{
+ ts: number; // unix time, milliseconds
+ level: "debug" | "info" | "warning" | "error";
+ message: string;
+ source: string; // file:line the entry came from (a URL in dev builds); empty for synthetic entries such as renderer crashes and preload errors
+ }>;
+}
+```
+
+## Errors
+
+Fails when `tail` is not a positive integer or `level` is not one of the four levels.
diff --git a/knowledge/reference/tools/media/filmstrip.md b/knowledge/reference/tools/media/filmstrip.md
new file mode 100644
index 00000000..a094ef54
--- /dev/null
+++ b/knowledge/reference/tools/media/filmstrip.md
@@ -0,0 +1,37 @@
+# media_filmstrip
+
+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).
+
+| | |
+| --- | --- |
+| MCP tool | `media_filmstrip` |
+| CLI | `dapi media filmstrip <path> [options]` |
+| CLI aliases | `dapi media film` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `path` | `string`, required | `<path>` | 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) |
+| `start` | `Time` | `-s, --start <time>` | start of the window — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0) |
+| `end` | `Time` | `-e, --end <time>` | end of the window — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: asset duration) |
+| `output` | `string` | `-o, --output <path>` | absolute path to write the PNG to (default: a fresh file under the system temp dir) |
+| `scale` | `number` | `-x, --scale <factor>` | scale factor for the thumbnails; smaller fits more rows and columns, larger fits fewer (default: 1) |
+
+Frames are sampled at even intervals across the window. Tick labels use `HH:MM:SS:FF` timecode (hours, minutes, seconds, frame within the second) at every zoom level, so labels stay comparable regardless of the window's span; frames count against the video's frame rate. Video only; use [`media_waveform`](./waveform.md) to inspect the audio track.
+
+The overall canvas size stays fixed, so a smaller `scale` (clamped to `0.25`–`4`) fits **more rows and columns** — a denser grid sampling more moments — and a larger one fits fewer but shows more detail each. Without `output` the PNG lands in a fresh file under the system temp directory.
+
+## Output
+
+One JSON object, the absolute path to the written PNG. Over MCP the image also arrives inline when it is under a megabyte.
+
+```ts
+{
+ path: string, // e.g. "/tmp/dapi-filmstrip-3f2c1a8e-….png", or the `output` path
+}
+```
+
+## Errors
+
+Fails when the path can't be resolved, the asset isn't a video, `start`/`end` fall outside the asset or cross (`start` >= `end`), `scale` isn't a positive number, or the PNG can't be written.
diff --git a/knowledge/reference/tools/media/grab.md b/knowledge/reference/tools/media/grab.md
new file mode 100644
index 00000000..a76e1caf
--- /dev/null
+++ b/knowledge/reference/tools/media/grab.md
@@ -0,0 +1,66 @@
+# media_grab
+
+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 (separate: true 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.
+
+| | |
+| --- | --- |
+| MCP tool | `media_grab` |
+| CLI | `dapi media grab <path> [options]` |
+| CLI aliases | `dapi media sample` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `path` | `string`, required | `<path>` | 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) |
+| `times` | `Time[]` | `-t, --times <time...>` | 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` | `integer` | `-c, --count <n>` | instead of times, grab this many frames evenly spaced across the clip (or across the start/end window) |
+| `auto` | `boolean` | `-a, --auto` | 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 |
+| `start` | `Time` | `-s, --start <time>` | with count or auto, start of the window to sample (default: 0) |
+| `end` | `Time` | `-e, --end <time>` | with count or auto, end of the window to sample (default: asset duration) |
+| `quality` | `"small" \| "medium" \| "large" \| "fullres"` | `-q, --quality <preset>` | frame resolution: small (384x384), medium (768x768), large (1536x1536), or fullres (native); default: as large as the sheet cell allows, or small with separate: true |
+| `separate` | `boolean` | `-S, --separate` | write one image per position instead of merging them into contact sheets of up to 12 cells, each labelled with its timecode |
+| `perSheet` | `integer` | `--per-sheet <n>` | positions per contact sheet, 1-12; fewer means a larger cell each (default: as many as fit) |
+| `uncapped` | `boolean` | `--uncapped` | lift the 100-frame safety cap (grabbing many frames is slow and token-heavy) |
+| `output` | `string` | `-o, --output <dir>` | absolute directory to write the PNGs into (default: a fresh directory under the system temp dir) |
+
+## Sampling
+
+Three ways to say which frames, mutually exclusive:
+
+- `times`: explicit timestamps in source time. A negative value counts back from the end of the clip, so `-1` is one second before the end and `-1f` one frame before it.
+- `count`: that many frames evenly spaced across the clip, or across the `start`/`end` window, at a fixed interval of `window / count`, starting at the window start.
+- `auto`: a scan at 2 fps that keeps a frame each time the picture settles into a new visual state, dropping near-duplicates and waiting out transitions so picks stay sharp. Returns at most `count` frames (default cap 30); static footage such as a screen recording returns far fewer. Needs WebGPU.
+
+`start` and `end` only apply with `count` or `auto`. Like [`capture`](../capture.md), but this grabs the asset's own pixels; `capture` renders the composited node. Renders locally; no credits. Past ~12 frames, [`media_filmstrip`](./filmstrip.md) is the cheaper way to scan a clip.
+
+With `separate`, frames keep their own resolution and alpha, and each file is named after its timecode (e.g. `01s12f.png`). Without an `output` directory the images land in a fresh `dapi-grab-*` directory under the system temp directory, so runs never overwrite each other. Writing into the same directory twice overwrites images whose name matches; with `separate`, requested times that land on the same frame share one file.
+
+## Timecodes
+
+Cell labels, the `timecode` field, and the filenames all use the same stamp, which drops its zero segments: `08s10f` is 8 seconds and 10 frames, `01m05s` is 65 seconds, and the first frame is `0f`. Each segment carries its unit, so nothing is ambiguous once the empty ones are gone. (The rulers [`media_filmstrip`](./filmstrip.md) and [`media_waveform`](./waveform.md) draw stay on fixed-width `HH:MM:SS:FF`, so their ticks line up.)
+
+## Layout
+
+A sheet never exceeds 2576x1456, the largest image a vision model reads at full detail. Within that budget the grid is the one that draws each frame largest, frames are never enlarged past their source resolution, and the last row may be partially filled. Sheets are named after the span they cover, e.g. `0f-08s10f.png`. For 16:9 footage the cell sizes are:
+
+| Frames | Grid | Per-frame |
+|---|---|---|
+| 1 | 1x1 | 2568x1444 |
+| 2-4 | 2x1, 2x2 | 1280x720 |
+| 5-9 | 3x2, 3x3 | 850x478 |
+| 10-12 | 4x3 | 636x358 |
+
+## Output
+
+One JSON object with one entry per written image: a contact sheet by default, a frame with `separate`.
+
+```ts
+{ images: Array<{ timecode: string; path: string }> } // e.g. { "images": [{ "timecode": "0f-08s10f", "path": "…/0f-08s10f.png" }] }
+```
+
+A sheet's timecode is the span it covers; a frame's is its own. Sheets come in time order, and their cells in the order the times were requested in. Over MCP, up to four images of at most a megabyte each also arrive inline.
+
+## Errors
+
+Fails when the path can't be resolved, the asset is not a video, any of `times` is past the asset's duration, the window is empty or `start` is not before `end`, `times` is combined with `count` or `auto`, `start`/`end` are given without `count` or `auto`, `perSheet` is outside 1 to 12 or combined with `separate`, more than 100 frames are requested without `uncapped`, or a PNG can't be written.
diff --git a/knowledge/reference/tools/media/listen.md b/knowledge/reference/tools/media/listen.md
new file mode 100644
index 00000000..a4dcc40d
--- /dev/null
+++ b/knowledge/reference/tools/media/listen.md
@@ -0,0 +1,31 @@
+# media_listen
+
+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; of a video only the audio track is analyzed. Needs a signed-in account.
+
+| | |
+| --- | --- |
+| MCP tool | `media_listen` |
+| CLI | `dapi media listen <path> [options]` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `path` | `string`, required | `<path>` | 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) |
+| `prompt` | `string` | `-p, --prompt <str>` | question or instruction to guide the analysis |
+| `start` | `Time` | `-s, --start <time>` | start of the segment to analyze (default: 0); timestamps in the analysis are relative to this point |
+| `end` | `Time` | `-e, --end <time>` | end of the segment to analyze (default: media duration) |
+
+With no `prompt` it returns a general description of what is heard; with one it answers that question about the audio (e.g. "who is speaking?", "what music is playing?", "summarize what is said"). See [the prompt guide](../../../guides/prompts/media-listen.md) for prompts that work. Costs credits, and needs a signed-in account ([`whoami`](../whoami.md)).
+
+## Output
+
+One JSON object, the model's answer. `start`/`end` echo the analyzed window (in seconds) and are present only when a window was given:
+
+```ts
+{ result: string, start?: number, end?: number }
+```
+
+## Errors
+
+Fails when the path can't be resolved, the asset isn't a video or audio asset, `start`/`end` cross (`start` >= `end`), or no account is signed in.
diff --git a/knowledge/reference/tools/media/probe.md b/knowledge/reference/tools/media/probe.md
new file mode 100644
index 00000000..55559028
--- /dev/null
+++ b/knowledge/reference/tools/media/probe.md
@@ -0,0 +1,37 @@
+# media_probe
+
+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.
+
+| | |
+| --- | --- |
+| MCP tool | `media_probe` |
+| CLI | `dapi media probe <path>` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `path` | `string`, required | `<path>` | 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) |
+
+Like `ffprobe`, but demuxed locally with mediabunny; any asset type is accepted.
+
+## Output
+
+One JSON object. The shape is **not yet stable**: it reports whatever mediabunny surfaces about the container and its tracks. Packet stats (frame rate, bitrate, packet count) are estimated from a leading sample of packets, so they are fast but approximate. Assets mediabunny can't demux (images, transcripts) don't error; they report file-level info only, with `format: null` and no tracks.
+
+```ts
+{
+ id: string; name: string; path: string; type: string;
+ mimeType?: string;
+ size: number; // bytes
+ width?: number; height?: number;
+ format: string | null; // container name; null when the file could not be read as media
+ duration?: number; // seconds
+ tags?: Record<string, unknown>;
+ tracks: Array<{ id: number; type: string; codec: string | null; language: string; firstTimestamp: number; duration: number; /* … */ }>;
+}
+```
+
+## Errors
+
+Fails when the path can't be resolved.
diff --git a/knowledge/reference/tools/media/transcribe.md b/knowledge/reference/tools/media/transcribe.md
new file mode 100644
index 00000000..653eedca
--- /dev/null
+++ b/knowledge/reference/tools/media/transcribe.md
@@ -0,0 +1,33 @@
+# media_transcribe
+
+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).
+
+| | |
+| --- | --- |
+| MCP tool | `media_transcribe` |
+| CLI | `dapi media transcribe <path>` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `path` | `string`, required | `<path>` | 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) |
+
+Times are in **seconds** of source/content time. The whole asset is transcribed once per app session (cached in memory, keyed by file content; an app restart or an edited file re-transcribes).
+
+## Output
+
+One JSON object, the transcript:
+
+```ts
+{
+ segments: Array<{
+ text: string; // spoken words only (no silence markers)
+ words: Array<{ text: string; start: number; end: number }>; // seconds
+ }>;
+}
+```
+
+## Errors
+
+Fails when the path can't be resolved, the asset is not a video/audio asset, or no speech is detected in the audio at all (`No speech detected`).
diff --git a/knowledge/reference/tools/media/waveform.md b/knowledge/reference/tools/media/waveform.md
new file mode 100644
index 00000000..9e6fe0be
--- /dev/null
+++ b/knowledge/reference/tools/media/waveform.md
@@ -0,0 +1,38 @@
+# media_waveform
+
+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.
+
+| | |
+| --- | --- |
+| MCP tool | `media_waveform` |
+| CLI | `dapi media waveform <path> [options]` |
+| CLI aliases | `dapi media wave` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `path` | `string`, required | `<path>` | 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) |
+| `start` | `Time` | `-s, --start <time>` | start of the window — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0) |
+| `end` | `Time` | `-e, --end <time>` | end of the window — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: asset duration) |
+| `output` | `string` | `-o, --output <path>` | absolute path to write the PNG to (default: a fresh file under the system temp dir) |
+| `scale` | `number` | `-x, --scale <factor>` | scale factor for the thumbnails; smaller fits more rows and columns, larger fits fewer (default: 1) |
+
+Loudness over time is drawn from decoded audio peaks. Tick labels use `HH:MM:SS:FF` timecode (hours, minutes, seconds, frame within the second) at every zoom level, so labels stay comparable regardless of the window's span. For a video, frames count against the video's frame rate; for a standalone audio asset, the ruler counts against a nominal 30 fps.
+
+The overall canvas size stays fixed, so a smaller `scale` (clamped to `0.25`–`4`) fits **more rows and columns** — a denser time axis — and a larger one fits fewer but taller rows. Without `output` the PNG lands in a fresh file under the system temp directory.
+
+## Output
+
+One JSON object: the absolute path to the written PNG plus the silent stretches (the red spans on the waveform) as `[start, end]` second ranges, in absolute seconds (offset by `start` when a window is used). Over MCP the image also arrives inline when it is under a megabyte.
+
+```ts
+{
+ path: string, // e.g. "/tmp/dapi-waveform-3f2c1a8e-….png", or the `output` path
+ silences: Array<{ start: number, end: number }>,
+}
+```
+
+## Errors
+
+Fails when the path can't be resolved, the asset has no decodable audio track, `start`/`end` fall outside the asset or cross (`start` >= `end`), `scale` isn't a positive number, or the PNG can't be written.
diff --git a/knowledge/reference/tools/models.md b/knowledge/reference/tools/models.md
new file mode 100644
index 00000000..ea67dee0
--- /dev/null
+++ b/knowledge/reference/tools/models.md
@@ -0,0 +1,33 @@
+# models
+
+List available AI generation models and their per-model constraints (durations, aspect ratios, features), for `generate.*` asset declarations in a project module.
+
+| | |
+| --- | --- |
+| MCP tool | `models` |
+| CLI | `dapi models [type]` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `type` | `"image" \| "video" \| "audio"` | `[type]` | filter to one kind of model, image, video, or audio (default: all three) |
+
+Use it to discover valid model ids and the per-model constraints (durations, aspect ratios, features) to set on an asset declaration (see [jsx/generate.md](../jsx/generate.md)). No tool generates: asset generation is declared in the project module and produced on mount.
+
+## Output
+
+One JSON object:
+
+```ts
+{
+ models: Array<{
+ type: "image" | "video" | "audio";
+ id: string; // the model id to set on a generate.* declaration
+ name: string;
+ durations?: string[]; // video only, e.g. ["5s","10s"]
+ aspectRatios?: string[]; // video only
+ features?: Array<"start-frame" | "end-frame" | "audio">; // video only
+ }>;
+}
+```
diff --git a/knowledge/reference/tools/open.md b/knowledge/reference/tools/open.md
new file mode 100644
index 00000000..251687bc
--- /dev/null
+++ b/knowledge/reference/tools/open.md
@@ -0,0 +1,49 @@
+# open
+
+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).
+
+| | |
+| --- | --- |
+| MCP tool | `open` |
+| CLI | `dapi open [path] [options]` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `dir` | `string`, required | `[path]` | absolute path of the project folder to open or create |
+| — | | `-b, --background` | launch or keep the app in the background, without raising a window (CLI only) |
+
+## What opening writes
+
+The folder may live anywhere on disk, and does not have to be a project yet. Opening is what makes it one, writing as little as that takes:
+
+- a missing folder is created;
+- a folder with no entry file (package.json `main`, or `index.tsx` and friends) gains an `index.tsx` holding an empty stage.
+
+Nothing else is written — no package.json, tsconfig, README, or manifest. A project is its JSX; the rest of the scaffold appears lazily, each piece when something first needs it. A folder that is already a project is opened untouched, wherever it lives.
+
+The app remembers the folder, so the project reopens across app relaunches and stays addressable by folder name or project id.
+
+## From a shell
+
+`dapi open` is also how the app starts: it launches Diffusion Studio (macOS) or surfaces the running instance, then, given a path, calls the tool. With no path it only makes sure the app is up, printing nothing and exiting `0` once the app answers. Relative paths resolve against the shell's working directory. `--background` launches or keeps the app without raising a window — the way to drive the editor headless.
+
+Over MCP the app is already running, since that is what the connection is to; the tool only opens the folder, and `dir` must be absolute.
+
+## Output
+
+The opened project:
+
+```ts
+{
+ id: string; // package.json `projectId`; "" until the project has a record
+ name: string; // display name (falls back to the folder name)
+ dir: string; // absolute project folder, as opened
+}
+```
+
+## Errors
+
+- The path exists but is not a folder.
+- From a shell off macOS, the app cannot be launched; the command then requires it to already be running.
diff --git a/knowledge/reference/tools/report.md b/knowledge/reference/tools/report.md
new file mode 100644
index 00000000..6eac3190
--- /dev/null
+++ b/knowledge/reference/tools/report.md
@@ -0,0 +1,72 @@
+# report
+
+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.
+
+| | |
+| --- | --- |
+| MCP tool | `report` |
+| CLI | `dapi report <title> [options]` |
+| CLI aliases | `dapi issue` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `title` | `string`, required | `<title>` | one-line summary of the problem |
+| `body` | `string` | `-b, --body <text>` | what happened, in markdown: expected vs actual, and anything the diagnostics won't show |
+| `commands` | `string[]` | `-c, --commands <cmd...>` | the dapi commands or tool calls that reproduce it, in order |
+| `logs` | `integer` | `--logs <n>` | trailing app log entries to attach (0 to omit; default: 50) |
+
+For a tool that errors, contradicts this reference, or returns something it shouldn't. The description is bundled with diagnostics (app version, platform, Electron version, the app's recent console output) and filed as a GitHub issue on [diffusionstudio/editor](https://github.com/diffusionstudio/editor/issues).
+
+The issue is submitted immediately, with no review step: the call returns once the issue exists. Filing goes through the [`gh`](https://cli.github.com) CLI, which must be installed and authenticated (`gh auth login`) on this machine; without it nothing is filed. It runs in the app's main process, so no project needs to be open.
+
+This is for defects in the tooling, not for problems inside a project: a composition that looks wrong, a node in the wrong place, or a generation that missed the prompt are editing problems, not reported here.
+
+## Output
+
+One JSON object:
+
+```ts
+{
+ url: string // the created github.com/diffusionstudio/editor issue
+}
+```
+
+## Issue layout
+
+The title is the issue title; the body is assembled from the fields and the diagnostics:
+
+````md
+<body>
+
+## Repro
+
+```sh
+dapi capture intro
+```
+
+## Environment
+
+| | |
+| --- | --- |
+| app | 0.204.1 |
+| platform | darwin 25.5.0 (arm64) |
+| electron | 38.2.0 |
+
+## App logs
+
+```
+19:37:17.538 [info] Finalizing file (…)
+```
+````
+
+`commands` are rendered as a shell block under `## Repro`, in the order given; from a shell, `-c` is repeatable (`-c "dapi context" -c "dapi capture intro"`). `logs: 0` omits the log section.
+
+## Notes
+
+- Attached logs are the same entries [`logs`](./logs.md) returns, and can contain project names, file paths, and prompt text. They go straight to a public issue: pass `logs: 0`, or check what [`logs`](./logs.md) currently holds, before reporting from a sensitive project.
+
+## Errors
+
+Fails on an empty title, a `logs` value below 0, a missing `gh`, or a failure from `gh` (not authenticated, no access to the repo); the message from `gh` is passed through.
diff --git a/knowledge/reference/tools/screenshot.md b/knowledge/reference/tools/screenshot.md
new file mode 100644
index 00000000..0bfd1801
--- /dev/null
+++ b/knowledge/reference/tools/screenshot.md
@@ -0,0 +1,24 @@
+# screenshot
+
+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.
+
+| | |
+| --- | --- |
+| MCP tool | `screenshot` |
+| CLI | `dapi screenshot [options]` |
+
+## Input
+
+| Field | Type | CLI | Description |
+| --- | --- | --- | --- |
+| `output` | `string` | `-o, --output <dir>` | absolute directory to write the PNGs into (default: a fresh directory under the system temp dir) |
+
+The shot is taken from the app's own window buffer, so it works even when the window is hidden or covered by other windows, and never includes anything outside the app. The file is named `diffusion-studio_<date>_<time>.png`; without an `output` directory it lands in the system temp directory.
+
+## Output
+
+One JSON object: the absolute path to the freshly written PNG, plus the image's pixel dimensions. Over MCP the image also arrives inline when it is under a megabyte.
+
+```ts
+{ path: string, width: number, height: number }
+```
diff --git a/knowledge/reference/tools/voices.md b/knowledge/reference/tools/voices.md
new file mode 100644
index 00000000..305e71a6
--- /dev/null
+++ b/knowledge/reference/tools/voices.md
@@ -0,0 +1,22 @@
+# voices
+
+List the speech voices available for `generate.voice` declarations in a project module.
+
+| | |
+| --- | --- |
+| MCP tool | `voices` |
+| CLI | `dapi voices` |
+
+## Input
+
+None.
+
+See [jsx/generate.md](../jsx/generate.md) for the declaration a voice id goes on.
+
+## Output
+
+One JSON object:
+
+```ts
+{ voices: Array<{ id: string; label: string; description: string }> }
+```
diff --git a/knowledge/reference/tools/whoami.md b/knowledge/reference/tools/whoami.md
new file mode 100644
index 00000000..8d67f713
--- /dev/null
+++ b/knowledge/reference/tools/whoami.md
@@ -0,0 +1,20 @@
+# whoami
+
+Report the authenticated account, or null if signed out.
+
+| | |
+| --- | --- |
+| MCP tool | `whoami` |
+| CLI | `dapi whoami` |
+
+## Input
+
+None.
+
+## Output
+
+One JSON object:
+
+```ts
+{ user: { id: string; email?: string } | null }
+```
diff --git a/knowledge/skills/editor.md b/knowledge/skills/editor.md
new file mode 100644
index 00000000..e7266e6b
--- /dev/null
+++ b/knowledge/skills/editor.md
@@ -0,0 +1,77 @@
+# Footage analysis
+
+How to understand source material before editing it. Inspect only the modalities the decision turns on — speech, action, music, graphics, or atmosphere may lead, so there is no fixed priority. Sample the picture against what the audio tells you.
+
+- **Always probe first.** `media_probe` reports the container and its tracks, telling you up front whether the file has a video track, an audio track, or both. Everything after branches on that.
+- **Get the lay of the land.** Render a `media_waveform` (audio) and a `media_filmstrip` (video) for a fast, cheap overview of where the loud and quiet stretches fall, and where the visual scene changes are. A filmstrip shows coarse structure and scene state, not crop, framing, readability, or an exact cut frame.
+- **Listen to the audio.** Run `media_listen` with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See [media-listen.md](../guides/prompts/media-listen.md) for prompt patterns.
+- **Transcribe speech.** For speech, `media_transcribe` returns the full transcript with word-level start/end times directly — read any segment straight from it.
+- **Sample the video against the audio.** Use `media_grab` to pull frames. When the audio has already pointed you at specific moments, feed those timestamps straight in from the transcript or listen output as `times` (e.g. `00:32`, `00:45`). When you need a visual pass without such cues, reach for `auto`: it scans the footage and keeps only the frames where the picture settles into a new visual state, dropping near-duplicates.
+
+# The editing loop
+
+- Write the brief first. For anything nontrivial, capture the edit as a markdown file: it is the plan every save works toward and the thing to check the result against.
+- Lay down the A-roll. Assemble the primary footage as JSX and save. Get the spine of the edit right before anything else.
+- Layer the rest on top. Once the A-roll holds, add B-roll and secondary assets (sound effects, captions, overlays) in the same source.
+- Symlink media the project uses into its `assets/` folder and name it by library path (`assets/b-roll/drone.mp4` is `"b-roll/drone.mp4"`); local and remote paths work too but stay outside the library.
+- `context` reports which folder the app actually has open, where the playhead sits, and where every `generate.*` declaration stands — poll it to wait for generations without blocking.
+
+**The source is the document.** A project is a folder of JSX; `open` a folder once, then write the files and save. Saving recompiles and re-renders the canvas.
+
+# Compositing
+
+- Chrome, scaffolding, and ornament all draw from a visual budget whose default balance is `0`; prefer not to use them. A cut, hold, or change of size can separate two ideas as clearly as a divider without adding visual clutter. An element earns its place by deepening the story, guiding attention, or expanding imagination, never by filling space.
+- Video is its own medium, with its own rules; it is not a website, poster, slide, or UI. It is watched, not read.
+- Don't darken, blur, or cover the picture to make something on top of it legible
+- Let visuals, sound, and voice carry context; let text punctuate rather than explain. Do not add copy, eyebrows, labels, underlines, or brand color highlights unless the brief or explicit video guidance calls for them; examples alone are not instructions.
+- Choose easing from the intended weight, energy, and continuity of the action.
+- When the brief, project, or user specifies branding, follow it. Only when none is specified, fall back to the [Diffusion Studio brand](../brand/README.md) — its design, voice, video, and library references, and the components and compositions bundled with them.
+
+# Verification
+
+How to confirm a change actually produced what you intended. A clean save does not guarantee a correct-looking composition.
+
+- Run `check` on the scene first. It catches black frames, clips that never become visible, zero-duration or fully transparent nodes, and assets that failed to load or generate.
+- Use `capture` on the scene to see what the viewer actually gets.
+- Reconcile captured frames with the brief, and the brief with these guidelines.
+- Verify after every stage, not only at the end — build the composition incrementally so a problem is caught next to the change that caused it.
+- Scale verification to the change. A small or incremental tweak the user asked for needs no visual confirmation so the user gets the result back fast and can keep iterating.
+- Fix the largest viewer-facing problem before polishing details, and recheck related moments after structural changes, since pacing, continuity, emphasis, and meaning are relational.
+- Use `screenshot` or `logs` to debug issues.
+- DO NOT export/render the scene for visual confirmation — `capture` is equivalent to a render but far more efficient. Rendering to a video should be a user-triggered action unless explicitly requested in the prompt.
+
+# Best practices
+
+- Wrap clips in `<sequence>` tags wherever the parent tag supports it — A-roll, B-roll, and other clips belong in sequences so the timeline stays structured rather than a flat, messy pile. A sequence does not place its children: give every clip an explicit `start`.
+- Use the built-in tags for the media a composition is made of (audio, video, images, captions).
+- Hoist the properties that define the composition's look — title copy, font family and size, accent colors, key padding — into top-level consts annotated with `@inspect`, so they become live controls in the app's inspector.
+- For anything 3D, use Three.js drawn into a `<surface>` tag.
+- For motion graphics, overlays and UI-heavy graphics, the `<html>` tag driven by a paused [anime.js](https://animejs.com) timeline
+- Before animating anything, read the [easings reference](../guides/motion/easings.md) and choose easings deliberately — default or linear easing is what makes motion read as a slideshow.
+- Add auto captions last, after everything else is assembled, so they transcribe the finished audio at its final placement.
+- For tasks that don't need an editing UI, keep the app in the background: from a shell, `dapi open -b <dir>` launches it that way. Over MCP the app is already running, and `open` only opens the folder.
+- Only render (export) the result when prompted.
+- Start with a fresh project.
+
+# Docs
+
+The authoring reference is served by the app for the installed version: read it there and trust it over memory.
+
+- [JSX reference — elements, timing, paints, generation, captions](../reference/jsx/README.md)
+- [Tool reference — every tool, its fields, its CLI spelling and its output](../reference/tools/README.md)
+- [Examples — complete compositions, basics through shaders](../examples/README.md)
+- [Easings: which cubic-bezier to use and when](../guides/motion/easings.md)
+- [Diffusion Studio brand — the fallback when no other branding is specified](../brand/README.md)
+
+# Examples
+
+Read worked example(s) that match your context.
+
+## Video editing
+
+- [Long-form talking head](../guides/walkthroughs/talking-head.md)
+- [Podcast clipping](../guides/walkthroughs/podcast-clip.md)
+
+## Prompts
+
+- [Writing prompts for `media_listen`](../guides/prompts/media-listen.md)
diff --git a/knowledge/skills/watch.md b/knowledge/skills/watch.md
new file mode 100644
index 00000000..c44de813
--- /dev/null
+++ b/knowledge/skills/watch.md
@@ -0,0 +1,28 @@
+# Watching footage
+
+How to understand source material. Inspect only the modalities the question turns on — speech, action, music, graphics, or atmosphere may lead, so there is no fixed priority. Sample the picture against what the audio tells you.
+
+- **Always probe first.** `media_probe` reports the container and its tracks, telling you up front whether the file has a video track, an audio track, or both. Everything after branches on that.
+- **Get the lay of the land.** Render a `media_waveform` (audio) and a `media_filmstrip` (video) for a fast, cheap overview of where the loud and quiet stretches fall, and where the visual scene changes are. A filmstrip shows coarse structure and scene state, not crop, framing, readability, or an exact cut frame.
+- **Listen to the audio.** Run `media_listen` with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See [media-listen.md](../guides/prompts/media-listen.md) for prompt patterns.
+- **Transcribe speech.** For speech, `media_transcribe` returns the full transcript with word-level start/end times directly — read any segment straight from it.
+- **Sample the video against the audio.** Use `media_grab` to pull frames. When the audio has already pointed you at specific moments, feed those timestamps straight in from the transcript or listen output as `times` (e.g. `00:32`, `00:45`). When you need a visual pass without such cues, reach for `auto`: it scans the footage and keeps only the frames where the picture settles into a new visual state, dropping near-duplicates.
+
+# Matching depth to the question
+
+Read only as much of the footage as the answer requires — each pass costs time, and `media_listen` costs credits.
+
+- A duration or format question ends at `media_probe`.
+- "Where is the quiet part" or "how is it paced" is usually answered by the waveform and filmstrip alone.
+- A question about what was said resolves fastest through `media_transcribe`; quote the transcript and its times directly.
+- Questions about non-speech audio (music, tone, sound events, speaker identity) are what `media_listen` is for.
+- Only questions about what is *seen* need frames — and the audio pass usually tells you which moments to grab, so grab those instead of scanning blind.
+- For open-ended questions ("summarize this", "what happens here"), combine passes: structure from waveform + filmstrip, content from transcript or listen, then frames at the salient moments to confirm what the picture shows.
+
+# Answering
+
+- Ground every claim in something you actually saw or heard — a transcript line, a listen answer, a grabbed frame. If the evidence is ambiguous, say so rather than smoothing over it.
+- Anchor answers to the timeline. Give timestamps as `MM:SS` (or `HH:MM:SS` for long footage) so the user can jump straight to the moment; for a scene or segment, give its start and end.
+- When asked to find a scene or moment, return the timestamp range plus a one-line description of what identifies it, so the user can confirm it is the right one.
+- Summaries follow the footage's own structure: what happens, in order, with the timestamps where each part begins. Length matches what the user asked for, not what the footage contains.
+- This skill only reads footage. When the user wants the footage changed — cut, composed, captioned, exported — that is the `editor` skill's job.
diff --git a/package-lock.json b/package-lock.json
index d48abb1a..befb5b44 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -22,22 +22,17 @@
"version": "0.204.1",
"license": "MPL-2.0",
"dependencies": {
- "@babel/core": "^7.29.7",
- "@babel/preset-typescript": "^7.27.1",
- "@trpc/client": "^11.18.0",
- "@trpc/server": "^11.18.0",
- "babel-preset-solid": "^1.9.12",
+ "@diffusionstudio/dapi": "*",
+ "@modelcontextprotocol/sdk": "^1.30.0",
"commander": "^14.0.3",
- "esbuild": "^0.28.1",
- "ws": "^8.18.3"
+ "zod": "^4.4.3"
},
"bin": {
"dapi": "dist/index.js"
},
"devDependencies": {
- "@types/babel__core": "^7.20.5",
"@types/node": "^24.10.1",
- "@types/ws": "^8.18.1",
+ "esbuild": "^0.28.1",
"typescript": "~5.9.3"
}
},
@@ -48,8 +43,9 @@
"dependencies": {
"@babel/core": "^7.29.7",
"@babel/preset-typescript": "^7.27.1",
- "@diffusionstudio/cli": "*",
+ "@diffusionstudio/dapi": "*",
"@diffusionstudio/jsx": "*",
+ "@modelcontextprotocol/sdk": "^1.30.0",
"babel-preset-solid": "^1.9.12",
"esbuild": "^0.28.1",
"nanoid": "^6.0.1",
@@ -65,7 +61,8 @@
"@types/babel__core": "^7.20.5",
"@types/node": "^24.10.1",
"electron": "^43.1.1",
- "typescript": "~5.9.3"
+ "typescript": "~5.9.3",
+ "vitest": "^4.0.0"
}
},
"apps/desktop/node_modules/nanoid": {
@@ -93,7 +90,7 @@
"dependencies": {
"@diffusionstudio/api-contract": "^0.1.0",
"@diffusionstudio/assets": "*",
- "@diffusionstudio/cli": "*",
+ "@diffusionstudio/dapi": "*",
"@diffusionstudio/encoder": "*",
"@diffusionstudio/jsx": "*",
"@diffusionstudio/koota-solid": "*",
@@ -623,6 +620,10 @@
"resolved": "apps/cli",
"link": true
},
+ "node_modules/@diffusionstudio/dapi": {
+ "resolved": "packages/dapi",
+ "link": true
+ },
"node_modules/@diffusionstudio/desktop": {
"resolved": "apps/desktop",
"link": true
@@ -2002,6 +2003,18 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/@hono/node-server": {
+ "version": "2.1.1",
+ "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.1.tgz",
+ "integrity": "sha512-ELuehkj5VCBdgEw9zs+ivkKwyzzUCSQuE96YmiPvn1ECBoZCczbFXJLeEGMTYjphP6gydh4pHMqEYPVMYUVgQg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=20"
+ },
+ "peerDependencies": {
+ "hono": "^4"
+ }
+ },
"node_modules/@humanfs/core": {
"version": "0.19.2",
"resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.2.tgz",
@@ -2468,6 +2481,85 @@
"node": ">= 12.13.0"
}
},
+ "node_modules/@modelcontextprotocol/sdk": {
+ "version": "1.30.0",
+ "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.30.0.tgz",
+ "integrity": "sha512-xKd8OIzlqNzcqcNumGAa6g+PW2kjD5vrpcKOnfldAUPP3j7lnqMPwlTXQm8gF+UwH72z0lqaRbjr9hqGz0eITA==",
+ "license": "MIT",
+ "dependencies": {
+ "@hono/node-server": "^1.19.9 || ^2.0.5",
+ "ajv": "^8.17.1",
+ "ajv-formats": "^3.0.1",
+ "content-type": "^1.0.5",
+ "cors": "^2.8.5",
+ "cross-spawn": "^7.0.5",
+ "eventsource": "^3.0.2",
+ "eventsource-parser": "^3.0.0",
+ "express": "^5.2.1",
+ "express-rate-limit": "^8.2.1",
+ "hono": "^4.11.4",
+ "jose": "^6.1.3",
+ "json-schema-typed": "^8.0.2",
+ "pkce-challenge": "^5.0.0",
+ "raw-body": "^3.0.0",
+ "zod": "^3.25 || ^4.0",
+ "zod-to-json-schema": "^3.25.1"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "peerDependencies": {
+ "@cfworker/json-schema": "^4.1.1",
+ "zod": "^3.25 || ^4.0"
+ },
+ "peerDependenciesMeta": {
+ "@cfworker/json-schema": {
+ "optional": true
+ },
+ "zod": {
+ "optional": false
+ }
+ }
+ },
+ "node_modules/@modelcontextprotocol/sdk/node_modules/ajv": {
+ "version": "8.20.0",
+ "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+ "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
+ "license": "MIT",
+ "dependencies": {
+ "fast-deep-equal": "^3.1.3",
+ "fast-uri": "^3.0.1",
+ "json-schema-traverse": "^1.0.0",
+ "require-from-string": "^2.0.2"
+ },
+ "funding": {
+ "type": "github",
+ "url": "https://github.com/sponsors/epoberezkin"
+ }
+ },
+ "node_modules/@modelcontextprotocol/sdk/node_modules/ajv-formats": {
+ "version": "3.0.1",
+ "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz",
+ "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==",
+ "license": "MIT",
+ "dependencies": {
+ "ajv": "^8.0.0"
+ },
+ "peerDependencies": {
+ "ajv": "^8.0.0"
+ },
+ "peerDependenciesMeta": {
+ "ajv": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/@modelcontextprotocol/sdk/node_modules/json-schema-traverse": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+ "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+ "license": "MIT"
+ },
"node_modules/@nodelib/fs.scandir": {
"version": "2.1.5",
"resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz",
@@ -3535,6 +3627,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 +4176,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 +4198,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",
@@ -4209,16 +4326,6 @@
"dev": true,
"license": "MIT"
},
- "node_modules/@types/ws": {
- "version": "8.18.1",
- "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
- "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
- "dev": true,
- "license": "MIT",
- "dependencies": {
- "@types/node": "*"
- }
- },
"node_modules/@types/yauzl": {
"version": "2.10.3",
"resolved": "https://registry.npmjs.org/@types/yauzl/-/yauzl-2.10.3.tgz",
@@ -4502,6 +4609,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",
@@ -4715,6 +4935,64 @@
"dev": true,
"license": "ISC"
},
+ "node_modules/accepts": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
+ "integrity": "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==",
+ "license": "MIT",
+ "dependencies": {
+ "mime-types": "^3.0.0",
+ "negotiator": "^1.0.0"
+ },
+ "engines": {
+ "node": ">= 0.6"
+ }
+ },
+ "node_modules/accepts/node_modules/content-type": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz",
+ "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/accepts/node_modules/mime-types": {
+ "version": "3.0.2",
+ "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz",
+ "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==",
+ "license": "MIT",
+ "dependencies": {
+ "mime-db": "^1.54.0"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/accepts/node_modules/negotiator": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.1.0.tgz",
+ "integrity": "sha512-NMPBRMJgiQHjbd8phG3Vebdx4kZ1H121rbl5IkMqeOsahptB9BKo/d7oJ3zTXqTgagn2bWlNSXkh0QUGM31RYg==",
+ "license": "MIT",
+ "dependencies": {
+ "content-type": "^2.1.0"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
"node_modules/acorn": {
"version": "8.17.0",
"resolved": "https://registry.npmjs.org/acorn/-/acorn-8.17.0.tgz",
@@ -4951,6 +5229,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",
@@ -5119,6 +5407,59 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/body-parser": {
+ "version": "2.3.0",
+ "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.3.0.tgz",
+ "integrity": "sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==",
+ "license": "MIT",
+ "dependencies": {
+ "bytes": "^3.1.2",
+ "content-type": "^2.0.0",
+ "debug": "^4.4.3",
+ "http-errors": "^2.0.1",
+ "iconv-lite": "^0.7.2",
+ "on-finished": "^2.4.1",
+ "qs": "^6.15.2",
+ "raw-body": "^3.0.2",
+ "type-is": "^2.1.0"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/body-parser/node_modules/content-type": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz",
+ "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/body-parser/node_modules/iconv-lite": {
+ "version": "0.7.3",
+ "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.3.tgz",
+ "integrity": "sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ==",
+ "license": "MIT",
+ "dependencies": {
+ "safer-buffer": ">= 2.1.2 < 3.0.0"
+ },
+ "engines": {
+ "node": ">=0.10.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
"node_modules/boolbase": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz",
@@ -5252,6 +5593,15 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/bytes": {
+ "version": "3.1.2",
+ "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
+ "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.8"
+ }
+ },
"node_modules/cacache": {
"version": "16.1.3",
"resolved": "https://registry.npmjs.org/cacache/-/cacache-16.1.3.tgz",
@@ -5394,7 +5744,6 @@
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
"integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
- "dev": true,
"license": "MIT",
"dependencies": {
"es-errors": "^1.3.0",
@@ -5408,7 +5757,6 @@
"version": "1.0.4",
"resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz",
"integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==",
- "dev": true,
"license": "MIT",
"dependencies": {
"call-bind-apply-helpers": "^1.0.2",
@@ -5451,6 +5799,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",
@@ -5770,16 +6128,73 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/content-disposition": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.1.0.tgz",
+ "integrity": "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/content-type": {
+ "version": "1.0.5",
+ "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz",
+ "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.6"
+ }
+ },
"node_modules/convert-source-map": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
"integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
"license": "MIT"
},
- "node_modules/cross-dirname": {
- "version": "0.1.0",
- "resolved": "https://registry.npmjs.org/cross-dirname/-/cross-dirname-0.1.0.tgz",
- "integrity": "sha512-+R08/oI0nl3vfPcqftZRpytksBXDzOUveBq/NBVx0sUp1axwzPQrKinNx5yd5sxPu8j1wIy8AfnVQ+5eFdha6Q==",
+ "node_modules/cookie": {
+ "version": "0.7.2",
+ "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz",
+ "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.6"
+ }
+ },
+ "node_modules/cookie-signature": {
+ "version": "1.2.2",
+ "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz",
+ "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=6.6.0"
+ }
+ },
+ "node_modules/cors": {
+ "version": "2.8.6",
+ "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz",
+ "integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==",
+ "license": "MIT",
+ "dependencies": {
+ "object-assign": "^4",
+ "vary": "^1"
+ },
+ "engines": {
+ "node": ">= 0.10"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/cross-dirname": {
+ "version": "0.1.0",
+ "resolved": "https://registry.npmjs.org/cross-dirname/-/cross-dirname-0.1.0.tgz",
+ "integrity": "sha512-+R08/oI0nl3vfPcqftZRpytksBXDzOUveBq/NBVx0sUp1axwzPQrKinNx5yd5sxPu8j1wIy8AfnVQ+5eFdha6Q==",
"dev": true,
"license": "MIT"
},
@@ -5787,7 +6202,6 @@
"version": "7.0.6",
"resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
"integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
- "dev": true,
"license": "MIT",
"dependencies": {
"path-key": "^3.1.0",
@@ -6048,6 +6462,15 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/depd": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
+ "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.8"
+ }
+ },
"node_modules/deprecation": {
"version": "2.3.1",
"resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz",
@@ -6173,7 +6596,6 @@
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
"integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
- "dev": true,
"license": "MIT",
"dependencies": {
"call-bind-apply-helpers": "^1.0.1",
@@ -6191,6 +6613,12 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/ee-first": {
+ "version": "1.1.1",
+ "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz",
+ "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==",
+ "license": "MIT"
+ },
"node_modules/electron": {
"version": "43.1.1",
"resolved": "https://registry.npmjs.org/electron/-/electron-43.1.1.tgz",
@@ -6287,6 +6715,15 @@
"license": "MIT",
"optional": true
},
+ "node_modules/encodeurl": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz",
+ "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.8"
+ }
+ },
"node_modules/encoding": {
"version": "0.1.13",
"resolved": "https://registry.npmjs.org/encoding/-/encoding-0.1.13.tgz",
@@ -6379,7 +6816,6 @@
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
"integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">= 0.4"
@@ -6389,7 +6825,6 @@
"version": "1.3.0",
"resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
"integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">= 0.4"
@@ -6406,7 +6841,6 @@
"version": "1.1.2",
"resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.2.tgz",
"integrity": "sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==",
- "dev": true,
"license": "MIT",
"dependencies": {
"es-errors": "^1.3.0"
@@ -6473,6 +6907,12 @@
"node": ">=6"
}
},
+ "node_modules/escape-html": {
+ "version": "1.0.3",
+ "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
+ "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==",
+ "license": "MIT"
+ },
"node_modules/escape-string-regexp": {
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
@@ -6701,6 +7141,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",
@@ -6724,6 +7174,15 @@
"url": "https://github.com/eta-dev/eta?sponsor=1"
}
},
+ "node_modules/etag": {
+ "version": "1.8.1",
+ "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz",
+ "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.6"
+ }
+ },
"node_modules/eventemitter3": {
"version": "5.0.4",
"resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-5.0.4.tgz",
@@ -6741,6 +7200,27 @@
"node": ">=0.8.x"
}
},
+ "node_modules/eventsource": {
+ "version": "3.0.7",
+ "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-3.0.7.tgz",
+ "integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==",
+ "license": "MIT",
+ "dependencies": {
+ "eventsource-parser": "^3.0.1"
+ },
+ "engines": {
+ "node": ">=18.0.0"
+ }
+ },
+ "node_modules/eventsource-parser": {
+ "version": "3.1.1",
+ "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.1.1.tgz",
+ "integrity": "sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18.0.0"
+ }
+ },
"node_modules/execa": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/execa/-/execa-1.0.0.tgz",
@@ -6840,6 +7320,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",
@@ -6847,6 +7337,84 @@
"dev": true,
"license": "Apache-2.0"
},
+ "node_modules/express": {
+ "version": "5.2.1",
+ "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
+ "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==",
+ "license": "MIT",
+ "dependencies": {
+ "accepts": "^2.0.0",
+ "body-parser": "^2.2.1",
+ "content-disposition": "^1.0.0",
+ "content-type": "^1.0.5",
+ "cookie": "^0.7.1",
+ "cookie-signature": "^1.2.1",
+ "debug": "^4.4.0",
+ "depd": "^2.0.0",
+ "encodeurl": "^2.0.0",
+ "escape-html": "^1.0.3",
+ "etag": "^1.8.1",
+ "finalhandler": "^2.1.0",
+ "fresh": "^2.0.0",
+ "http-errors": "^2.0.0",
+ "merge-descriptors": "^2.0.0",
+ "mime-types": "^3.0.0",
+ "on-finished": "^2.4.1",
+ "once": "^1.4.0",
+ "parseurl": "^1.3.3",
+ "proxy-addr": "^2.0.7",
+ "qs": "^6.14.0",
+ "range-parser": "^1.2.1",
+ "router": "^2.2.0",
+ "send": "^1.1.0",
+ "serve-static": "^2.2.0",
+ "statuses": "^2.0.1",
+ "type-is": "^2.0.1",
+ "vary": "^1.1.2"
+ },
+ "engines": {
+ "node": ">= 18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/express-rate-limit": {
+ "version": "8.7.0",
+ "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.7.0.tgz",
+ "integrity": "sha512-hOwV7WOxXfjRpAM1DSJWZDXx3GhplwD8IfwuwvogD8i1Qnkgosw/H45s4ZnFAUHDAhPjlY9hLBvJhKmGMyY26g==",
+ "license": "MIT",
+ "dependencies": {
+ "debug": "^4.4.3",
+ "ip-address": "^10.2.0"
+ },
+ "engines": {
+ "node": ">= 16"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/express-rate-limit"
+ },
+ "peerDependencies": {
+ "express": ">= 4.11"
+ }
+ },
+ "node_modules/express/node_modules/mime-types": {
+ "version": "3.0.2",
+ "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz",
+ "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==",
+ "license": "MIT",
+ "dependencies": {
+ "mime-db": "^1.54.0"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
"node_modules/external-editor": {
"version": "3.1.0",
"resolved": "https://registry.npmjs.org/external-editor/-/external-editor-3.1.0.tgz",
@@ -6903,7 +7471,6 @@
"version": "3.1.3",
"resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
"integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
- "dev": true,
"license": "MIT"
},
"node_modules/fast-glob": {
@@ -6954,7 +7521,6 @@
"version": "3.1.3",
"resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.3.tgz",
"integrity": "sha512-i70LwGWUduXqzicKXWshooq+sWL1K3WUU5rKZNG/0i3a1OSoX3HqhH5WbWwTmqWfor4urUakGPiRQcleRZTwOg==",
- "dev": true,
"funding": [
{
"type": "github",
@@ -7041,6 +7607,27 @@
"node": ">=8"
}
},
+ "node_modules/finalhandler": {
+ "version": "2.1.1",
+ "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz",
+ "integrity": "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==",
+ "license": "MIT",
+ "dependencies": {
+ "debug": "^4.4.0",
+ "encodeurl": "^2.0.0",
+ "escape-html": "^1.0.3",
+ "on-finished": "^2.4.1",
+ "parseurl": "^1.3.3",
+ "statuses": "^2.0.1"
+ },
+ "engines": {
+ "node": ">= 18.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
"node_modules/find-up": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz",
@@ -7114,6 +7701,24 @@
"imul": "^1.0.0"
}
},
+ "node_modules/forwarded": {
+ "version": "0.2.0",
+ "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
+ "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.6"
+ }
+ },
+ "node_modules/fresh": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/fresh/-/fresh-2.0.0.tgz",
+ "integrity": "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.8"
+ }
+ },
"node_modules/fs-extra": {
"version": "10.1.0",
"resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-10.1.0.tgz",
@@ -7194,7 +7799,6 @@
"version": "1.1.2",
"resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
"integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
- "dev": true,
"license": "MIT",
"funding": {
"url": "https://github.com/sponsors/ljharb"
@@ -7260,7 +7864,6 @@
"version": "1.3.0",
"resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
"integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
- "dev": true,
"license": "MIT",
"dependencies": {
"call-bind-apply-helpers": "^1.0.2",
@@ -7318,7 +7921,6 @@
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
"integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
- "dev": true,
"license": "MIT",
"dependencies": {
"dunder-proto": "^1.0.1",
@@ -7455,7 +8057,6 @@
"version": "1.2.0",
"resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
"integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">= 0.4"
@@ -7524,7 +8125,6 @@
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
"integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">= 0.4"
@@ -7537,7 +8137,6 @@
"version": "2.0.4",
"resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz",
"integrity": "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==",
- "dev": true,
"license": "MIT",
"dependencies": {
"function-bind": "^1.1.2"
@@ -7546,6 +8145,15 @@
"node": ">= 0.4"
}
},
+ "node_modules/hono": {
+ "version": "4.13.5",
+ "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.5.tgz",
+ "integrity": "sha512-O6+/eCYRkzzzy0rPWwKLiGBR1nFuUPZynnwjxN1MBA62NNqbT0wQEzQyK2gSO5yDIDB336sXQleAhOHrzlYyKw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=16.9.0"
+ }
+ },
"node_modules/hosted-git-info": {
"version": "2.8.9",
"resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-2.8.9.tgz",
@@ -7579,6 +8187,26 @@
"dev": true,
"license": "BSD-2-Clause"
},
+ "node_modules/http-errors": {
+ "version": "2.0.1",
+ "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
+ "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==",
+ "license": "MIT",
+ "dependencies": {
+ "depd": "~2.0.0",
+ "inherits": "~2.0.4",
+ "setprototypeof": "~1.2.0",
+ "statuses": "~2.0.2",
+ "toidentifier": "~1.0.1"
+ },
+ "engines": {
+ "node": ">= 0.8"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
"node_modules/http-proxy-agent": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-5.0.0.tgz",
@@ -7776,7 +8404,6 @@
"version": "2.0.4",
"resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
"integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
- "dev": true,
"license": "ISC"
},
"node_modules/ini": {
@@ -7810,12 +8437,20 @@
"version": "10.2.0",
"resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
"integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">= 12"
}
},
+ "node_modules/ipaddr.js": {
+ "version": "1.9.1",
+ "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz",
+ "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.10"
+ }
+ },
"node_modules/is-arrayish": {
"version": "0.2.1",
"resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz",
@@ -7954,6 +8589,12 @@
"node": ">=0.12.0"
}
},
+ "node_modules/is-promise": {
+ "version": "4.0.0",
+ "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz",
+ "integrity": "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==",
+ "license": "MIT"
+ },
"node_modules/is-property": {
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/is-property/-/is-property-1.0.2.tgz",
@@ -8041,7 +8682,6 @@
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
"integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
- "dev": true,
"license": "ISC"
},
"node_modules/jest-worker": {
@@ -8085,6 +8725,15 @@
"jiti": "lib/jiti-cli.mjs"
}
},
+ "node_modules/jose": {
+ "version": "6.2.10",
+ "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.10.tgz",
+ "integrity": "sha512-iiW7J9qRFlGxvCOIBDBDxFePQSn7ZMAnrYGhrrOo6siO/MIqwfyilLR27pkfDgUk+raLuzADS8A3S/KLBisc0g==",
+ "license": "MIT",
+ "funding": {
+ "url": "https://github.com/sponsors/panva"
+ }
+ },
"node_modules/js-tokens": {
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -8140,6 +8789,12 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/json-schema-typed": {
+ "version": "8.0.2",
+ "resolved": "https://registry.npmjs.org/json-schema-typed/-/json-schema-typed-8.0.2.tgz",
+ "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
+ "license": "BSD-2-Clause"
+ },
"node_modules/json-stable-stringify": {
"version": "1.3.0",
"resolved": "https://registry.npmjs.org/json-stable-stringify/-/json-stable-stringify-1.3.0.tgz",
@@ -8340,6 +8995,7 @@
"os": [
"android"
],
+ "peer": true,
"engines": {
"node": ">= 12.0.0"
},
@@ -8361,6 +9017,7 @@
"os": [
"darwin"
],
+ "peer": true,
"engines": {
"node": ">= 12.0.0"
},
@@ -8382,6 +9039,7 @@
"os": [
"darwin"
],
+ "peer": true,
"engines": {
"node": ">= 12.0.0"
},
@@ -8403,6 +9061,7 @@
"os": [
"freebsd"
],
+ "peer": true,
"engines": {
"node": ">= 12.0.0"
},
@@ -8424,6 +9083,7 @@
"os": [
"linux"
],
+ "peer": true,
"engines": {
"node": ">= 12.0.0"
},
@@ -8445,6 +9105,7 @@
"os": [
"linux"
],
+ "peer": true,
"engines": {
"node": ">= 12.0.0"
},
@@ -8466,6 +9127,7 @@
"os": [
"linux"
],
+ "peer": true,
"engines": {
"node": ">= 12.0.0"
},
@@ -8487,6 +9149,7 @@
"os": [
"linux"
],
+ "peer": true,
"engines": {
"node": ">= 12.0.0"
},
@@ -8508,6 +9171,7 @@
"os": [
"linux"
],
+ "peer": true,
"engines": {
"node": ">= 12.0.0"
},
@@ -8529,6 +9193,7 @@
"os": [
"win32"
],
+ "peer": true,
"engines": {
"node": ">= 12.0.0"
},
@@ -8550,6 +9215,7 @@
"os": [
"win32"
],
+ "peer": true,
"engines": {
"node": ">= 12.0.0"
},
@@ -8927,7 +9593,6 @@
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
"integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">= 0.4"
@@ -8940,6 +9605,19 @@
"dev": true,
"license": "CC0-1.0"
},
+ "node_modules/media-typer": {
+ "version": "1.1.1",
+ "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.1.tgz",
+ "integrity": "sha512-yz3xRaG20c6/BOzvYoDaGtPmGscs7YivItZEEqe6GbwNfHuxu9YNmvnEkMzKldAGY4/80pRcQRZSEnhquk9XuQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.8"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
"node_modules/mediabunny": {
"version": "1.50.6",
"resolved": "https://registry.npmjs.org/mediabunny/-/mediabunny-1.50.6.tgz",
@@ -8989,6 +9667,18 @@
"url": "https://github.com/sponsors/mesqueeb"
}
},
+ "node_modules/merge-descriptors": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-2.0.0.tgz",
+ "integrity": "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
"node_modules/merge-stream": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",
@@ -9024,7 +9714,6 @@
"version": "1.54.0",
"resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz",
"integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">= 0.6"
@@ -9495,6 +10184,27 @@
"url": "https://github.com/fb55/nth-check?sponsor=1"
}
},
+ "node_modules/object-assign": {
+ "version": "4.1.1",
+ "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
+ "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/object-inspect": {
+ "version": "1.13.4",
+ "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
+ "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
"node_modules/object-keys": {
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/object-keys/-/object-keys-1.1.1.tgz",
@@ -9505,11 +10215,36 @@
"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/on-finished": {
+ "version": "2.4.1",
+ "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
+ "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==",
+ "license": "MIT",
+ "dependencies": {
+ "ee-first": "1.1.1"
+ },
+ "engines": {
+ "node": ">= 0.8"
+ }
+ },
"node_modules/once": {
"version": "1.4.0",
"resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
"integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
- "dev": true,
"license": "ISC",
"dependencies": {
"wrappy": "1"
@@ -9801,6 +10536,15 @@
"url": "https://github.com/inikulin/parse5?sponsor=1"
}
},
+ "node_modules/parseurl": {
+ "version": "1.3.3",
+ "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
+ "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.8"
+ }
+ },
"node_modules/patch-package": {
"version": "8.0.1",
"resolved": "https://registry.npmjs.org/patch-package/-/patch-package-8.0.1.tgz",
@@ -9871,7 +10615,6 @@
"version": "3.1.1",
"resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
"integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">=8"
@@ -9884,6 +10627,16 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/path-to-regexp": {
+ "version": "8.4.2",
+ "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz",
+ "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==",
+ "license": "MIT",
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
"node_modules/path-type": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/path-type/-/path-type-2.0.0.tgz",
@@ -9955,6 +10708,15 @@
"node": ">=0.10.0"
}
},
+ "node_modules/pkce-challenge": {
+ "version": "5.0.1",
+ "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz",
+ "integrity": "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=16.20.0"
+ }
+ },
"node_modules/plist": {
"version": "3.1.1",
"resolved": "https://registry.npmjs.org/plist/-/plist-3.1.1.tgz",
@@ -10092,6 +10854,19 @@
"node": ">=10"
}
},
+ "node_modules/proxy-addr": {
+ "version": "2.0.7",
+ "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
+ "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==",
+ "license": "MIT",
+ "dependencies": {
+ "forwarded": "0.2.0",
+ "ipaddr.js": "1.9.1"
+ },
+ "engines": {
+ "node": ">= 0.10"
+ }
+ },
"node_modules/pump": {
"version": "3.0.4",
"resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
@@ -10113,6 +10888,22 @@
"node": ">=6"
}
},
+ "node_modules/qs": {
+ "version": "6.16.0",
+ "resolved": "https://registry.npmjs.org/qs/-/qs-6.16.0.tgz",
+ "integrity": "sha512-h6fhOIaRrID2CbEY2fqs+7t+UXZo+MLAnU5gRIq85uFtdiUPCdsApMlHhXogKVM4HM2DVbIjGNTTYH2OcmP1vA==",
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "es-define-property": "^1.0.1",
+ "side-channel": "^1.1.1"
+ },
+ "engines": {
+ "node": ">=0.6"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
"node_modules/queue-microtask": {
"version": "1.2.3",
"resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
@@ -10159,15 +10950,59 @@
"murmur-32": "^0.1.0 || ^0.2.0"
}
},
- "node_modules/read-binary-file-arch": {
- "version": "1.0.6",
- "resolved": "https://registry.npmjs.org/read-binary-file-arch/-/read-binary-file-arch-1.0.6.tgz",
- "integrity": "sha512-BNg9EN3DD3GsDXX7Aa8O4p92sryjkmzYYgmgTAc6CA4uGLEDzFfxOxugu21akOxpcXHiEgsYkC6nPsQvLLLmEg==",
- "dev": true,
+ "node_modules/range-parser": {
+ "version": "1.3.0",
+ "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.3.0.tgz",
+ "integrity": "sha512-hek2mFQpPuI4E1BBKrSto+BU3e3x4xuarsbiwr3+lf7p44juvFMV0XFWQAP3xUyqXA4RrXLIoaSUGbSt056ZMw==",
"license": "MIT",
- "dependencies": {
- "debug": "^4.3.4"
- },
+ "engines": {
+ "node": ">= 0.6"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/raw-body": {
+ "version": "3.0.2",
+ "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz",
+ "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==",
+ "license": "MIT",
+ "dependencies": {
+ "bytes": "~3.1.2",
+ "http-errors": "~2.0.1",
+ "iconv-lite": "~0.7.0",
+ "unpipe": "~1.0.0"
+ },
+ "engines": {
+ "node": ">= 0.10"
+ }
+ },
+ "node_modules/raw-body/node_modules/iconv-lite": {
+ "version": "0.7.3",
+ "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.3.tgz",
+ "integrity": "sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ==",
+ "license": "MIT",
+ "dependencies": {
+ "safer-buffer": ">= 2.1.2 < 3.0.0"
+ },
+ "engines": {
+ "node": ">=0.10.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/read-binary-file-arch": {
+ "version": "1.0.6",
+ "resolved": "https://registry.npmjs.org/read-binary-file-arch/-/read-binary-file-arch-1.0.6.tgz",
+ "integrity": "sha512-BNg9EN3DD3GsDXX7Aa8O4p92sryjkmzYYgmgTAc6CA4uGLEDzFfxOxugu21akOxpcXHiEgsYkC6nPsQvLLLmEg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "debug": "^4.3.4"
+ },
"bin": {
"read-binary-file-arch": "cli.js"
}
@@ -10317,7 +11152,6 @@
"version": "2.0.2",
"resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
"integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">=0.10.0"
@@ -10526,6 +11360,22 @@
"fsevents": "~2.3.2"
}
},
+ "node_modules/router": {
+ "version": "2.2.0",
+ "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz",
+ "integrity": "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==",
+ "license": "MIT",
+ "dependencies": {
+ "debug": "^4.4.0",
+ "depd": "^2.0.0",
+ "is-promise": "^4.0.0",
+ "parseurl": "^1.3.3",
+ "path-to-regexp": "^8.0.0"
+ },
+ "engines": {
+ "node": ">= 18"
+ }
+ },
"node_modules/run-parallel": {
"version": "1.2.0",
"resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz",
@@ -10575,7 +11425,6 @@
"version": "2.1.2",
"resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
"integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
- "dev": true,
"license": "MIT"
},
"node_modules/sax": {
@@ -10666,6 +11515,48 @@
"license": "MIT",
"optional": true
},
+ "node_modules/send": {
+ "version": "1.2.1",
+ "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz",
+ "integrity": "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==",
+ "license": "MIT",
+ "dependencies": {
+ "debug": "^4.4.3",
+ "encodeurl": "^2.0.0",
+ "escape-html": "^1.0.3",
+ "etag": "^1.8.1",
+ "fresh": "^2.0.0",
+ "http-errors": "^2.0.1",
+ "mime-types": "^3.0.2",
+ "ms": "^2.1.3",
+ "on-finished": "^2.4.1",
+ "range-parser": "^1.2.1",
+ "statuses": "^2.0.2"
+ },
+ "engines": {
+ "node": ">= 18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/send/node_modules/mime-types": {
+ "version": "3.0.2",
+ "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz",
+ "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==",
+ "license": "MIT",
+ "dependencies": {
+ "mime-db": "^1.54.0"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
"node_modules/serialize-error": {
"version": "7.0.1",
"resolved": "https://registry.npmjs.org/serialize-error/-/serialize-error-7.0.1.tgz",
@@ -10718,6 +11609,25 @@
"seroval": "^1.0"
}
},
+ "node_modules/serve-static": {
+ "version": "2.2.1",
+ "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-2.2.1.tgz",
+ "integrity": "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==",
+ "license": "MIT",
+ "dependencies": {
+ "encodeurl": "^2.0.0",
+ "escape-html": "^1.0.3",
+ "parseurl": "^1.3.3",
+ "send": "^1.2.0"
+ },
+ "engines": {
+ "node": ">= 18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
"node_modules/set-function-length": {
"version": "1.2.2",
"resolved": "https://registry.npmjs.org/set-function-length/-/set-function-length-1.2.2.tgz",
@@ -10736,11 +11646,16 @@
"node": ">= 0.4"
}
},
+ "node_modules/setprototypeof": {
+ "version": "1.2.0",
+ "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz",
+ "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==",
+ "license": "ISC"
+ },
"node_modules/shebang-command": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
"integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
- "dev": true,
"license": "MIT",
"dependencies": {
"shebang-regex": "^3.0.0"
@@ -10753,12 +11668,90 @@
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
"integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">=8"
}
},
+ "node_modules/side-channel": {
+ "version": "1.1.1",
+ "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.1.tgz",
+ "integrity": "sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==",
+ "license": "MIT",
+ "dependencies": {
+ "es-errors": "^1.3.0",
+ "object-inspect": "^1.13.4",
+ "side-channel-list": "^1.0.1",
+ "side-channel-map": "^1.0.1",
+ "side-channel-weakmap": "^1.0.2"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/side-channel-list": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz",
+ "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==",
+ "license": "MIT",
+ "dependencies": {
+ "es-errors": "^1.3.0",
+ "object-inspect": "^1.13.4"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/side-channel-map": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz",
+ "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==",
+ "license": "MIT",
+ "dependencies": {
+ "call-bound": "^1.0.2",
+ "es-errors": "^1.3.0",
+ "get-intrinsic": "^1.2.5",
+ "object-inspect": "^1.13.3"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "node_modules/side-channel-weakmap": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz",
+ "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==",
+ "license": "MIT",
+ "dependencies": {
+ "call-bound": "^1.0.2",
+ "es-errors": "^1.3.0",
+ "get-intrinsic": "^1.2.5",
+ "object-inspect": "^1.13.3",
+ "side-channel-map": "^1.0.1"
+ },
+ "engines": {
+ "node": ">= 0.4"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/ljharb"
+ }
+ },
+ "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 +11996,35 @@
"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/statuses": {
+ "version": "2.0.2",
+ "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
+ "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.8"
+ }
+ },
+ "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 +12333,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 +12362,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 +12417,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",
@@ -11432,6 +12475,15 @@
"node": ">=8.0"
}
},
+ "node_modules/toidentifier": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
+ "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.6"
+ }
+ },
"node_modules/tr46": {
"version": "0.0.3",
"resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
@@ -11533,6 +12585,53 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
+ "node_modules/type-is": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.1.0.tgz",
+ "integrity": "sha512-faYHw0anBbc/kWF3zFTEnxSFOAGUX9GFbOBthvDdLsIlEoWOFOtS0zgCiQYwIskL9iGXZL3kAXD8OoZ4GmMATA==",
+ "license": "MIT",
+ "dependencies": {
+ "content-type": "^2.0.0",
+ "media-typer": "^1.1.0",
+ "mime-types": "^3.0.0"
+ },
+ "engines": {
+ "node": ">= 18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/type-is/node_modules/content-type": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz",
+ "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/type-is/node_modules/mime-types": {
+ "version": "3.0.2",
+ "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz",
+ "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==",
+ "license": "MIT",
+ "dependencies": {
+ "mime-db": "^1.54.0"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
"node_modules/typed-binary": {
"version": "4.3.3",
"resolved": "https://registry.npmjs.org/typed-binary/-/typed-binary-4.3.3.tgz",
@@ -11641,6 +12740,15 @@
"node": ">= 0.4.0"
}
},
+ "node_modules/unpipe": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
+ "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.8"
+ }
+ },
"node_modules/unplugin": {
"version": "3.3.0",
"resolved": "https://registry.npmjs.org/unplugin/-/unplugin-3.3.0.tgz",
@@ -11827,6 +12935,15 @@
"spdx-expression-parse": "^3.0.0"
}
},
+ "node_modules/vary": {
+ "version": "1.1.2",
+ "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
+ "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.8"
+ }
+ },
"node_modules/vite": {
"version": "7.3.6",
"resolved": "https://registry.npmjs.org/vite/-/vite-7.3.6.tgz",
@@ -11992,6 +13109,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",
@@ -12138,7 +13358,6 @@
"version": "2.0.2",
"resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
"integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
- "dev": true,
"license": "ISC",
"dependencies": {
"isexe": "^2.0.0"
@@ -12150,6 +13369,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",
@@ -12211,30 +13447,8 @@
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
"integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
- "dev": true,
"license": "ISC"
},
- "node_modules/ws": {
- "version": "8.21.0",
- "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
- "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
- "license": "MIT",
- "engines": {
- "node": ">=10.0.0"
- },
- "peerDependencies": {
- "bufferutil": "^4.0.1",
- "utf-8-validate": ">=5.0.2"
- },
- "peerDependenciesMeta": {
- "bufferutil": {
- "optional": true
- },
- "utf-8-validate": {
- "optional": true
- }
- }
- },
"node_modules/xmlbuilder": {
"version": "15.1.1",
"resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-15.1.1.tgz",
@@ -12395,6 +13609,15 @@
"url": "https://github.com/sponsors/colinhacks"
}
},
+ "node_modules/zod-to-json-schema": {
+ "version": "3.25.2",
+ "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz",
+ "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==",
+ "license": "ISC",
+ "peerDependencies": {
+ "zod": "^3.25.28 || ^4"
+ }
+ },
"packages/assets": {
"name": "@diffusionstudio/assets",
"version": "0.1.0",
@@ -12407,6 +13630,21 @@
"typescript": "~5.9.3"
}
},
+ "packages/dapi": {
+ "name": "@diffusionstudio/dapi",
+ "version": "0.1.0",
+ "license": "MPL-2.0",
+ "dependencies": {
+ "@diffusionstudio/jsx": "*",
+ "@modelcontextprotocol/sdk": "^1.30.0",
+ "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/package.json b/package.json
index 59bfec16..695bd2f6 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +19,7 @@
"release": "node scripts/release.mjs",
"postinstall": "patch-package",
"lint": "npm run lint --workspaces --if-present",
- "check": "npm run check --workspaces --if-present && tsc -p examples --noEmit"
+ "check": "npm run check --workspaces --if-present"
},
"devDependencies": {
"patch-package": "^8.0.1"
diff --git a/packages/dapi/README.md b/packages/dapi/README.md
new file mode 100644
index 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.json
new file mode 100644
index 00000000..b25e0166
--- /dev/null
+++ b/packages/dapi/package.json
@@ -0,0 +1,31 @@
+{
+ "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": "*",
+ "@modelcontextprotocol/sdk": "^1.30.0",
+ "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.ts
new file mode 100644
index 00000000..3f90c21e
--- /dev/null
+++ b/packages/dapi/src/catalog.test.ts
@@ -0,0 +1,43 @@
+/* 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 input and output to JSON Schema, as MCP tools/list does", () => {
+ 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();
+ expect(tool.output, `${tool.name} output must be an object for structured content`).toBeInstanceOf(z.ZodObject);
+ }
+ });
+
+ it("looks tools up by name", () => {
+ expect(toolByName("capture").environment).toBe("renderer");
+ expect(toolByName("fonts").environment).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.ts
new file mode 100644
index 00000000..39c70d60
--- /dev/null
+++ b/packages/dapi/src/catalog.ts
@@ -0,0 +1,83 @@
+/* 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 { GenericTool } 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"]>;
+/** What a caller receives: the tool's structured content. */
+export type ToolOutput<N extends ToolName> = z.output<ToolByName<N>["output"]>;
+/** What a handler returns; the output, unless the tool declares a `result`. */
+export type ToolResult<N extends ToolName> = ToolByName<N> extends { result?: infer R }
+ ? R extends z.ZodType
+ ? z.output<R>
+ : ToolOutput<N>
+ : ToolOutput<N>;
+
+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 with each tool's specifics erased, for code that iterates it. */
+export const tools: readonly GenericTool[] = catalog;
diff --git a/packages/dapi/src/errors.ts b/packages/dapi/src/errors.ts
new file mode 100644
index 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.ts
new file mode 100644
index 00000000..83b45d5c
--- /dev/null
+++ b/packages/dapi/src/index.ts
@@ -0,0 +1,84 @@
+/* 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, GenericTool, Environment } from "./tool";
+
+export { catalog, tools, toolByName, isToolName } from "./catalog";
+export type { AnyTool, ToolName, ToolByName, ToolInput, ToolArgs, ToolOutput, 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, Bytes } from "./schemas";
+
+export { DAPI_WIRE } from "./ipc";
+export type { DapiCall, DapiCancel, DapiReply } from "./ipc";
+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 { ImageRef as ImageRefSchema, 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, ToolOutput, 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 ImageRef = z.output<typeof ImageRefSchema>;
+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 = ToolOutput<"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 ScreenshotOutput = ToolOutput<"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/ipc.ts b/packages/dapi/src/ipc.ts
new file mode 100644
index 00000000..db0eae92
--- /dev/null
+++ b/packages/dapi/src/ipc.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/. */
+
+// The channel between the app's main process, which hosts the MCP server,
+// and the renderer, which answers renderer tools. One call, one reply, and
+// a cancel when the caller gives up. Arguments arrive validated: main parsed
+// them against the catalog before forwarding.
+
+import type { DapiErrorCode } from "./errors";
+
+export const DAPI_WIRE = {
+ /** main → renderer */
+ CALL: "dapi:call",
+ /** main → renderer */
+ CANCEL: "dapi:cancel",
+ /** renderer → main */
+ REPLY: "dapi:reply",
+} as const;
+
+export type DapiCall = { id: string; tool: string; args: unknown };
+
+export type DapiCancel = { id: string };
+
+export type DapiReply =
+ | { id: string; ok: true; data: unknown }
+ | { id: string; ok: false; error: { code?: DapiErrorCode; message: string } };
diff --git a/packages/dapi/src/schemas.ts b/packages/dapi/src/schemas.ts
new file mode 100644
index 00000000..0e52cd3d
--- /dev/null
+++ b/packages/dapi/src/schemas.ts
@@ -0,0 +1,114 @@
+/* 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, TIME_FORMS } 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;
+
+/**
+ * Raw bytes as a handler produces them. How they travel is the transport's
+ * business: base64 on a JSON wire, structured clone over IPC, a file on disk.
+ */
+export const Bytes = z.custom<Uint8Array>((value) => value instanceof Uint8Array, "expected bytes (a Uint8Array)");
+
+/**
+ * One rendered image as a handler returns it: 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(),
+ png: Bytes,
+});
+
+/** The same image once the server has written it to disk. */
+export const ImageRef = z.object({
+ timecode: z.string(),
+ path: z.string().describe("absolute path of the PNG"),
+});
+
+export const outputDirField = z
+ .string()
+ .optional()
+ .describe("absolute directory to write the PNGs into (default: a fresh directory under the system temp dir)");
+
+/**
+ * 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 = {
+ separate: z
+ .boolean()
+ .optional()
+ .describe("write one image per position instead of merging them into contact sheets of up to 12 cells, each labelled with its timecode"),
+ 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: { separate?: boolean | undefined; perSheet?: number | undefined },
+ ctx: z.RefinementCtx,
+): void {
+ if (value.perSheet !== undefined && value.separate) {
+ ctx.addIssue({
+ code: "custom",
+ path: ["perSheet"],
+ message: "perSheet lays out contact sheets; it cannot be combined with separate: true",
+ });
+ }
+}
+
+/** A `[start, end)` window in seconds; both optional, and start must precede end. */
+export const windowFields = {
+ start: NonNegativeTime.optional().describe(`start of the window — ${TIME_FORMS} (default: 0)`),
+ end: NonNegativeTime.optional().describe(`end of the window — ${TIME_FORMS} (default: asset duration)`),
+};
+
+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/packages/dapi/src/socket.test.ts b/packages/dapi/src/socket.test.ts
new file mode 100644
index 00000000..cdba741e
--- /dev/null
+++ b/packages/dapi/src/socket.test.ts
@@ -0,0 +1,111 @@
+/* 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 { mkdtempSync, rmSync } from "node:fs";
+import { connect, createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { LoggingMessageNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+import { tools } from "./catalog";
+import { SocketTransport } from "./socket";
+
+import type { Server, Socket } from "node:net";
+
+// A server over the real catalog with stub handlers, the way the app hosts
+// it: one McpServer per accepted connection, MCP framed over the socket.
+const dir = mkdtempSync(join(tmpdir(), "dapi-test-"));
+const path = join(dir, "app.sock");
+let server: Server;
+
+beforeAll(async () => {
+ server = createServer((socket) => {
+ const session = new McpServer({ name: "test", version: "0.0.0" }, { capabilities: { logging: {} } });
+ for (const tool of tools) {
+ session.registerTool(
+ tool.name,
+ { description: tool.description, inputSchema: tool.input, outputSchema: tool.output },
+ async (_args, extra) => {
+ if (tool.name === "context") {
+ // A notification right before the response, in the same write burst:
+ // the transport must not let the response overtake its handling.
+ await extra.sendNotification({ method: "notifications/message", params: { level: "info", data: "about to reply" } });
+ const output = { rootDir: "/p", projectDir: null, currentTime: null, fontFamilies: [], generations: [] };
+ return { content: [{ type: "text", text: JSON.stringify(output) }], structuredContent: output };
+ }
+ return { isError: true, content: [{ type: "text", text: `stub has no ${tool.name}` }] };
+ },
+ );
+ }
+ void session.connect(new SocketTransport(socket));
+ });
+ await new Promise<void>((resolve) => server.listen(path, resolve));
+});
+
+afterAll(async () => {
+ await new Promise<void>((resolve) => server.close(() => resolve()));
+ rmSync(dir, { recursive: true, force: true });
+});
+
+async function open(): Promise<{ client: Client; socket: Socket }> {
+ const socket = await new Promise<Socket>((resolve, reject) => {
+ const s = connect(path);
+ s.once("connect", () => resolve(s));
+ s.once("error", reject);
+ });
+ const client = new Client({ name: "test-client", version: "0.0.0" });
+ await client.connect(new SocketTransport(socket));
+ return { client, socket };
+}
+
+describe("MCP over the socket", () => {
+ it("lists the whole catalog with JSON Schema inputs", async () => {
+ const { client } = await open();
+ try {
+ const { tools: listed } = await client.listTools();
+ expect(listed.map((t) => t.name).sort()).toEqual(tools.map((t) => t.name).sort());
+ const grab = listed.find((t) => t.name === "media_grab")!;
+ expect(grab.inputSchema.type).toBe("object");
+ expect(Object.keys(grab.inputSchema.properties ?? {})).toContain("times");
+ expect(grab.outputSchema?.type).toBe("object");
+ } finally {
+ await client.close();
+ }
+ });
+
+ it("returns structured content and rejects bad arguments with the field named", async () => {
+ const { client } = await open();
+ try {
+ const messages: string[] = [];
+ client.setNotificationHandler(LoggingMessageNotificationSchema, (n) => {
+ messages.push(String(n.params.data));
+ });
+ const result = await client.callTool({ name: "context", arguments: {} });
+ expect(result.structuredContent).toEqual({ rootDir: "/p", projectDir: null, currentTime: null, fontFamilies: [], generations: [] });
+ expect(messages).toEqual(["about to reply"]);
+
+ // Bad arguments come back as a result the agent can read, not a protocol error.
+ const bad = await client.callTool({ name: "media_grab", arguments: { path: "/c.mp4", count: 0 } });
+ expect(bad.isError).toBe(true);
+ expect(JSON.stringify(bad.content)).toMatch(/count/);
+ } finally {
+ await client.close();
+ }
+ });
+
+ it("serves several sessions at once", async () => {
+ const a = await open();
+ const b = await open();
+ try {
+ const [ra, rb] = await Promise.all([a.client.ping(), b.client.ping()]);
+ expect(ra).toBeDefined();
+ expect(rb).toBeDefined();
+ } finally {
+ await a.client.close();
+ await b.client.close();
+ }
+ });
+});
diff --git a/packages/dapi/src/socket.ts b/packages/dapi/src/socket.ts
new file mode 100644
index 00000000..62c1b9db
--- /dev/null
+++ b/packages/dapi/src/socket.ts
@@ -0,0 +1,106 @@
+/* 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/. */
+
+// The Node side of the protocol: where the app's socket lives and how MCP
+// travels over it. Its own entry point (`@diffusionstudio/dapi/socket`) so
+// the renderer can import the catalog without node:os or the MCP SDK.
+
+import { platform, tmpdir } from "node:os";
+import { join } from "node:path";
+import { ReadBuffer, serializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
+
+import type { Socket } from "node:net";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+
+// Where the app serves MCP over HTTP, for agents: a fixed loopback port, so
+// the URL is the same on every machine and can be written into a config once.
+// 3274 spells "dapi" on a phone keypad. Loopback only; no token — the server
+// checks the Host header, which is what keeps browser pages out, and anything
+// else running as the user can already reach the socket below.
+export const MCP_HOST = "127.0.0.1";
+export const MCP_PORT = 3274;
+export const MCP_PATH = "/mcp";
+export const MCP_URL = `http://${MCP_HOST}:${MCP_PORT}${MCP_PATH}`;
+
+// One socket / named pipe per host, for the CLI. On macOS tmpdir is per-user;
+// on Linux /tmp is global but the socket file's owner-only mode 0600 keeps it
+// isolated.
+export const SOCKET_PATH =
+ platform() === "win32"
+ ? "\\\\.\\pipe\\diffusion-studio"
+ : join(tmpdir(), "diffusion-studio.sock");
+
+/**
+ * MCP over a local socket, framed exactly like MCP over stdio: one JSON-RPC
+ * message per line. The same class serves the app (one per accepted
+ * connection) and the CLI (one per command); a stdio proxy needs neither,
+ * since the bytes on the socket are already what a stdio client expects.
+ */
+export class SocketTransport implements Transport {
+ onclose?: () => void;
+ onerror?: (error: Error) => void;
+ onmessage?: (message: JSONRPCMessage) => void;
+
+ private readonly socket: Socket;
+ private readonly buffer = new ReadBuffer();
+ private started = false;
+ private draining = false;
+
+ constructor(socket: Socket) {
+ this.socket = socket;
+ }
+
+ async start(): Promise<void> {
+ if (this.started) throw new Error("SocketTransport already started");
+ this.started = true;
+ this.socket.on("data", (chunk: Buffer) => {
+ this.buffer.append(chunk);
+ void this.drain();
+ });
+ this.socket.on("error", (error) => this.onerror?.(error));
+ this.socket.on("close", () => this.onclose?.());
+ }
+
+ send(message: JSONRPCMessage): Promise<void> {
+ return new Promise((resolve, reject) => {
+ if (this.socket.destroyed) {
+ reject(new Error("Socket is closed"));
+ return;
+ }
+ this.socket.write(serializeMessage(message), (error) => (error ? reject(error) : resolve()));
+ });
+ }
+
+ async close(): Promise<void> {
+ this.socket.end();
+ this.socket.destroy();
+ }
+
+ // Messages are handed over one per turn of the event loop. The SDK runs
+ // notification handlers on a microtask, so a notification and the response
+ // that follows it in the same chunk must not be dispatched back to back:
+ // the response would settle the request before the notification's handler
+ // ran. A drain in progress picks up chunks appended meanwhile.
+ private async drain(): Promise<void> {
+ if (this.draining) return;
+ this.draining = true;
+ try {
+ while (true) {
+ let message: JSONRPCMessage | null;
+ try {
+ message = this.buffer.readMessage();
+ } catch (error) {
+ this.onerror?.(error as Error);
+ return;
+ }
+ if (!message) return;
+ this.onmessage?.(message);
+ await new Promise<void>((resolve) => setImmediate(resolve));
+ }
+ } finally {
+ this.draining = false;
+ }
+ }
+}
diff --git a/packages/dapi/src/time.test.ts b/packages/dapi/src/time.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 00000000..02466d9c
--- /dev/null
+++ b/packages/dapi/src/tool.ts
@@ -0,0 +1,50 @@
+/* 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 Environment = "renderer" | "main";
+
+export interface Tool<
+ Name extends string = string,
+ Input extends z.ZodObject = z.ZodObject,
+ Output extends z.ZodObject = z.ZodObject,
+ Result extends z.ZodType = Output,
+> {
+ /** 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;
+ /** What the caller receives: a JSON object, the tool's structured content. */
+ readonly output: Output;
+ /**
+ * What the handler returns, when that is not the output: image tools hand
+ * back bytes, and the server presents them as files and inline images. Same
+ * as `output` when omitted.
+ */
+ readonly result?: Result;
+ readonly environment: Environment;
+}
+
+/** A tool with its specifics erased, for code that iterates the catalog. */
+export type GenericTool = Tool<string, z.ZodObject, z.ZodObject, z.ZodType>;
+
+/** 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.ZodObject,
+ Result extends z.ZodType = Output,
+>(tool: Tool<Name, Input, Output, Result>): Tool<Name, Input, Output, Result> {
+ return tool;
+}
diff --git a/packages/dapi/src/tools/capture.ts b/packages/dapi/src/tools/capture.ts
new file mode 100644
index 00000000..7b997a9e
--- /dev/null
+++ b/packages/dapi/src/tools/capture.ts
@@ -0,0 +1,31 @@
+/* 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, ImageRef, outputDirField, SceneId, sheetFields, TimecodedImage } from "../schemas";
+import { NonNegativeTime } from "../time";
+
+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 (separate: true 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,
+ times: z
+ .array(NonNegativeTime)
+ .optional()
+ .describe(
+ "positions to capture, relative to the export's first frame, the workarea's start (0 = the export's frame 0) — seconds (\"1.5\"), frames (\"45f\"), or \"MM:SS\" (default: [0])",
+ ),
+ ...sheetFields,
+ output: outputDirField,
+ })
+ .superRefine(checkSheetOptions),
+ output: z.object({ images: z.array(ImageRef) }),
+ result: z.array(TimecodedImage),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/check.ts b/packages/dapi/src/tools/check.ts
new file mode 100644
index 00000000..18996035
--- /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),
+ }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/context.ts b/packages/dapi/src/tools/context.ts
new file mode 100644
index 00000000..4f19f65e
--- /dev/null
+++ b/packages/dapi/src/tools/context.ts
@@ -0,0 +1,48 @@
+/* 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.object({
+ rootDir: z.string().nullable().describe("folder projects live under; null until one has been chosen"),
+ projectDir: z.string().nullable().describe("absolute path of the open project; null when none is open"),
+ currentTime: z
+ .number()
+ .nullable()
+ .describe("playhead in seconds, the unit the source places clips in; null when no scene is active or no project is open"),
+ 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),
+ }),
+ environment: "renderer",
+});
+
+export type GenerationRow = z.output<typeof GenerationRow>;
diff --git a/packages/dapi/src/tools/export.ts b/packages/dapi/src/tools/export.ts
new file mode 100644
index 00000000..2e93ab7c
--- /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",
+ ),
+ }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/fetch.ts b/packages/dapi/src/tools/fetch.ts
new file mode 100644
index 00000000..d9a98f6b
--- /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()) }),
+ environment: "main",
+});
diff --git a/packages/dapi/src/tools/fonts.ts b/packages/dapi/src/tools/fonts.ts
new file mode 100644
index 00000000..0ba24884
--- /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, normal or italic"),
+ limit: z.int().min(1).optional().describe("return at most this many families"),
+ }),
+ output: z.object({ families: z.array(FontFamily) }),
+ environment: "main",
+});
diff --git a/packages/dapi/src/tools/logs.ts b/packages/dapi/src/tools/logs.ts
new file mode 100644
index 00000000..25c509d5
--- /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: debug, info, warning, or error"),
+ }),
+ output: z.object({ entries: z.array(LogEntry) }),
+ environment: "main",
+});
diff --git a/packages/dapi/src/tools/media-filmstrip.ts b/packages/dapi/src/tools/media-filmstrip.ts
new file mode 100644
index 00000000..c678df35
--- /dev/null
+++ b/packages/dapi/src/tools/media-filmstrip.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";
+import { AssetPath, Bytes, checkWindow, windowFields } from "../schemas";
+
+/** The window and scale that filmstrip and waveform share. */
+export const previewFields = {
+ ...windowFields,
+ output: z.string().optional().describe("absolute path to write the PNG to (default: a fresh file under the system temp dir)"),
+ 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({ path: z.string().describe("absolute path of the PNG") }),
+ result: z.looseObject({ png: Bytes }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/media-grab.ts b/packages/dapi/src/tools/media-grab.ts
new file mode 100644
index 00000000..5a4ab3d0
--- /dev/null
+++ b/packages/dapi/src/tools/media-grab.ts
@@ -0,0 +1,77 @@
+/* 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, ImageRef, outputDirField, 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 (separate: true 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",
+ ),
+ start: windowFields.start.describe("with count or auto, start of the window to sample (default: 0)"),
+ end: windowFields.end.describe("with count or auto, end of the window to sample (default: asset duration)"),
+ 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 separate: true",
+ ),
+ ...sheetFields,
+ uncapped: z
+ .boolean()
+ .optional()
+ .describe(`lift the ${FRAME_CAP}-frame safety cap (grabbing many frames is slow and token-heavy)`),
+ output: outputDirField,
+ })
+ .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.object({ images: z.array(ImageRef) }),
+ result: z.array(TimecodedImage),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/media-listen.ts b/packages/dapi/src/tools/media-listen.ts
new file mode 100644
index 00000000..1c56b097
--- /dev/null
+++ b/packages/dapi/src/tools/media-listen.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 { 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; of a video 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)"),
+ })
+ .superRefine(checkWindow),
+ output: z.object({
+ result: z.string().optional(),
+ start: z.number().optional(),
+ end: z.number().optional(),
+ }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/media-probe.ts b/packages/dapi/src/tools/media-probe.ts
new file mode 100644
index 00000000..c430f2ac
--- /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),
+ }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/media-transcribe.ts b/packages/dapi/src/tools/media-transcribe.ts
new file mode 100644
index 00000000..7c1ece94
--- /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) }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/media-waveform.ts b/packages/dapi/src/tools/media-waveform.ts
new file mode 100644
index 00000000..72faf05f
--- /dev/null
+++ b/packages/dapi/src/tools/media-waveform.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";
+import { AssetPath, Bytes, checkWindow } from "../schemas";
+import { previewFields } from "./media-filmstrip";
+
+const Silences = z.array(z.object({ start: z.number(), end: z.number() })).describe("seconds");
+
+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({
+ path: z.string().describe("absolute path of the PNG"),
+ silences: Silences,
+ }),
+ result: z.looseObject({ png: Bytes, silences: Silences }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/models.ts b/packages/dapi/src/tools/models.ts
new file mode 100644
index 00000000..91ac7253
--- /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, image, video, or audio (default: all three)"),
+ }),
+ output: z.object({ models: z.array(ModelInfo) }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/open.ts b/packages/dapi/src/tools/open.ts
new file mode 100644
index 00000000..1b3cac7d
--- /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"),
+ }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/report.ts b/packages/dapi/src/tools/report.ts
new file mode 100644
index 00000000..a8835e65
--- /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() }),
+ environment: "main",
+});
diff --git a/packages/dapi/src/tools/screenshot.ts b/packages/dapi/src/tools/screenshot.ts
new file mode 100644
index 00000000..4463a31f
--- /dev/null
+++ b/packages/dapi/src/tools/screenshot.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";
+import { Bytes, outputDirField } from "../schemas";
+
+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: outputDirField }),
+ output: z.object({
+ path: z.string().describe("absolute path of the PNG"),
+ width: z.number(),
+ height: z.number(),
+ }),
+ result: z.object({ png: Bytes, width: z.number(), height: z.number() }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/tools.test.ts b/packages/dapi/src/tools/tools.test.ts
new file mode 100644
index 00000000..b00d26d4
--- /dev/null
+++ b/packages/dapi/src/tools/tools.test.ts
@@ -0,0 +1,120 @@
+/* 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.separate).toBeUndefined();
+ 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", separate: true, 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 times in every form", () => {
+ expect(capture.input.parse({ id: "intro", times: [0, "45f", "1:10"] }).times).toEqual([0, 1.5, 70]);
+ expect(capture.input.safeParse({ id: "intro", times: [-1] }).success).toBe(false);
+ expect(capture.input.safeParse({ id: "intro", times: ["-2f"] }).success).toBe(false);
+ });
+
+ it("shares the sheet rule with media_grab", () => {
+ expect(issues(capture.input.safeParse({ id: "intro", separate: true, 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("reports the same shape with and without an open project", () => {
+ expect(
+ context.output.safeParse({ rootDir: "/p", projectDir: null, currentTime: null, fontFamilies: [], generations: [] }).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);
+ });
+});
+
+describe("image tools", () => {
+ it("present bytes as paths: the result carries png, the output a path", () => {
+ expect(capture.result!.safeParse([{ timecode: "0f", png: new Uint8Array(3) }]).success).toBe(true);
+ expect(capture.output.safeParse({ images: [{ timecode: "0f", path: "/tmp/0f.png" }] }).success).toBe(true);
+ expect(capture.output.safeParse({ images: [{ timecode: "0f", png: new Uint8Array(3) }] }).success).toBe(false);
+ });
+});
diff --git a/packages/dapi/src/tools/voices.ts b/packages/dapi/src/tools/voices.ts
new file mode 100644
index 00000000..cb052805
--- /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.object({ voices: z.array(VoiceInfo) }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/src/tools/whoami.ts b/packages/dapi/src/tools/whoami.ts
new file mode 100644
index 00000000..d088db34
--- /dev/null
+++ b/packages/dapi/src/tools/whoami.ts
@@ -0,0 +1,17 @@
+/* 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.object({
+ user: z.object({ id: z.string(), email: z.string().optional() }).nullable(),
+ }),
+ environment: "renderer",
+});
diff --git a/packages/dapi/tsconfig.json b/packages/dapi/tsconfig.json
new file mode 100644
index 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"]
+}
diff --git a/packages/encoder/src/contact-sheet.ts b/packages/encoder/src/contact-sheet.ts
index 37259a8b..ac14ed39 100644
--- a/packages/encoder/src/contact-sheet.ts
+++ b/packages/encoder/src/contact-sheet.ts
@@ -3,6 +3,7 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
import { stampTimestampLabel } from '@diffusionstudio/runtime';
+import { encodePng } from './png';
/**
* Contact sheets: a handful of frames merged into one labelled image, so a
@@ -112,7 +113,7 @@ export function planSheetSizes(total: number, perSheet?: number): number[] {
export async function composeSheet(
frames: Array<{ image: CanvasImageSource; label: string }>,
plan: SheetPlan,
-): Promise<string> {
+): Promise<Uint8Array> {
const canvas = new OffscreenCanvas(plan.width, plan.height);
const ctx = canvas.getContext('2d')!;
@@ -133,17 +134,5 @@ export async function composeSheet(
ctx.restore();
}
- const blob = await canvas.convertToBlob({ type: 'image/png' });
- const dataUrl = await new Promise<string>((resolve, reject) => {
- const reader = new FileReader();
- reader.onload = () => resolve(reader.result as string);
- reader.onerror = () => reject(reader.error);
- reader.readAsDataURL(blob);
- });
- return dataUrl.slice(dataUrl.indexOf(',') + 1);
-}
-
-export async function decodePngBase64(base64: string): Promise<ImageBitmap> {
- const bytes = Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
- return createImageBitmap(new Blob([bytes], { type: 'image/png' }));
+ return encodePng(canvas);
}
diff --git a/packages/encoder/src/image-encoder.ts b/packages/encoder/src/image-encoder.ts
index c0bf0f48..03919812 100644
--- a/packages/encoder/src/image-encoder.ts
+++ b/packages/encoder/src/image-encoder.ts
@@ -11,12 +11,13 @@ import {
import { captureScene, normalizeSceneTransform, resolverSystem, warmupAssets } from './encoder';
import { scaleSize } from './utils';
+import { encodePng } from './png';
import type { World } from 'koota';
import type { ImageEncoderConfig } from './interfaces';
-/** One capture: the PNG plus the timecode of the frame rendered, e.g. `01s15f`. */
-export type CapturedImage = { base64: string; timecode: string };
+/** One capture: the PNG bytes plus the timecode of the frame rendered, e.g. `01s15f`. */
+export type CapturedImage = { png: Uint8Array; timecode: string };
export type ImageExportResult =
| { type: 'success'; data: CapturedImage[] }
@@ -25,7 +26,7 @@ export type ImageExportResult =
/**
* Renders single frames of the scene a capture world holds into standalone
- * PNGs (base64, no data-url prefix).
+ * PNGs.
*
* `world` is the caller's, built for this capture and holding the scene as
* the stage's only child — the same arrangement `createEncoder` takes, and
@@ -125,7 +126,7 @@ export async function createImageEncoder(world: World, config: ImageEncoderConfi
renderSystem(world);
images.set(frame, {
- base64: await toBase64Png(canvas),
+ png: await encodePng(canvas),
timecode: formatTimecode(playheadSeconds, frameRate),
});
}
@@ -148,15 +149,3 @@ export async function createImageEncoder(world: World, config: ImageEncoderConfi
};
}
-async function toBase64Png(canvas: HTMLCanvasElement): Promise<string> {
- const blob = await new Promise<Blob>((resolve, reject) => {
- canvas.toBlob((value) => value ? resolve(value) : reject(new Error('Could not encode PNG')), 'image/png');
- });
- const dataUrl = await new Promise<string>((resolve, reject) => {
- const reader = new FileReader();
- reader.onload = () => resolve(reader.result as string);
- reader.onerror = () => reject(reader.error);
- reader.readAsDataURL(blob);
- });
- return dataUrl.split(',')[1] ?? '';
-}
diff --git a/packages/encoder/src/index.ts b/packages/encoder/src/index.ts
index ab8b77dd..433dd698 100644
--- a/packages/encoder/src/index.ts
+++ b/packages/encoder/src/index.ts
@@ -8,5 +8,6 @@ export * from './encoder';
export * from './format';
export * from './image-encoder';
export * from './interfaces';
+export * from './png';
export * from './types';
export * from './utils';
diff --git a/packages/encoder/src/png.ts b/packages/encoder/src/png.ts
new file mode 100644
index 00000000..905b6190
--- /dev/null
+++ b/packages/encoder/src/png.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/. */
+
+// PNG in and out of a canvas, as bytes. Transports decide how bytes travel
+// (base64 on a JSON wire, structured clone over IPC, a file on disk); nothing
+// in the render path should have to know.
+
+export async function encodePng(canvas: HTMLCanvasElement | OffscreenCanvas): Promise<Uint8Array> {
+ const blob =
+ canvas instanceof OffscreenCanvas
+ ? await canvas.convertToBlob({ type: 'image/png' })
+ : await new Promise<Blob>((resolve, reject) => {
+ canvas.toBlob((value) => (value ? resolve(value) : reject(new Error('Could not encode PNG'))), 'image/png');
+ });
+ return new Uint8Array(await blob.arrayBuffer());
+}
+
+export function decodePng(png: Uint8Array): Promise<ImageBitmap> {
+ return createImageBitmap(new Blob([png as BlobPart], { type: 'image/png' }));
+}
diff --git a/packages/jsx/package.json b/packages/jsx/package.json
index ac5c790d..07024780 100644
--- a/packages/jsx/package.json
+++ b/packages/jsx/package.json
@@ -1,7 +1,7 @@
{
"name": "@diffusionstudio/jsx",
"version": "0.204.0",
- "description": "Types and authoring API for Diffusion Studio compositions: the JSX element vocabulary, declarative generated assets (`generate.*`), and the hooks the editor implements when a project is mounted via `dapi mount`.",
+ "description": "Types and authoring API for Diffusion Studio compositions: the JSX element vocabulary, declarative generated assets (`generate.*`), and the hooks the editor implements when it mounts a project.",
"license": "MPL-2.0",
"type": "module",
"sideEffects": false,
diff --git a/reference/README.md b/reference/README.md
deleted file mode 100644
index 9bf1420a..00000000
--- a/reference/README.md
+++ /dev/null
@@ -1,77 +0,0 @@
-# dapi CLI Reference
-
-Reference for `dapi`, the Diffusion Studio CLI. Every canvas and project command talks to the running app over a local socket. Responses are JSON written to stdout; errors are human-readable messages on stderr with a non-zero exit.
-
-Each feature command has its own file (linked below). The JSX code syntax specified in [jsx/](./jsx/README.md) is **pseudo-SVG**, mirroring SVG's shape-and-paint model with the editor's own tags and props rather than the SVG spec.
-
-A project is a folder of that JSX, and **the source is the document**: the app compiles the entry file and renders every element into an editable node, and edits made on the canvas are written back to the element that authored them. So the loop is `dapi open <dir>` once, then edit the files — there is no command that pushes content into the app. What the commands do is read the running app ([`context`](./context.md), [`capture`](./capture.md), [`logs`](./logs.md)), inspect media, and list what a declaration may name.
-
-## Groups
-
-**Top-level:** [`whoami`](./whoami.md), [`logs`](./logs.md), [`screenshot`](./screenshot.md), [`report`](./report.md), [`context`](./context.md) (alias `ctx`), [`capture`](./capture.md), [`check`](./check.md), [`export`](./export.md), [`models`](./models.md), [`voices`](./voices.md), [`fonts`](./fonts.md), [`fetch`](./fetch.md).
-
-| Group | Alias | Scope |
-| ----- | ----- | ----- |
-| `media` | `m` | Inspect a media file by path, without adding it to the project. Local files and URLs work with or without an open project; library paths need one. |
-
-How the surface is divided:
-
-- AI asset generation (image / video / speech / audio) is declared in the project module (`generate.*`, see [jsx/generate.md](./jsx/generate.md)). `models` and `voices` list what those declarations can reference.
-- Inspecting an existing asset (probe / transcribe / listen / filmstrip / waveform / grab) lives under `media`.
-
-## Commands
-
-### App
-
-- [`dapi whoami`](./whoami.md): print the authenticated account
-- [`dapi logs`](./logs.md): recent console output from the running app
-- [`dapi screenshot`](./screenshot.md): capture the entire application window as a PNG
-- [`dapi report`](./report.md): file a GitHub issue about a bug in the CLI or the app, with diagnostics attached
-
-### Document
-
-- [`dapi open`](./open.md): launch the app and open (or create) a project folder, anywhere on disk
-- [`dapi context`](./context.md): which project the app has open, where its playhead sits, its registered fonts, and where its generations stand
-- [`dapi capture`](./capture.md): render frames of a scene, as an export would, to a labelled contact sheet or one PNG per position
-- [`dapi check`](./check.md): check a node's subtree for structural mistakes (black-frame gaps, never-visible nodes, failed sources) and report subtree stats
-- [`dapi export`](./export.md): encode a scene to a video file, with the settings saved in the project's `package.json`
-
-### Media
-
-- [`dapi media probe`](./media/probe.md): container and track metadata
-- [`dapi media transcribe`](./media/transcribe.md): timed speech transcript
-- [`dapi media grab`](./media/grab.md): decode video frames to a labelled contact sheet, or one PNG per frame
-- [`dapi media filmstrip`](./media/filmstrip.md): grid of video frames as a PNG
-- [`dapi media waveform`](./media/waveform.md): audio waveform PNG with silence highlighting
-- [`dapi media listen`](./media/listen.md): AI description of an audio track
-
-### Generation reference
-
-- [`dapi models`](./models.md): list generation models and constraints
-- [`dapi voices`](./voices.md): list speech voices
-
-### Fonts
-
-- [`dapi fonts`](./fonts.md): list local fonts
-
-### Download
-
-- [`dapi fetch`](./fetch.md): download a video with yt-dlp (installed separately)
-
-## Shared types
-
-```ts
-Asset = { id: string; path: string; type: string } // asset ids are content hashes; `path` is the library path
-Time = number | `${number}f` | "MM:SS" // seconds, frames at 30 fps ("45f"), or a clock string; see jsx/timing.md
-NodeId = string // an element's `id` in the project's JSX; `file:id` when two files collide
-```
-
-Time inputs take the `Time` format unless noted otherwise. Times in **outputs** are plain seconds.
-
-## Conventions
-
-- **Stdout is JSON.** Commands that return a single record emit one JSON value. Commands that return a collection emit JSON Lines (one object per line, no surrounding array) so per-item results stay streamable. Exceptions: `fonts --names-only` writes plain family names; `logs` writes plain formatted log lines.
-- **Unix-style names are canonical.** Commands without a natural Unix equivalent (`context`, `whoami`) keep their descriptive names.
-- **Stderr:** human-readable error messages.
-- **Exit codes:** `0` on success, `1` on any error (missing file, app not running, invalid input, IPC error).
-- **App must be running:** every command except `fonts` and `fetch` talks to the open Diffusion Studio instance. If the app isn't running, the CLI prints an instruction to launch it and exits `1`. `report` is the one command that reads from the app but tolerates its absence, recording it in the issue instead of failing.
diff --git a/reference/capture.md b/reference/capture.md
deleted file mode 100644
index dd7cd1be..00000000
--- a/reference/capture.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# `dapi capture <id> [-t, --time <time...>]`
-
-Renders single frames of a scene at one or more timeline positions and merges them into **contact sheets**: up to 12 positions per PNG, each cell labelled with the timecode of the frame actually rendered and drawn as large as the sheet allows, so a few positions arrive as one high-resolution picture instead of a directory to open one by one. `--separate` writes a PNG per position instead.
-
-Each frame is **the frame an export of that scene would encode**: the scene is re-rendered from a fresh mount at its own size, position `0` is the workarea's first frame, and the requested positions are evaluated in timeline order, forward only — the way an export advances — so a composition whose look depends on having played (an `<html>` node's own animation state, for instance) captures exactly as it exports. 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 the element plays. To grab a video asset's own pixels instead of a composited frame, use [`media grab`](./media/grab.md).
-
-## Input
-
-- `<id>`: scene id to capture (required) — the scene's `id` attribute in the project's JSX (e.g. `intro`), or its position in the file when it has none. When two files use the same id, the `file:id` form (`index.tsx:intro`) settles it. Entity numbers are not accepted; they change on every recompile.
-- `-t, --time <time...>`: one or more positions to capture, relative to the export's first frame — the workarea's start, so `0` is the export's frame 0 — each a `Time` value (optional; default `0`)
-- `-S, --separate`: write one PNG per position instead of merging them into contact sheets (optional). Each is rendered at 720p height and named after its timecode (e.g. `01s12f.png`).
-- `--per-sheet <n>`: positions per contact sheet, 1 to 12 (optional; default as many as fit). Fewer positions per sheet means a larger cell each. Sheets are balanced, so 13 positions become 7 + 6 rather than 12 + 1.
-- `-o, --output <dir>`: directory to write the PNGs into (optional; default a fresh `dapi-capture-*` directory in the system temp directory, so runs never overwrite each other). Writing into the same directory twice overwrites images whose name matches; with `--separate`, requested times that land on the same frame share one file.
-
-## Timecodes
-
-Cell labels, the `timecode` field, and the filenames all use the same stamp, which drops its zero segments: `08s10f` is 8 seconds and 10 frames, `01m05s` is 65 seconds, and the export's first frame is `0f`. Each segment carries its unit, so nothing is ambiguous once the empty ones are gone.
-
-## Layout
-
-A sheet never exceeds 2576x1456, the largest image a vision model reads at full detail. Within that budget the grid is the one that draws each frame largest, and the last row may be partially filled. Cells render at their own size rather than the flat 720p of `--separate`, so a few positions are sharper than a standalone capture and never coarser; a scene smaller than 1080p tall is rendered up to that height, and nothing is rendered beyond it. Sheets are named after the span they cover, e.g. `0f-11s.png`. For a 16:9 scene the cell sizes are:
-
-| Positions | Grid | Per-frame |
-|---|---|---|
-| 1 | 1x1 | 1920x1080 |
-| 2-4 | 2x1, 2x2 | 1280x720 |
-| 5-9 | 3x2, 3x3 | 850x478 |
-| 10-12 | 4x3 | 636x357 |
-
-Sheets are opaque: a scene's transparent background composites onto flat grey, and the gutters between cells use the same grey.
-
-## Output
-
-JSON Lines, one object per written image: a contact sheet by default, a position with `--separate`.
-
-```ts
-{ timecode: string; path: string } // e.g. { "timecode": "0f-01s15f", "path": "/tmp/dapi-capture-3f2c1a8e/0f-01s15f.png" }
-```
-
-A sheet's timecode is the span it covers; a single position's is its own. Sheets come in timeline order, and their cells in the order the positions were requested in.
-
-## Errors
-
-Exits non-zero if no project is open (`No project open` — run `dapi open <dir>` first), the id is unknown, the id is ambiguous (two files use it — pass `file:id`), the id names a node that is not a scene (the error names the scene to capture instead), `--per-sheet` is outside 1 to 12, or a PNG can't be written.
diff --git a/reference/context.md b/reference/context.md
deleted file mode 100644
index 89f1277d..00000000
--- a/reference/context.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# `dapi context`
-
-Summary of app state: what the project's source cannot say. The composition
-itself — its scenes, what is selected, which scene is active, the work area —
-is all in the JSX, and a caller that wants any of it reads the file. Alias:
-`ctx`.
-
-## Input
-
-None.
-
-## Output
-
-One JSON object:
-
-```ts
-{
- rootDir: string | null; // absolute folder projects live under; null until one is picked
- projectDir: string | null; // absolute open project folder — where the JSX being edited lives; null when none is open
- currentTime: number | null; // playhead in the active scene, in seconds; null if no scene is active
- fontFamilies: string[]; // families registered in the running world, valid as `fontFamily`
- generations: { // every generated source in the project, and where it stands
- element: string | null; // the element's source stamp, `<file>:<id>`; null for an entity no element produced
- name: string | null; // the element's `name`, when it has one
- state: "generating" | "failed" | "done";
- error?: string; // what it failed with, on `failed` rows
- asset?: string; // the library path it landed as, on `done` rows
- }[];
-}
-```
-
-With no project open (the app sits at the dashboard) the report is just
-`{ rootDir, projectDir: null }`: there is no playhead, no world, and no fonts
-to speak of. Open one with [`dapi open`](./open.md).
-
-`rootDir` is reported whether or not a project is open — it is where a caller
-with nothing open goes to create or find one.
-
-`currentTime` is local to the active scene, the same origin a clip's `start`
-and `end` are placed against, and in the same unit.
-
-`projectDir` is the folder the app is editing, which is not necessarily the
-one a command was run from: check it before writing to source files.
-
-`fontFamilies` is what text can be drawn with right now — loaded into the world,
-not merely named in the source — and always includes the editor default. For
-every family installed on the machine, see [`dapi fonts`](./fonts.md).
-
-`generations` is how a caller waits for `generate.*` declarations without
-blocking: generation is asynchronous, so poll this until nothing is
-`generating`. A `done` row's `asset` is a library path, ready for
-[`dapi media probe`](./media/probe.md) and its siblings; a `failed` row's
-`error` is the same message the element carries as its `error` prop, which is
-what keeps it from being generated again (see
-[jsx/errors.md](./jsx/errors.md#failed-sources)).
diff --git a/reference/export.md b/reference/export.md
deleted file mode 100644
index f3823172..00000000
--- a/reference/export.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# `dapi export <id> [output]`
-
-Encodes a scene to a video file — the full render the app's own export runs: the scene re-rendered from a fresh mount at its own size, the workarea from start to end, video and audio, streamed to the output file as it encodes. What [`capture`](./capture.md) shows one frame of, `export` writes all of.
-
-**The settings live in the project, not on the command.** The export is made with the scene's entry in the project's `package.json` — the same entry the app's export panel writes — so a CLI export reproduces the in-app one exactly, and the settings version with the project. The command decides only what to export and where to put it; a hand edit to `package.json` is picked up by the running app immediately, no reload needed.
-
-Renders take as long as the scene demands (the CLI waits up to 60 minutes). The app shows the export's progress overlay while it runs, with a working Cancel button; one export runs at a time. Verify frames with [`capture`](./capture.md) and structure with [`check`](./check.md) before spending the render time.
-
-## Input
-
-- `<id>`: scene id to export (required) — the scene's `id` attribute in the project's JSX, or `file:id` when two files use the same id. Scenes only: a scene is the unit an export renders, and the error names the scene to export when the id is some other node's.
-- `[output]`: output file path, ffmpeg-style (optional; relative paths resolve against the working directory). Its extension picks the container — `.mp4`, `.webm`, `.ogg` (audio only), `.mov` — overriding the configured format, so the file is always what its name says. A path without one of those extensions is an error. Omitted, the file lands at `exports/<id>.<format>` in the project folder (parent directories are created); an existing file is overwritten.
-
-## Settings
-
-The scene's entry under `diffusion.export.<id>` in the project's `package.json`:
-
-```jsonc
-{
- "diffusion": {
- "export": {
- "intro": {
- "format": "mp4", // mp4 | webm | ogg | mov
- "video": {
- "enabled": true, // false encodes audio only
- "codec": "avc", // avc | hevc | vp9 | av1 | vp8
- "bitrate": 12000000, // bits per second
- "fps": 30, // capture rate; default: the project's
- "resolution": 1080 // shorter-side "p" number: 720 | 1080 | 1440 | 2160
- },
- "audio": {
- "enabled": true,
- "codec": "aac", // aac | opus
- "sampleRate": 48000,
- "bitrate": 128000
- }
- }
- }
- }
-}
-```
-
-Every field is optional; the encoder fills what the entry leaves out. A scene without an entry exports with the defaults — 1080p H.264 MP4 with AAC audio, the app's default template. `resolution` scales the scene uniformly until its shorter side reaches the number, so a portrait 1080×1920 scene at `2160` encodes as 2160×3840.
-
-## Output
-
-One JSON object once the file is written:
-
-```ts
-{
- path: string; // absolute path of the written file
- width: number; // encoded pixel size (0×0 for an audio-only export)
- height: number;
- duration: number; // seconds encoded (the workarea's length)
- size: number; // bytes written
- config: { // the settings the export was made with — the package.json
- format: string; // entry (or the defaults), with the container the
- video?: {...}; // extension resolved to. Fields the entry left out are
- audio?: {...}; // absent; the encoder used its defaults for them.
- }
-}
-```
-
-The echoed `config` is the confirmation of what a `package.json` edit actually did: fields of the wrong type are dropped when the entry is read, so a typoed key shows up here as the default it fell back to.
-
-## Errors
-
-Exits non-zero if no project is open (`No project open` — run `dapi open <dir>` first), the id is unknown or ambiguous (pass `file:id`), the id names a node that is not a scene (the error names the scene to export instead), the output path lacks a container extension, the entry's format is unknown, the configuration is unencodable on this machine (codec × resolution × bitrate — the error says what to lower), another export is already running, or the export is canceled in the app. A failed or canceled export deletes the partial file.
diff --git a/reference/fetch.md b/reference/fetch.md
deleted file mode 100644
index 1ed87627..00000000
--- a/reference/fetch.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# `dapi fetch <url>`
-
-Downloads a video with [yt-dlp](https://github.com/yt-dlp/yt-dlp). Does not require the app to be running. yt-dlp is not bundled: install it separately (`brew install yt-dlp`, or `pipx install yt-dlp`). If it is not on `PATH`, the command exits `1` with an install hint; set `YT_DLP_PATH` to point at a specific binary.
-
-This writes the file to disk only; it does not touch the open project.
-
-## Arguments
-
-- `<url>`: the video or page URL to download.
-
-## Options
-
-- `-o, --output <path>`: output file path or directory (yt-dlp `-o` template). Default: yt-dlp's own default template in the current directory.
-- `-f, --format <selector>`: yt-dlp format selector, e.g. `"bv*+ba/b"`. Default: prefer mp4/m4a streams and remux the result to `.mp4` (`--merge-output-format mp4`), falling back to the best available if no mp4 source exists.
-- `-a, --audio`: extract audio only (yt-dlp `-x`). Takes precedence over the mp4 default.
-
-## Passthrough
-
-Forward raw yt-dlp flags after `--`; they are appended verbatim:
-
-```sh
-dapi fetch https://youtu.be/xyz -f "bv*+ba/b" -- --sponsorblock-remove all --limit-rate 2M
-```
-
-## Output
-
-JSON Lines, one per file written (a single URL can yield several, e.g. a playlist):
-
-```ts
-{ path: string } // absolute path of the file on disk, after any extraction / rename
-```
-
-Download progress is rendered by yt-dlp on stderr while the command runs.
-
-## Notes
-
-- The resolved path comes from yt-dlp's `after_move:filepath`, so it reflects the real name after audio extraction or renaming, not a guess.
-- Exit code is `0` on success; on failure the command surfaces yt-dlp's exit code and prints its stderr.
diff --git a/reference/fonts.md b/reference/fonts.md
deleted file mode 100644
index 34b96b4e..00000000
--- a/reference/fonts.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# `dapi fonts`
-
-Lists local fonts available on this machine. macOS only. Does not require the app to be running. Font families listed here are valid `fontFamily` values on [`<text>`](./jsx/text.md).
-
-## Options
-
-- `-f, --family <pattern>`: filter to families whose name contains `<pattern>` (case-insensitive)
-- `-w, --weight <weights...>`: filter to variants with the given CSS weight(s), e.g. `-w 400 700`
-- `-s, --style <style>`: `"normal"` or `"italic"`
-- `-l, --limit <n>`: output at most `<n>` families
-- `-n, --names-only`: output only family names, one per line, plain text (no JSON)
-
-## Output
-
-JSON Lines, one per family (or plain family names when `--names-only` is set):
-
-```ts
-{
- family: string;
- variants: Array<{
- weight: string; // CSS weight, e.g. "400"
- style: "normal" | "italic";
- source: string; // CSS local() source
- }>;
-}
-```
diff --git a/reference/logs.md b/reference/logs.md
deleted file mode 100644
index 5f8a39e8..00000000
--- a/reference/logs.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# `dapi logs`
-
-Prints recent console output from the running app: everything the devtools console shows, including page logs, worker logs, uncaught errors, and Chromium warnings. Oldest first. The app buffers the last 2000 entries in its main process, so the log survives page reloads and project switches; use this instead of relaunching with `ELECTRON_ENABLE_LOGGING=1` to see renderer-side errors.
-
-## Options
-
-- `-n, --tail <n>`: output only the last `<n>` entries (positive integer)
-- `-l, --level <level>`: minimum level to include: `"debug"`, `"info"`, `"warning"`, or `"error"`
-
-## Output
-
-Plain text (no JSON), one line per entry:
-
-```
-HH:MM:SS.mmm [level] message (source:line)
-```
-
-Timestamps are local time. `source:line` is the logging call site (a URL in dev builds); omitted for synthetic entries such as renderer crashes and preload errors.
-
-## Errors
-
-Exits non-zero on an invalid `--tail` or `--level`, or if the app is not running.
diff --git a/reference/media/filmstrip.md b/reference/media/filmstrip.md
deleted file mode 100644
index 01180e14..00000000
--- a/reference/media/filmstrip.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# `dapi media filmstrip <path>`
-
-Renders a **filmstrip** of a video to a PNG, written to a file in the system temp directory: a grid of frames sampled at even intervals across the window, each row stamped with a timestamp ruler. Video only; use [`dapi media waveform`](./waveform.md) to inspect the audio track. Renders locally; no credits. Alias: `film`.
-
-Tick labels use `HH:MM:SS:FF` timecode (hours, minutes, seconds, frame within the second) at every zoom level, so labels stay comparable regardless of the window's span. Frames count against the video's frame rate.
-
-## Input
-
-- `<path>`: a local video file to preview in place without adding it to the library, or a project library path (required; library paths need an open project).
-- `-s, --start <time>`: start of the window to preview, a `Time` value in source/content time (optional; default `0`).
-- `-e, --end <time>`: end of the window to preview, a `Time` value (optional; default the asset's duration).
-- `-x, --scale <factor>`: scale factor for the thumbnails (optional; default `1`, clamped to `0.25`-`4`). The overall canvas size stays fixed, so smaller thumbnails fit **more rows and columns** (a denser grid sampling more moments) and larger thumbnails fit fewer but show more detail each.
-- `-o, --output <path>`: write the PNG here instead of a temp file (optional).
-
-## Output
-
-One JSON object, the absolute path to the written PNG:
-
-```ts
-{
- path: string, // e.g. "/tmp/3f2c1a8e-....png", or the --output path
-}
-```
-
-## Errors
-
-Exits non-zero if the path can't be resolved, the asset isn't a video, `--start`/`--end` fall outside the asset or cross (`--start` >= `--end`), `--scale` isn't a positive number, or `--output` can't be written.
diff --git a/reference/media/grab.md b/reference/media/grab.md
deleted file mode 100644
index 5b735d26..00000000
--- a/reference/media/grab.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# `dapi media grab <path>`
-
-Decodes one or more frames of a video asset at the given times and merges them into **contact sheets**: up to 12 frames per PNG, each cell labelled with its timecode and drawn as large as the sheet allows, so a handful of frames arrives as one high-resolution picture instead of a directory to open one by one. `--separate` writes a PNG per frame instead. Like [`capture`](../capture.md), but grabs the asset's own pixels (unlike `capture`, which renders the composited node). Renders locally; no credits. Past ~12 frames, [`media filmstrip`](./filmstrip.md) is the cheaper way to scan a clip.
-
-## Input
-
-- `<path>`: a local video file to grab frames from in place without adding it to the library, or a project library path (required; library paths need an open project).
-- `-t, --time <time...>`: one or more timestamps to grab, `Time` values in source/content time (optional; default `0`). A negative value is an offset back from the end of the clip, so `-1` is one second before the end and `-1f` one frame before it. Order is preserved in the output regardless of the order given. Mutually exclusive with `--count`.
-- `-c, --count <n>`: instead of `--time`, grab `n` frames evenly spaced across the clip at a fixed interval of `window / n`, starting at the window start (optional; positive integer).
-- `-s, --start <time>`: with `--count`, the start of the window to sample (optional; `Time` value; default `0`).
-- `-e, --end <time>`: with `--count`, the end of the window to sample (optional; `Time` value; default the asset duration).
-- `-q, --quality <preset>`: per-frame resolution preset (optional). One of `small` (384x384), `medium` (768x768), `large` (1536x1536), or `fullres` (native); each caps the total pixel count while preserving aspect ratio. Defaults to as much detail as the sheet cell can show, or `small` with `--separate`.
-- `-S, --separate`: write one PNG per frame instead of merging them into contact sheets (optional). The frames keep their own resolution and alpha, and each file is named after its timecode (e.g. `01s12f.png`).
-- `--per-sheet <n>`: frames per contact sheet, 1 to 12 (optional; default as many as fit). Fewer frames per sheet means a larger cell each. Sheets are balanced, so 13 frames become 7 + 6 rather than 12 + 1.
-- `--uncapped`: lift the 100-frame safety cap (optional). Without it, requesting more than 100 frames (via `--count` or `--time`) is rejected.
-- `-o, --output <dir>`: directory to write the PNGs into (optional; default a fresh `dapi-grab-*` directory in the system temp directory, so runs never overwrite each other). Writing into the same directory twice overwrites images whose name matches; with `--separate`, requested times that land on the same frame share one file.
-
-## Timecodes
-
-Cell labels, the `timecode` field, and the filenames all use the same stamp, which drops its zero segments: `08s10f` is 8 seconds and 10 frames, `01m05s` is 65 seconds, and the first frame is `0f`. Each segment carries its unit, so nothing is ambiguous once the empty ones are gone. (The rulers `filmstrip` and `waveform` draw stay on fixed-width `HH:MM:SS:FF`, so their ticks line up.)
-
-## Layout
-
-A sheet never exceeds 2576x1456, the largest image a vision model reads at full detail. Within that budget the grid is the one that draws each frame largest, frames are never enlarged past their source resolution, and the last row may be partially filled. Sheets are named after the span they cover, e.g. `0f-08s10f.png`. For 16:9 footage the cell sizes are:
-
-| Frames | Grid | Per-frame |
-|---|---|---|
-| 1 | 1x1 | 2568x1444 |
-| 2-4 | 2x1, 2x2 | 1280x720 |
-| 5-9 | 3x2, 3x3 | 850x478 |
-| 10-12 | 4x3 | 636x358 |
-
-## Output
-
-JSON Lines, one object per written image: a contact sheet by default, a frame with `--separate`.
-
-```ts
-{ timecode: string; path: string } // e.g. { "timecode": "0f-08s10f", "path": "…/0f-08s10f.png" }
-```
-
-A sheet's timecode is the span it covers; a frame's is its own. Sheets come in time order, and their cells in the order the times were requested in.
-
-## Errors
-
-Exits non-zero if the path can't be resolved, the asset is not a video, any `--time` is past the asset's duration, the `--count` window is empty, `--time` and `--count` are combined, `--start`/`--end` are given without `--count`, `--per-sheet` is outside 1 to 12, more than 100 frames are requested without `--uncapped`, or a PNG can't be written.
diff --git a/reference/media/listen.md b/reference/media/listen.md
deleted file mode 100644
index 3fdfbde6..00000000
--- a/reference/media/listen.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# `dapi media listen <path>`
-
-Puts a multimodal model in front of an audio track and returns its answer. With no prompt it returns a general description of what is heard; with `--prompt` it answers that question about the audio (e.g. "who is speaking?", "what music is playing?", "summarize what is said"). Accepts an audio file or a video, but only the audio track is analyzed by default. Alias: `watch`.
-
-## Input
-
-- `<path>`: a local audio or video file to analyze in place without adding it to the library, or a project library path (required; library paths need an open project).
-- `-p, --prompt <str>`: question or instruction about the audio (optional; defaults to a general description).
-- `-s, --start <time>`: start of the segment to analyze, a `Time` value (optional; default `0`). Timestamps in the analysis are relative to this point.
-- `-e, --end <time>`: end of the segment to analyze, a `Time` value (optional; default the asset's duration).
-- `--keep-video`: for a video asset, keep the video track instead of stripping it to audio, so the model can analyze what is on screen (optional; default off). Expensive: requires a full video upload.
-
-## Output
-
-One JSON object, the model's answer. `start`/`end` echo the analyzed window (in seconds) and are present only when `-s`/`-e` were given:
-
-```ts
-{ result: string, start?: number, end?: number }
-```
-
-## Errors
-
-Exits non-zero if the path can't be resolved, the asset isn't a video or audio asset, or `--start`/`--end` cross (`--start` >= `--end`).
diff --git a/reference/media/probe.md b/reference/media/probe.md
deleted file mode 100644
index a1740961..00000000
--- a/reference/media/probe.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# `dapi media probe <path>`
-
-Reads the container and per-track technical metadata of an asset; like `ffprobe`, but demuxed locally with mediabunny. Reports the container format, duration, metadata tags, and every track's codec parameters without decoding any media. Reads locally; no credits.
-
-## Input
-
-- `<path>`: a local file to probe in place without adding it to the library, or a project library path (required; library paths need an open project). Any asset type is accepted.
-
-## Output
-
-One JSON object. The shape is **not yet stable**: it reports whatever mediabunny surfaces about the container and its tracks. Packet stats (frame rate, bitrate, packet count) are estimated from a leading sample of packets, so they are fast but approximate. Assets mediabunny can't demux (images, transcripts) don't error; they report file-level info only, with `format: null` and no tracks.
-
-## Errors
-
-Exits non-zero if the path can't be resolved.
diff --git a/reference/media/transcribe.md b/reference/media/transcribe.md
deleted file mode 100644
index ae5e29ff..00000000
--- a/reference/media/transcribe.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# `dapi media transcribe <path>`
-
-Transcribes the speech in a video or audio asset and returns the timed transcript. Word-level start/end times are in **seconds** (source/content time).
-
-## Input
-
-- `<path>`: a local video or audio file to transcribe in place without adding it to the library, or a project library path (required; library paths need an open project).
-
-The whole asset is transcribed once per app session (cached in memory, keyed by file content; an app restart or an edited file re-transcribes).
-
-## Output
-
-One JSON object, the transcript:
-
-```ts
-{
- segments: Array<{
- text: string; // spoken words only (no silence markers)
- words: Array<{ text: string; start: number; end: number }>; // seconds
- }>;
-}
-```
-
-## Errors
-
-Exits non-zero if the path can't be resolved or the asset is not a video/audio asset, or if no speech is detected in the audio at all (`No speech detected`).
diff --git a/reference/media/waveform.md b/reference/media/waveform.md
deleted file mode 100644
index 7d7ef2db..00000000
--- a/reference/media/waveform.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# `dapi media waveform <path>`
-
-Renders the audio track of a video or audio file as an amplitude **waveform** PNG, written to a file in the system temp directory: loudness over time drawn from decoded audio peaks, with a timestamp ruler. Silent stretches are highlighted in red. Renders locally; no credits. Alias: `wave`.
-
-Tick labels use `HH:MM:SS:FF` timecode (hours, minutes, seconds, frame within the second) at every zoom level, so labels stay comparable regardless of the window's span. For a video, frames count against the video's frame rate; for a standalone audio asset, the ruler counts against a nominal 30 fps.
-
-## Input
-
-- `<path>`: a local video or audio file to preview in place without adding it to the library, or a project library path (required; library paths need an open project).
-- `-s, --start <time>`: start of the window to preview, a `Time` value in source/content time (optional; default `0`).
-- `-e, --end <time>`: end of the window to preview, a `Time` value (optional; default the asset's duration).
-- `-x, --scale <factor>`: scale factor for the waveform (optional; default `1`, clamped to `0.25`-`4`). The overall canvas size stays fixed, so a smaller scale fits **more rows and columns** (a denser time axis) and a larger scale fits fewer but taller rows.
-- `-o, --output <path>`: write the PNG here instead of a temp file (optional).
-
-## Output
-
-One JSON object, the absolute path to the written PNG plus the silent stretches (the red spans on the waveform) as `[start, end]` second ranges, in absolute seconds (offset by `--start` when a window is used):
-
-```ts
-{
- path: string, // e.g. "/tmp/3f2c1a8e-....png", or the --output path
- silences: Array<{ start: number, end: number }>,
-}
-```
-
-## Errors
-
-Exits non-zero if the path can't be resolved, the asset has no decodable audio track, `--start`/`--end` fall outside the asset or cross (`--start` >= `--end`), `--scale` isn't a positive number, or `--output` can't be written.
diff --git a/reference/models.md b/reference/models.md
deleted file mode 100644
index 89fb6404..00000000
--- a/reference/models.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# `dapi models [type]`
-
-Lists the generation models available for a media type, including each model's capabilities. Use it to discover valid model ids and the per-model constraints (durations, aspect ratios, features) to set on an asset declaration (see [jsx/generate.md](./jsx/generate.md)).
-
-There are no CLI commands that generate; asset generation is declared in the project module and produced on mount.
-
-## Input
-
-- `[type]` (optional): one of `image`, `video`, `audio`. Omit to list all three groups.
-
-## Output
-
-JSON Lines, one per model:
-
-```ts
-{
- type: "image" | "video" | "audio";
- id: string; // the model id to set on a generate.* declaration
- name: string;
- durations?: string[]; // video only, e.g. ["5s","10s"]
- aspectRatios?: string[]; // video only
- features?: Array<"start-frame" | "end-frame" | "audio">; // video only
-}
-```
diff --git a/reference/open.md b/reference/open.md
deleted file mode 100644
index 934ee176..00000000
--- a/reference/open.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# `dapi open [path]`
-
-Launches Diffusion Studio — or surfaces the running instance — and, given a
-path, opens that folder as a project. The first command of the core loop:
-`open`, then mount, then render.
-
-The folder may live anywhere on disk, and does not have to be a project yet.
-Opening is what makes it one, writing as little as that takes:
-
-- a missing folder is created;
-- a folder with no entry file (package.json `main`, or `index.tsx` and
- friends) gains an `index.tsx` holding an empty stage.
-
-Nothing else is written — no package.json, tsconfig, README, or manifest. A
-project is its JSX; the rest of the scaffold appears lazily, each piece when
-something first needs it. A folder that is already a project is opened
-untouched, wherever it lives.
-
-The app remembers the folder, so the project reopens across app relaunches
-and stays addressable by folder name or project id.
-
-## Input
-
-- `[path]`: project folder to open or create (optional; with no path the
- command just makes sure the app is up). Relative paths resolve against the
- shell's working directory.
-- `-b, --background`: launch or keep the app in the background, without
- raising a window. The way to drive the editor headless.
-
-## Output
-
-With a path, the opened project as one JSON object:
-
-```ts
-{
- id: string; // package.json `projectId`; "" until the project has a record
- name: string; // display name (falls back to the folder name)
- dir: string; // absolute project folder, as opened
-}
-```
-
-With no path, nothing: exit code `0` says the app is up.
-
-## Errors
-
-- The path exists but is not a folder.
-- Off macOS, the app cannot be launched; the command then requires it to
- already be running.
diff --git a/reference/report.md b/reference/report.md
deleted file mode 100644
index bcbb4703..00000000
--- a/reference/report.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# `dapi report <title>`
-
-Reports a bug in `dapi` itself or in the app behind it: a command that errors, contradicts this reference, or returns something it shouldn't. Bundles the description with diagnostics (dapi version, platform, node version, the app's recent console output) and files it as a GitHub issue on [diffusionstudio/editor](https://github.com/diffusionstudio/editor/issues), printing the URL of the created issue.
-
-The issue is submitted immediately, in the background, with no review step: the command returns once the issue exists. Filing goes through the [`gh`](https://cli.github.com) CLI, which must be installed and authenticated (`gh auth login`); without it the command exits `1` and files nothing.
-
-This is for defects in the tooling, not for problems inside a project: a composition that looks wrong, a node in the wrong place, or a generation that missed the prompt are editing problems, not reported here.
-
-Does not require the app to be running. If the app is down or unreachable, the report records that instead of failing, since that is often the bug being reported.
-
-## Arguments
-
-- `<title>`: one-line summary of the problem, used as the issue title.
-
-## Options
-
-- `-b, --body <text>`: what happened, in markdown: what you expected, what you got, and anything the diagnostics won't show.
-- `-c, --command <cmd...>`: the `dapi` command(s) that reproduce it, in order. Repeatable (`-c "dapi context" -c "dapi capture intro"`); rendered as a shell block under `## Repro`.
-- `--logs <n>`: trailing app log entries to attach (default: 50). `--logs 0` omits the section, and then the app is not contacted at all.
-
-## Output
-
-One JSON object:
-
-```ts
-{
- url: string // the created github.com/diffusionstudio/editor issue
-}
-```
-
-## Issue layout
-
-The title is the issue title; the body is assembled from the options and the diagnostics:
-
-````md
-<body>
-
-## Repro
-
-```sh
-dapi capture intro
-```
-
-## Environment
-
-| | |
-| --- | --- |
-| dapi | 0.129.0 |
-| platform | darwin 25.5.0 (arm64) |
-| node | v20.19.0 |
-| app | running |
-
-## App logs
-
-```
-19:37:17.538 [info] Finalizing file (…)
-```
-````
-
-The `app` row reads `running`, `not running`, `not checked` (with `--logs 0`), or the reason it was unreachable.
-
-## Notes
-
-- Attached logs are the same entries [`logs`](./logs.md) prints, and can contain project names, file paths, and prompt text. They go straight to a public issue: pass `--logs 0`, or check what [`logs`](./logs.md) currently holds, before reporting from a sensitive project.
-- Exits non-zero on an empty title, an invalid `--logs`, a missing `gh`, or a failure from `gh` (not authenticated, no access to the repo); the message from `gh` is passed through.
-- `dapi issue` is an alias of this command.
diff --git a/reference/screenshot.md b/reference/screenshot.md
deleted file mode 100644
index 70116903..00000000
--- a/reference/screenshot.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# `dapi screenshot`
-
-Captures 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. Use it to check what the app itself looks like; to render a node or scene cleanly for composition checks use [`capture`](./capture.md) instead.
-
-The shot is taken from the app's own window buffer, so it works even when the window is hidden or covered by other windows, and never includes anything outside the app.
-
-## Options
-
-- `-o, --output <dir>`: directory to write the PNG into (default: the system temp directory)
-
-## Output
-
-One JSON object: the absolute path to a freshly written PNG, plus the image's pixel dimensions.
-
-```ts
-{ path: string, width: number, height: number }
-```
-
-## Errors
-
-Exits non-zero if the app is not running.
diff --git a/reference/voices.md b/reference/voices.md
deleted file mode 100644
index b7cf287a..00000000
--- a/reference/voices.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# `dapi voices`
-
-Lists the speech voices available for `generate.voice` declarations (see [jsx/generate.md](./jsx/generate.md)).
-
-## Input
-
-None.
-
-## Output
-
-JSON Lines, one per voice:
-
-```ts
-{ id: string; label: string; description: string }
-```
diff --git a/reference/whoami.md b/reference/whoami.md
deleted file mode 100644
index bdd303f9..00000000
--- a/reference/whoami.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# `dapi whoami`
-
-Prints the authenticated account, or `null` if signed out.
-
-## Input
-
-None.
-
-## Output
-
-One JSON value:
-
-```ts
-{ id: string; email: string; provider: string } | null
-```
