The VS Code of video editing, built for agents.
TypeScript
Add project initialization tests and refactor project handling logic
konstantin-paulus04f388ff3358
diff --git a/apps/desktop/src/dapi/handlers/fetch.ts b/apps/desktop/src/dapi/handlers/fetch.tsindex a809bf23..e00d2549 100644--- a/apps/desktop/src/dapi/handlers/fetch.ts+++ b/apps/desktop/src/dapi/handlers/fetch.ts@@ -4,37 +4,60 @@import { spawn, spawnSync } from "node:child_process";import { DapiError } from "@diffusionstudio/dapi";+import { hydrateEnv, which } from "@diffusionstudio/agent-chat/host/env";+import type { HostEnv } from "@diffusionstudio/agent-chat/host/env";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";+// A Finder- or Dock-launched app inherits launchd's minimal PATH+// (/usr/bin:/bin:/usr/sbin:/sbin), which is where a Homebrew or pipx yt-dlp+// is not. The login shell's PATH is read once and searched, then the usual+// install dirs; YT_DLP_PATH is an escape hatch for pinned installs. The+// hydrated env is also what yt-dlp runs with, so it finds ffmpeg for merging+// and extraction the same way.+let hostEnv: Promise<HostEnv> | undefined;-// 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" });+function host(): Promise<HostEnv> {+ return (hostEnv ??= hydrateEnv());+}++/** Where yt-dlp is, or null when it is nowhere the app can see. */+async function resolveYtDlp(): Promise<{ bin: string; env: HostEnv["env"] } | null> {+ const env = await host();+ const override = env.env.YT_DLP_PATH ?? process.env.YT_DLP_PATH;+ const bin = override ?? which("yt-dlp", env);+ return bin ? { bin, env: env.env } : null;+}++// Fails with an actionable message before any download is attempted. Not+// found is the "not installed" case; a non-zero status means the binary is+// present but broken.+async function requireYtDlp(): Promise<{ bin: string; env: HostEnv["env"] }> {+ const resolved = await resolveYtDlp();+ if (!resolved) {+ 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.",+ );+ }+ const probe = spawnSync(resolved.bin, ["--version"], { encoding: "utf8", env: resolved.env });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 new DapiError("unsupported", `yt-dlp is not runnable at ${resolved.bin}. Install it, or point YT_DLP_PATH at a working binary.`);}throw probe.error;}if (probe.status !== 0) {throw new DapiError("unsupported", probe.stderr?.trim() || "yt-dlp is present but not runnable.");}+ return resolved;}// 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();+export const fetchVideo: MainHandler<"fetch"> = async ({ url, output, format, audio, raw }, ctx) => {+ const { bin, env } = await requireYtDlp();const args = ["--quiet", "--no-warnings", "--print", "after_move:filepath"];if (output) args.push("-o", output);@@ -51,7 +74,7 @@ export const fetchVideo: MainHandler<"fetch"> = ({ url, output, format, audio, rargs.push(url);return new Promise((resolve, reject) => {- const child = spawn(BIN, args, { stdio: ["ignore", "pipe", "pipe"] });+ const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"], env });let out = "";child.stdout.setEncoding("utf8");child.stdout.on("data", (chunk) => (out += chunk));diff --git a/apps/desktop/src/dapi/present.test.ts b/apps/desktop/src/dapi/present.test.tsindex a090d642..d11113e3 100644--- a/apps/desktop/src/dapi/present.test.ts+++ b/apps/desktop/src/dapi/present.test.ts@@ -2,9 +2,9 @@* 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 { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";import { tmpdir } from "node:os";-import { join } from "node:path";+import { basename, dirname, join } from "node:path";import { afterAll, describe, expect, it } from "vitest";import { present, toCallToolResult } from "./present";@@ -37,6 +37,21 @@ describe("present", () => {expect(presented.output).toEqual({ path: file, silences: [{ start: 0, end: 1 }] });});+ it("writes a preview or transcript into an output that names an existing directory", async () => {+ const out = join(dir, "into");+ mkdirSync(out, { recursive: true });+ const preview = await present("media_waveform", { path: "/c.mp4", output: out }, { png: png(7), silences: [] });+ const previewPath = (preview.output as { path: string }).path;+ expect(dirname(previewPath)).toBe(out);+ expect(basename(previewPath)).toMatch(/^dapi-waveform-.*\.png$/);+ expect(readFileSync(previewPath)).toEqual(Buffer.from(png(7)));++ const transcript = await present("media_transcribe", { path: "/c.mp4", output: out }, { segments: [] });+ const transcriptPath = (transcript.output as { path: string }).path;+ expect(transcriptPath).toMatch(/dapi-transcript-.*\.json$/);+ expect(JSON.parse(readFileSync(transcriptPath, "utf8"))).toEqual({ segments: [] });+ });+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 });diff --git a/apps/desktop/src/dapi/present.ts b/apps/desktop/src/dapi/present.tsindex 0bdfc957..874c29e7 100644--- a/apps/desktop/src/dapi/present.ts+++ b/apps/desktop/src/dapi/present.ts@@ -2,8 +2,8 @@* 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 } from "node:fs";-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";+import { existsSync } from "node:fs";+import { mkdir, mkdtemp, stat, writeFile } from "node:fs/promises";import { tmpdir } from "node:os";import { dirname, join } from "node:path";import { randomUUID } from "node:crypto";@@ -58,14 +58,26 @@ async function presentImages(images: TimecodedImage[], output: string | undefinereturn { output: { images: refs }, images: written };}+/**+ * Where a single-file tool writes: `output` when given, a fresh name under+ * the temp dir otherwise. An `output` that names an existing directory gets+ * the fresh name inside it rather than an EISDIR from writeFile.+ */+async function singleFilePath(output: string | undefined, name: string): Promise<string> {+ if (output === undefined) return join(tmpdir(), name);+ const existing = await stat(output).catch(() => null);+ if (existing?.isDirectory()) return join(output, name);+ await mkdir(dirname(output), { recursive: true });+ return output;+}+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 });+ const path = await singleFilePath(output, `dapi-${kind}-${randomUUID()}.png`);await writeFile(path, png);return { output: { path, ...rest }, images: [{ path, png }] };}@@ -83,8 +95,7 @@ async function presentScreenshot(result: ToolResult<"screenshot">, output: strin}async function presentTranscript(transcript: ToolResult<"media_transcribe">, output: string | undefined): Promise<Presented> {- const path = output ?? join(tmpdir(), `dapi-transcript-${randomUUID()}.json`);- await mkdir(dirname(path), { recursive: true });+ const path = await singleFilePath(output, `dapi-transcript-${randomUUID()}.json`);await writeFile(path, JSON.stringify(transcript, null, 2));const words = transcript.segments.reduce((sum, segment) => sum + segment.words.length, 0);const presented: ToolOutput<"media_transcribe"> = { path, segments: transcript.segments.length, words };diff --git a/apps/desktop/src/dapi/server.ts b/apps/desktop/src/dapi/server.tsindex efa032f4..386bd251 100644--- a/apps/desktop/src/dapi/server.ts+++ b/apps/desktop/src/dapi/server.ts@@ -7,10 +7,10 @@ import { MCP_HOST, MCP_PATH, MCP_PORT, tools } from "@diffusionstudio/dapi";import { mainHandlers } from "./handlers";import { DapiHttpServer } from "./http";import { instructions } from "./docs";-import { present, toCallToolResult, toErrorResult } from "./present";import { RendererCalls } from "./renderer-calls";+import { serveCatalog } from "./tools-session";-import type { GenericTool, LogEntry, ToolName } from "@diffusionstudio/dapi";+import type { LogEntry } from "@diffusionstudio/dapi";import type { MainContext, MainToolName } from "./handler";/**@@ -93,26 +93,12 @@ export class DapiServer {// `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);- 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);- }- },+ serveCatalog(session, (tool, args, signal) =>+ tool.environment === "main" ?+ this.runInMain(tool.name as MainToolName, args, signal)+ : this.renderer.call(tool.name, args, signal),);+ return session;}private runInMain(name: MainToolName, args: unknown, signal: AbortSignal): Promise<unknown> {diff --git a/apps/desktop/src/dapi/tools-session.test.ts b/apps/desktop/src/dapi/tools-session.test.tsnew file mode 100644index 00000000..fd7abba5--- /dev/null+++ b/apps/desktop/src/dapi/tools-session.test.ts@@ -0,0 +1,67 @@+/* 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 { afterAll, beforeAll, describe, expect, it } from "vitest";+import { Client } from "@modelcontextprotocol/sdk/client/index.js";+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";+import { JSON_SCHEMA_DIALECT, tools } from "@diffusionstudio/dapi";+import { serveCatalog } from "./tools-session";++let client: Client;+const calls: Array<{ name: string; args: unknown }> = [];++beforeAll(async () => {+ const session = new McpServer({ name: "test", version: "0.0.0" });+ serveCatalog(session, async (tool, args) => {+ calls.push({ name: tool.name, args });+ switch (tool.name) {+ case "whoami":+ return { user: null };+ case "check":+ throw new Error("No project open — run open first");+ default:+ return {};+ }+ });+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();+ await session.connect(serverTransport);+ client = new Client({ name: "test-client", version: "0.0.0" });+ await client.connect(clientTransport);+});++afterAll(() => client.close());++describe("serveCatalog", () => {+ it("lists every tool with its schemas in JSON Schema 2020-12, the dialect clients validate", async () => {+ const listed = (await client.listTools()).tools;+ expect(listed.map((tool) => tool.name)).toEqual(tools.map((tool) => tool.name));+ for (const tool of listed) {+ expect(tool.inputSchema.$schema, `${tool.name} input`).toBe(JSON_SCHEMA_DIALECT);+ expect(tool.outputSchema?.$schema, `${tool.name} output`).toBe(JSON_SCHEMA_DIALECT);+ expect(tool.description, tool.name).toBeTruthy();+ }+ const fonts = listed.find((tool) => tool.name === "fonts")!;+ expect(fonts.inputSchema.properties).toHaveProperty("family");+ expect(fonts.outputSchema?.properties).toHaveProperty("families");+ });++ it("validates arguments before the tool runs, and runs it with the parsed ones", async () => {+ const before = calls.length;+ const bad = await client.callTool({ name: "fonts", arguments: { limit: 0 } });+ expect(bad.isError).toBe(true);+ expect(JSON.stringify(bad.content)).toContain("limit");+ expect(calls.length).toBe(before);++ const result = await client.callTool({ name: "whoami", arguments: {} });+ expect(result.structuredContent).toEqual({ user: null });+ expect(calls.at(-1)).toEqual({ name: "whoami", args: {} });+ });++ it("returns a handler's failure as a readable error result, not a protocol error", async () => {+ const result = await client.callTool({ name: "check", arguments: { id: "intro" } });+ expect(result.isError).toBe(true);+ expect(result.content).toEqual([{ type: "text", text: "No project open — run open first" }]);+ });+});diff --git a/apps/desktop/src/dapi/tools-session.ts b/apps/desktop/src/dapi/tools-session.tsnew file mode 100644index 00000000..24dd54af--- /dev/null+++ b/apps/desktop/src/dapi/tools-session.ts@@ -0,0 +1,44 @@+/* 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 { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";+import { toolJsonSchemas, tools } from "@diffusionstudio/dapi";+import { present, toCallToolResult, toErrorResult } from "./present";++import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";+import type { GenericTool, ToolName } from "@diffusionstudio/dapi";++/** Runs one tool wherever it lives (main or renderer) and returns the handler's raw result. */+export type ToolRunner = (tool: GenericTool, args: unknown, signal: AbortSignal) => Promise<unknown>;++/**+ * Serves the whole catalog on an MCP session: every tool registered with the+ * SDK, which validates arguments against the zod schema and structured+ * content against the output schema, and a `tools/list` of our own.+ *+ * The list is ours because the SDK's converts the zod schemas to JSON Schema+ * draft-07, and the validators clients run reject that dialect — Claude Code+ * fails every call on the `outputSchema` before it reaches the app. What+ * clients get instead is the same schema in 2020-12 (see `toolJsonSchemas`);+ * `tools/call` and the validation behind it stay the SDK's.+ */+export function serveCatalog(session: McpServer, run: ToolRunner): void {+ for (const tool of tools) {+ session.registerTool(+ tool.name,+ { title: tool.title, description: tool.description, inputSchema: tool.input, outputSchema: tool.output },+ async (args, extra) => {+ try {+ const result = await run(tool, args, extra.signal);+ return toCallToolResult(await present(tool.name as ToolName, args, result));+ } catch (error) {+ return toErrorResult(error);+ }+ },+ );+ }+ session.server.setRequestHandler(ListToolsRequestSchema, () => ({+ tools: tools.map((tool) => ({ name: tool.name, title: tool.title, description: tool.description, ...toolJsonSchemas(tool) })),+ }));+}diff --git a/apps/desktop/src/projects.init.test.ts b/apps/desktop/src/projects.init.test.tsnew file mode 100644index 00000000..3e4eca91--- /dev/null+++ b/apps/desktop/src/projects.init.test.ts@@ -0,0 +1,86 @@+/* 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/. */++// What `open` writes into a folder, and what it refuses: the promise the+// tool reference makes is that a folder opened from anywhere on disk stays+// the user's, gaining an entry and the record and nothing else.++import { tmpdir } from "node:os";+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++vi.mock("electron", () => ({+ app: { isPackaged: false, getPath: () => tmpdir() },+ dialog: {},+ shell: {},+ ipcMain: { on: () => { } },+}));++const { initProject } = await import("./projects");++let root: string;++beforeEach(async () => {+ root = await mkdtemp(join(tmpdir(), "init-test-"));+});++afterEach(async () => {+ await rm(root, { recursive: true, force: true });+});++describe("initProject", () => {+ it("turns a missing folder into a project with an entry and a record, nothing else", async () => {+ const dir = join(root, "fresh");+ const project = await initProject(null, dir);+ expect(project.id).toMatch(/^[\w-]{21}$/);+ expect(project.name).toBe("fresh");+ expect(project.entry).toBe("index.tsx");+ expect((await readdir(dir)).sort()).toEqual(["index.tsx", "package.json"]);+ const pkg = JSON.parse(await readFile(join(dir, "package.json"), "utf8"));+ expect(pkg).toMatchObject({ projectId: project.id, displayName: "fresh", main: "index.tsx" });+ });++ it("leaves a folder that is already a project untouched", async () => {+ const dir = join(root, "kept");+ await initProject(null, dir);+ const before = await readFile(join(dir, "package.json"), "utf8");+ await writeFile(join(dir, "notes.txt"), "mine");+ const again = await initProject(null, dir);+ expect(again.id).toBe(JSON.parse(before).projectId);+ expect(await readFile(join(dir, "package.json"), "utf8")).toBe(before);+ expect((await readdir(dir)).sort()).toEqual(["index.tsx", "notes.txt", "package.json"]);+ });++ it("keeps what a package.json already says and only adds the record fields", async () => {+ const dir = join(root, "partial");+ await mkdir(dir);+ await writeFile(join(dir, "main.tsx"), "export default () => <stage />;\n");+ await writeFile(join(dir, "package.json"), JSON.stringify({ name: "partial", main: "main.tsx", scripts: { build: "x" } }, null, 2) + "\n");+ const project = await initProject(null, dir);+ const pkg = JSON.parse(await readFile(join(dir, "package.json"), "utf8"));+ expect(pkg.name).toBe("partial");+ expect(pkg.main).toBe("main.tsx");+ expect(pkg.scripts).toEqual({ build: "x" });+ expect(pkg.projectId).toBe(project.id);+ expect((await readdir(dir)).sort()).toEqual(["main.tsx", "package.json"]);+ });++ it("leaves a JavaScript project entirely alone", async () => {+ const dir = join(root, "js");+ await mkdir(dir);+ await writeFile(join(dir, "index.jsx"), "export default () => null;\n");+ const project = await initProject(null, dir);+ expect(project.id).toBe("");+ expect(await readdir(dir)).toEqual(["index.jsx"]);+ });++ it("refuses a relative path and a path that is a file", async () => {+ await expect(initProject(null, "relative/project")).rejects.toThrow(/absolute path/);+ const file = join(root, "a-file");+ await writeFile(file, "");+ await expect(initProject(null, file)).rejects.toThrow(/not a folder/);+ expect(await readFile(file, "utf8")).toBe("");+ });+});diff --git a/apps/desktop/src/projects.ts b/apps/desktop/src/projects.tsindex 8e073f75..0a7bade3 100644--- a/apps/desktop/src/projects.ts+++ b/apps/desktop/src/projects.ts@@ -705,43 +705,59 @@ async function ensurePackage(dir: string, name: string, displayName: string, ent* from @diffusionstudio/jsx (jsxImportSource), installed by the project.*/export async function scaffold(dir: string, displayName = basename(dir)): Promise<void> {- const name = basename(dir);- let entry = await findEntry(dir);+ const entry = await ensureRecord(dir, displayName);// JavaScript projects are left alone.- if (entry && !/\.tsx?$/.test(entry)) return;-- if (!entry) {- await writeIfMissing(dir, "index.tsx", STARTER);- entry = "index.tsx";- }- await ensurePackage(dir, name, displayName, entry);+ if (!entry) return;await writeIfMissing(dir, "tsconfig.json", TSCONFIG);await writeIfMissing(dir, ".gitignore", GITIGNORE);await writeIfMissing(dir, "README.md", readme(displayName));-if (!(await exists(join(dir, MANIFEST_FILE)))) {await writeManifest(dir, EMPTY_MANIFEST);}}+/**+ * The part of the scaffold every project needs: an entry file, and the+ * package.json record (`projectId`, `displayName`, `main`) the app remembers+ * the folder by. Nothing a folder already has is touched. Returns the entry,+ * or undefined for a JavaScript project, which is left entirely alone.+ */+async function ensureRecord(dir: string, displayName = basename(dir)): Promise<string | undefined> {+ let entry = await findEntry(dir);+ if (entry && !/\.tsx?$/.test(entry)) return undefined;+ if (!entry) {+ await writeIfMissing(dir, "index.tsx", STARTER);+ entry = "index.tsx";+ }+ await ensurePackage(dir, basename(dir), displayName, entry);+ return entry;+}+/*** Makes `dir` openable as a project, writing as little as that takes: the- * folder if it does not exist, and — when nothing in it can be an entry — an- * `index.tsx` holding an empty stage. Nothing else; a project is its JSX, and- * the record, manifest, and the rest of the scaffold appear lazily, each when- * something first needs it. A folder that is already a project comes back- * untouched. How `dapi open <path>` opens a folder anywhere on disk.+ * folder if it does not exist, an `index.tsx` holding an empty stage when+ * nothing in it can be an entry, and the package.json record the app+ * remembers the folder by. Nothing else — no tsconfig, README, or+ * .gitignore, which come with a project created from the dashboard (see+ * `scaffold`); a folder opened from anywhere on disk stays the user's. A+ * folder that is already a project comes back untouched. How+ * `dapi open <path>` opens a folder.*/export async function initProject(window: BrowserWindow | null, dir: string): Promise<ProjectInfo> {+ if (!isAbsolute(dir)) {+ throw new Error(`The project folder must be an absolute path (got "${dir}").`);+ }+ const existing = await stat(dir).catch(() => null);+ if (existing && !existing.isDirectory()) {+ throw new Error(`${dir} exists but is not a folder.`);+ }if (!(await confirmCloudLocation(window, dir, "Cancel"))) {throw new Error("Cancelled: that folder is synced.");}await mkdir(dir, { recursive: true });- if (!(await findEntry(dir))) {- await writeIfMissing(dir, "index.tsx", STARTER);- }+ await ensureRecord(dir);const project = await describe(dir);if (!project) throw new Error(noEntryError());return project;@@ -905,8 +921,9 @@ export async function compileProject(dir: string): Promise<CompileResult> {const entry = await findEntry(dir);if (!entry) return { ok: false, error: noEntryError() };- // Fills in package.json/tsconfig for folders that predate the record.- await scaffold(dir);+ // Fills in the package.json record for folders that predate it; the rest+ // of the scaffold is the dashboard's (see `initProject`).+ await ensureRecord(dir);// Names every element before it is numbered, so the ids this compile hands// the canvas are durable ones. A fully keyed project is not written to.diff --git a/apps/web/src/dapi/handlers/export.ts b/apps/web/src/dapi/handlers/export.tsindex fc688cc8..aa325624 100644--- a/apps/web/src/dapi/handlers/export.ts+++ b/apps/web/src/dapi/handlers/export.ts@@ -5,6 +5,7 @@import { canEncodeVideo } from "mediabunny";import { computeOutputSize } from "@diffusionstudio/encoder";import { Computed, FrameRate, Workarea } from "@diffusionstudio/runtime";+import { isAbsoluteSource } from "@diffusionstudio/assets";import { DapiError } from "@diffusionstudio/dapi";import { renderOverlay, renderScene } from "@/context/render";@@ -16,6 +17,7 @@ import { mainBridge } from "@/lib/ipc";import { MAIN_CHANNELS } from "@desktop/main-channels";import { requireScene } from "../lib/scene";+import type { AudioCodec, OutputFormat, VideoCodec } from "mediabunny";import type { ExportSettings } from "@diffusionstudio/dapi";import type { ContainerFormat, ExportConfig } from "@/engine/project-config";import type { ToolHandler } from "../handler";@@ -29,6 +31,9 @@ import type { ToolHandler } from "../handler";function resolveFormat(path: string | undefined, config: ExportConfig): ContainerFormat {const supported = VIDEO_FORMAT_OPTIONS.map((format) => `.${format}`).join(", ");if (path !== undefined) {+ if (!isAbsoluteSource(path)) {+ throw new DapiError("invalid-input", `The output path must be absolute (got "${path}").`);+ }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}.`);@@ -45,6 +50,47 @@ function resolveFormat(path: string | undefined, config: ExportConfig): Containereturn format;}+/** The container's format class, imported on demand: the muxers are not part of the main bundle. */+async function outputFormat(format: ContainerFormat): Promise<OutputFormat> {+ const { MovOutputFormat, Mp4OutputFormat, OggOutputFormat, WebMOutputFormat } = await import("mediabunny");+ switch (format) {+ case "webm":+ return new WebMOutputFormat();+ case "ogg":+ return new OggOutputFormat();+ case "mov":+ return new MovOutputFormat();+ default:+ return new Mp4OutputFormat();+ }+}++/** What each container is given when the entry's codec cannot go in it. */+const FALLBACK_VIDEO: Record<ContainerFormat, VideoCodec> = { mp4: "avc", mov: "avc", webm: "vp9", ogg: "vp9" };+const FALLBACK_AUDIO: Record<ContainerFormat, AudioCodec> = { mp4: "aac", mov: "aac", webm: "opus", ogg: "opus" };++/**+ * The entry's codecs, reconciled with the container the extension picked: an+ * entry written for MP4 names AAC, which WebM and Ogg cannot hold, so an+ * export to `.webm` would fail on the codec rather than produce the file the+ * name asks for. A codec the container cannot contain is swapped for the+ * container's own (Opus for WebM and Ogg audio, VP9 for WebM video); the+ * echoed config carries the swap. Codecs the container can hold stay as+ * written, including ones the entry leaves to the encoder's default.+ */+async function reconcileCodecs(settings: ExportConfig, format: ContainerFormat): Promise<ExportConfig> {+ const container = await outputFormat(format);+ const video = settings.video?.codec;+ const audio = settings.audio?.codec;+ const videoCodec = video && !container.getSupportedVideoCodecs().includes(video) ? FALLBACK_VIDEO[format] : video;+ const audioCodec = audio && !container.getSupportedAudioCodecs().includes(audio) ? FALLBACK_AUDIO[format] : audio;+ return {+ ...settings,+ ...(videoCodec !== video ? { video: { ...settings.video, codec: videoCodec } } : {}),+ ...(audioCodec !== audio ? { audio: { ...settings.audio, codec: audioCodec } } : {}),+ };+}+export const exportScene: ToolHandler<"export"> = async ({ id, path }, ctx) => {const { world, project, engine } = ctx.requireSession();const scene = requireScene(world, id, "export");@@ -54,9 +100,8 @@ export const exportScene: ToolHandler<"export"> = async ({ id, path }, ctx) => {// 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 format = resolveFormat(path, { format: base.format, video: base.video, audio: base.audio });+ const settings = await reconcileCodecs({ format, video: base.video, audio: base.audio }, format);const key = sceneConfigKey(scene) ?? id;const target = path ?? `${project.dir()}/exports/${key.replace(/[^\w.-]+/g, "-")}.${format}`;diff --git a/apps/web/src/dapi/handlers/open.ts b/apps/web/src/dapi/handlers/open.tsindex f4c0dcfb..ea5a9ac6 100644--- a/apps/web/src/dapi/handlers/open.ts+++ b/apps/web/src/dapi/handlers/open.ts@@ -2,6 +2,17 @@* 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 { isAbsoluteSource } from "@diffusionstudio/assets";+import { DapiError } from "@diffusionstudio/dapi";+import type { ToolHandler } from "../handler";-export const open: ToolHandler<"open"> = ({ dir }, ctx) => ctx.app.openProject(dir);+// The app has no working directory a relative path could mean anything+// against (the CLI resolves one before calling), so it is refused here+// rather than surfacing as an ENOENT from mkdir.+export const open: ToolHandler<"open"> = ({ dir }, ctx) => {+ if (!isAbsoluteSource(dir)) {+ throw new DapiError("invalid-input", `The project folder must be an absolute path (got "${dir}").`);+ }+ return ctx.app.openProject(dir);+};diff --git a/apps/web/src/dapi/handlers/whoami.ts b/apps/web/src/dapi/handlers/whoami.tsindex a23daaa7..670e9cc1 100644--- a/apps/web/src/dapi/handlers/whoami.ts+++ b/apps/web/src/dapi/handlers/whoami.ts@@ -2,6 +2,10 @@* 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 { toolByName } from "@diffusionstudio/dapi";+import type { ToolHandler } from "../handler";-export const whoami: ToolHandler<"whoami"> = async (_, ctx) => ({ user: ctx.app.user() });+// The auth record carries identities, provider metadata and avatar URLs;+// the output schema names the id and the email, and parsing strips the rest.+export const whoami: ToolHandler<"whoami"> = async (_, ctx) => toolByName("whoami").output.parse({ user: ctx.app.user() });diff --git a/docs/reference/tools/README.md b/docs/reference/tools/README.mdindex dc2ffd9f..055898f4 100644--- a/docs/reference/tools/README.md+++ b/docs/reference/tools/README.md@@ -2,7 +2,7 @@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). A connected agent gets every tool in `tools/list`, with the descriptions on these pages, and instructions that give the path of these docs in the installed app. A client that can only spawn a stdio server can bridge to the URL with a generic proxy such as `mcp-remote`.+- **MCP.** The running app serves an MCP server at `http://127.0.0.1:3274/mcp` (Streamable HTTP). A connected agent gets every tool in `tools/list`, with the descriptions on these pages and its input and output as JSON Schema 2020-12, and instructions that give the path of these docs in the installed app. A client that can only spawn a stdio server can bridge to the URL with a generic proxy such as `mcp-remote`.- **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`.@@ -64,7 +64,7 @@ How the surface is divided:```tsAsset = { id: string; path: string; type: string } // asset ids are content hashes; `path` is the library pathTime = 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+NodeId = string // an element's `id` in the project's JSX; `file:id` (`intro.tsx:hero`, the file name with its extension) when two files collide```Time inputs take the `Time` format unless noted otherwise.diff --git a/docs/reference/tools/capture.md b/docs/reference/tools/capture.mdindex 3546987b..03fce15d 100644--- a/docs/reference/tools/capture.md+++ b/docs/reference/tools/capture.md@@ -19,7 +19,7 @@ Render single frames of a scene to PNGs — each frame is the frame an export of## 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.+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. A position past the workarea's end is not an error: the scene keeps playing past it, and the frame is what plays there — just not one an export would include.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).@@ -31,7 +31,7 @@ Cell labels, the `timecode` field, and the filenames all use the same stamp, whi## 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:+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`. A sheet carries a 4px margin around the grid (so a single 1080p cell makes a 1928x1088 image) and an 8px gutter between cells. For a 16:9 scene the cell sizes are:| Positions | Grid | Per-frame ||---|---|---|diff --git a/docs/reference/tools/context.md b/docs/reference/tools/context.mdindex e73e5c42..becabb7f 100644--- a/docs/reference/tools/context.md+++ b/docs/reference/tools/context.md@@ -1,6 +1,6 @@# 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.+Report the current app context: the folder new projects are created in (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.| | || --- | --- |diff --git a/docs/reference/tools/export.md b/docs/reference/tools/export.mdindex 84f5be57..4c7bc18d 100644--- a/docs/reference/tools/export.md+++ b/docs/reference/tools/export.md@@ -1,6 +1,6 @@# 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.+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; a codec the container cannot hold is swapped for the container's own (Opus for WebM and Ogg audio, VP9 for WebM video). 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.| | || --- | --- |@@ -26,7 +26,9 @@ Scenes only: a scene is the unit an export renders, and the error names the scen## 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.+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. The path must be absolute over MCP; from a shell, a relative path resolves against the working directory.++A container decides which codecs it can hold, and an entry is usually written for one: the default entry names AAC audio, which WebM and Ogg cannot contain. Rather than fail the export on the codec, a codec the chosen container cannot hold is swapped for the container's own — Opus for WebM and Ogg audio, VP9 for WebM video, AVC and AAC the other way round — and the echoed `config` says which codecs the file was actually made with. Codecs the container can hold stay as the entry wrote them, so a `.mp4` export of a VP9/Opus entry is exactly that.## Settings@@ -82,4 +84,4 @@ The echoed `config` is the confirmation of what a `package.json` edit actually d## 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.+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 is not absolute or 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/docs/reference/tools/fetch.md b/docs/reference/tools/fetch.mdindex e35544c0..99c6753f 100644--- a/docs/reference/tools/fetch.md+++ b/docs/reference/tools/fetch.md@@ -17,7 +17,7 @@ Download a video with yt-dlp (installed separately). Writes files to disk only a| `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.+[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 login shell's `PATH` (read once, so a Dock-launched app finds a Homebrew or pipx install the way a terminal does), then in the usual install folders (`~/.local/bin`, `/opt/homebrew/bin`, `/usr/local/bin`), or at `YT_DLP_PATH` when set; it runs with that same `PATH`, so it finds `ffmpeg` for merging and extraction the same way. 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)).diff --git a/docs/reference/tools/media/filmstrip.md b/docs/reference/tools/media/filmstrip.mdindex a094ef54..e6e9920c 100644--- a/docs/reference/tools/media/filmstrip.md+++ b/docs/reference/tools/media/filmstrip.md@@ -18,9 +18,9 @@ Render a grid of thumbnails sampled across the timeline to a PNG (local render,| `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.+Frames are sampled at even intervals across the window. An `end` past the asset's duration is clamped to it; a `start` at or past the end is an error, since the window would be empty. 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.+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; an `output` naming an existing directory gets that fresh file inside it.## Output@@ -34,4 +34,4 @@ One JSON object, the absolute path to the written PNG. Over MCP the image also a## 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.+Fails when the path can't be resolved, the asset isn't a video, the window is empty (`start` at or past the asset's end) or crosses (`start` >= `end`), `scale` isn't a positive number, or the PNG can't be written.diff --git a/docs/reference/tools/media/grab.md b/docs/reference/tools/media/grab.mdindex a76e1caf..1698de54 100644--- a/docs/reference/tools/media/grab.md+++ b/docs/reference/tools/media/grab.md@@ -18,7 +18,7 @@ Decode frames of a video file and write them as PNGs (local render, no credits).| `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 |+| `quality` | `"small" \| "medium" \| "large" \| "fullres"` | `-q, --quality <preset>` | frame resolution as a pixel budget, aspect ratio kept and never enlarged past the source: small (384² pixels, 512x288 for 16:9), medium (768², 1024x576), large (1536², 2048x1152), 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) |@@ -32,7 +32,9 @@ Three ways to say which frames, mutually exclusive:- `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.+`start` and `end` only apply with `count` or `auto`. An `end` past the asset's duration is clamped to it; a `start` at or past the end is an error, since the window would be empty. 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.++`quality` is a pixel budget rather than a box: a frame is scaled down, aspect ratio kept, until it holds no more pixels than the preset's square (`small` is 384², so a 16:9 frame becomes 512x288; `medium` 768² gives 1024x576; `large` 1536² gives 2048x1152), and never enlarged, so `large` on 1080p footage is the native 1920x1080.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.@@ -63,4 +65,4 @@ A sheet's timecode is the span it covers; a frame's is its own. Sheets come in t## 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.+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 (`start` at or past the asset's end) 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/docs/reference/tools/media/probe.md b/docs/reference/tools/media/probe.mdindex 55559028..032a7998 100644--- a/docs/reference/tools/media/probe.md+++ b/docs/reference/tools/media/probe.md@@ -34,4 +34,4 @@ One JSON object. The shape is **not yet stable**: it reports whatever mediabunny## Errors-Fails when the path can't be resolved.+Fails when the path can't be resolved: a file that is not there (`No such file`), a library path the project has no asset at, or a relative path (only library paths are relative; a file on disk is named by its absolute path).diff --git a/docs/reference/tools/media/transcribe.md b/docs/reference/tools/media/transcribe.mdindex 61d244d4..ec16de9d 100644--- a/docs/reference/tools/media/transcribe.md+++ b/docs/reference/tools/media/transcribe.md@@ -14,7 +14,7 @@ Transcribe the speech in a video or audio file and write the timed transcript to| `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) || `output` | `string` | `-o, --output <path>` | absolute path to write the transcript JSON to (default: a fresh file under the system temp dir) |-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). Every call writes the file again, so a cached transcript returns at once.+Times are in **seconds** of source/content time. An `output` naming an existing directory gets a fresh `dapi-transcript-*.json` inside it. 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). Every call writes the file again, so a cached transcript returns at once.## Outputdiff --git a/docs/reference/tools/media/waveform.md b/docs/reference/tools/media/waveform.mdindex 9e6fe0be..27b612ef 100644--- a/docs/reference/tools/media/waveform.md+++ b/docs/reference/tools/media/waveform.md@@ -18,9 +18,9 @@ Render the audio track of a video or audio file as a waveform PNG (local render,| `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.+Loudness over time is drawn from decoded audio peaks. An `end` past the asset's duration is clamped to it; a `start` at or past the end is an error, since the window would be empty. 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.+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; an `output` naming an existing directory gets that fresh file inside it.## Output@@ -35,4 +35,4 @@ One JSON object: the absolute path to the written PNG plus the silent stretches## 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.+Fails when the path can't be resolved, the asset has no decodable audio track, the window is empty (`start` at or past the asset's end) or crosses (`start` >= `end`), `scale` isn't a positive number, or the PNG can't be written.diff --git a/docs/reference/tools/open.md b/docs/reference/tools/open.mdindex 251687bc..fd3bb83a 100644--- a/docs/reference/tools/open.md+++ b/docs/reference/tools/open.md@@ -19,9 +19,10 @@ Open a folder as a project in the running app, creating the project files if theThe 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.+- a folder with no entry file (package.json `main`, or `index.tsx` and friends) gains an `index.tsx` holding an empty stage;+- a folder with no project record gains one in `package.json` — `projectId`, `displayName`, `main`, and the dapi commands as `scripts` — which is what the app remembers the folder by. A package.json that is already there keeps everything it has and only gains the fields it lacks.-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.+Nothing else is written — no tsconfig, README, or .gitignore. Those come with a project created from the app's dashboard; a folder opened from anywhere on disk stays the user's. A folder that is already a project is opened untouched, wherever it lives. A JavaScript project (an entry ending in `.js` or `.jsx`) is left entirely alone, record included.The app remembers the folder, so the project reopens across app relaunches and stays addressable by folder name or project id.@@ -37,7 +38,7 @@ The opened project:```ts{- id: string; // package.json `projectId`; "" until the project has a record+ id: string; // package.json `projectId`; "" only for a JavaScript project, which gets no recordname: string; // display name (falls back to the folder name)dir: string; // absolute project folder, as opened}@@ -45,5 +46,6 @@ The opened project:## Errors+- The path is not absolute (`The project folder must be an absolute path`).- 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/packages/agent-chat/package.json b/packages/agent-chat/package.jsonindex 150e8a59..3775dcf4 100644--- a/packages/agent-chat/package.json+++ b/packages/agent-chat/package.json@@ -7,7 +7,8 @@"sideEffects": false,"exports": {".": "./src/index.ts",- "./host": "./src/host/index.ts"+ "./host": "./src/host/index.ts",+ "./host/env": "./src/host/env.ts"},"scripts": {"check": "tsc --noEmit",diff --git a/packages/assets/src/library.ts b/packages/assets/src/library.tsindex da60ac36..c4211a68 100644--- a/packages/assets/src/library.ts+++ b/packages/assets/src/library.ts@@ -759,6 +759,9 @@ export class AssetLibrary {/** Describes a file or frames directory at `source`. */private async describeSource(source: string, meta: DescribeMeta): Promise<Asset> {+ // A path that is not there fails as that, not as an unsupported file+ // once the mime sniff finds nothing to read.+ if (!(await this.fs.stat(source))) throw new Error(`No such file: ${source}`);const entries = await this.fs.list(source);if (entries.length && isSequenceListing(entries.map((entry) => entry.name))) {return this.describeSequence(source, sortFrames(entries).filter((entry) => entry.kind === 'file'), meta);diff --git a/packages/dapi/src/catalog.test.ts b/packages/dapi/src/catalog.test.tsindex 3f90c21e..225146d9 100644--- a/packages/dapi/src/catalog.test.ts+++ b/packages/dapi/src/catalog.test.ts@@ -5,6 +5,7 @@import { describe, expect, it } from "vitest";import { z } from "zod";import { catalog, isToolName, toolByName } from "./catalog";+import { JSON_SCHEMA_DIALECT, toolJsonSchemas } from "./json-schema";describe("catalog", () => {it("has unique MCP-legal names", () => {@@ -34,6 +35,16 @@ describe("catalog", () => {}});+ it("publishes every schema as JSON Schema 2020-12, the dialect MCP clients validate", () => {+ for (const tool of catalog) {+ const { inputSchema, outputSchema } = toolJsonSchemas(tool);+ expect(inputSchema.$schema, `${tool.name} input`).toBe(JSON_SCHEMA_DIALECT);+ expect(outputSchema.$schema, `${tool.name} output`).toBe(JSON_SCHEMA_DIALECT);+ expect(inputSchema.type, `${tool.name} input`).toBe("object");+ expect(outputSchema.type, `${tool.name} output`).toBe("object");+ }+ });+it("looks tools up by name", () => {expect(toolByName("capture").environment).toBe("renderer");expect(toolByName("fonts").environment).toBe("main");diff --git a/packages/dapi/src/index.ts b/packages/dapi/src/index.tsindex a6c46969..29781afa 100644--- a/packages/dapi/src/index.ts+++ b/packages/dapi/src/index.ts@@ -20,6 +20,8 @@ export type { DapiErrorCode } from "./errors";export { MAX_FRAMES_PER_SHEET, Bytes } from "./schemas";export { MCP_HOST, MCP_PORT, MCP_PATH, MCP_URL } from "./mcp";+export { JSON_SCHEMA_DIALECT, toolJsonSchemas } from "./json-schema";+export type { ToolJsonSchemas } from "./json-schema";export { DAPI_WIRE } from "./ipc";export type { DapiCall, DapiCancel, DapiReply } from "./ipc";export { FRAME_CAP } from "./tools/media-grab";diff --git a/packages/dapi/src/json-schema.ts b/packages/dapi/src/json-schema.tsnew file mode 100644index 00000000..364ca277--- /dev/null+++ b/packages/dapi/src/json-schema.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 type { GenericTool } from "./tool";++/**+ * The JSON Schema dialect a tool's schemas are published in over MCP. The+ * spec recommends 2020-12, and the validators clients run (Claude Code's+ * among them) accept nothing older: a `$schema` naming draft-07 fails every+ * tool call before it reaches the app. The MCP SDK's own conversion defaults+ * to draft-07, so the server publishes these instead.+ */+export const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";++export type ToolJsonSchemas = {+ inputSchema: Record<string, unknown>;+ outputSchema: Record<string, unknown>;+};++/** A tool's input and output as JSON Schema 2020-12, the way `tools/list` reports them. */+export function toolJsonSchemas(tool: GenericTool): ToolJsonSchemas {+ return {+ inputSchema: z.toJSONSchema(tool.input, { target: "draft-2020-12", io: "input" }) as Record<string, unknown>,+ outputSchema: z.toJSONSchema(tool.output, { target: "draft-2020-12", io: "output" }) as Record<string, unknown>,+ };+}diff --git a/packages/dapi/src/schemas.ts b/packages/dapi/src/schemas.tsindex 0e52cd3d..0539d2a6 100644--- a/packages/dapi/src/schemas.ts+++ b/packages/dapi/src/schemas.ts@@ -11,12 +11,12 @@ 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");+ .describe("node id from the project's JSX, or `file:id` (`intro.tsx:hero`) 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");+ .describe("scene id from the project's JSX, or `file:id` (`intro.tsx:main`) when two files use the same id");export const AssetPath = z.string()diff --git a/packages/dapi/src/tools/export.ts b/packages/dapi/src/tools/export.tsindex 2e93ab7c..2d1b01da 100644--- a/packages/dapi/src/tools/export.ts+++ b/packages/dapi/src/tools/export.ts@@ -37,7 +37,7 @@ 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.",+ "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; a codec the container cannot hold is swapped for the container's own (Opus for WebM and Ogg audio, VP9 for WebM video). 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: zdiff --git a/packages/dapi/src/tools/media-grab.ts b/packages/dapi/src/tools/media-grab.tsindex 5a4ab3d0..fb164570 100644--- a/packages/dapi/src/tools/media-grab.ts+++ b/packages/dapi/src/tools/media-grab.ts@@ -40,7 +40,7 @@ export const mediaGrab = defineTool({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",+ "frame resolution as a pixel budget, aspect ratio kept and never enlarged past the source: small (384² pixels, 512x288 for 16:9), medium (768², 1024x576), large (1536², 2048x1152), or fullres (native); default: as large as the sheet cell allows, or small with separate: true",),...sheetFields,uncapped: z