wizards 0.1.9

package/apps/runtime/dist/mcp/bridge.js

@@ -0,0 +1,59 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+import { createMcpHandler, fromJsonSchema, McpServer, } from "@modelcontextprotocol/server";
+import { env } from "../env.js";
+const bridges = new Map();
+const textOf = (value) => typeof value === "string" ? value : JSON.stringify(value ?? null);
+/** A tool's result as MCP content: text, or the blocks its `toModelOutput` shapes (text and images). */
+function contentOf(tool, output) {
+    const shaped = tool.toModelOutput?.(output);
+    if (shaped?.type === "content") {
+        return {
+            content: shaped.value.map((part) => part.type === "image-data"
+                ? { type: "image", data: part.data ?? "", mimeType: part.mediaType ?? "image/png" }
+                : { type: "text", text: part.text ?? textOf(part) }),
+        };
+    }
+    return { content: [{ type: "text", text: textOf(shaped ? shaped.value : output) }] };
+}
+export function openBridge(tools) {
+    const token = randomBytes(24).toString("base64url");
+    // The client's requests arrive on their own; the tools run as the call that opened the bridge —
+    // in its tenant, as its person.
+    const inCall = AsyncLocalStorage.snapshot();
+    const handler = createMcpHandler(() => {
+        const server = new McpServer({ name: "step", version: "0.1.0" }, { capabilities: { tools: {} } });
+        for (const tool of tools) {
+            server.registerTool(tool.name, {
+                description: tool.description,
+                inputSchema: fromJsonSchema(tool.inputSchema),
+            }, (async (args) => {
+                try {
+                    return contentOf(tool, await inCall(() => tool.execute(args)));
+                }
+                catch (err) {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: err?.message ?? String(err) }],
+                    };
+                }
+            }));
+        }
+        return server;
+    }, { legacy: "stateless" });
+    bridges.set(token, handler);
+    return {
+        url: `http://127.0.0.1:${env.port}/api/mcp/bridge/${token}`,
+        close: () => {
+            bridges.delete(token);
+        },
+    };
+}
+/** Answers an MCP request of an open bridge; a closed or unknown one is not found. */
+export function bridgeRequest(token, request) {
+    const handler = bridges.get(token);
+    if (!handler) {
+        return Promise.resolve(new Response("not found", { status: 404 }));
+    }
+    return handler.fetch(request);
+}

package/apps/runtime/dist/mcp/handler.js

@@ -0,0 +1,42 @@
+import { createMcpHandler, McpServer, originValidationResponse, } from "@modelcontextprotocol/server";
+import { withTenant } from "../db/client.js";
+import { env } from "../env.js";
+import { tenantStatus } from "../tenants/control.js";
+import { authenticate, principalOf } from "./auth.js";
+import { registerPrompts, registerTools } from "./tools.js";
+const INSTRUCTIONS = `engenty wizards: build page-by-page AI wizards that people open on a shared link.
+Start with get_authoring_guide (schema + design rules), look at a close starter with get_starter, then create_wizard and refine with edit_wizard until "issues" is empty.
+Check it with start_test_run + get_test_run (waitSeconds) — test runs spend the admin's credits.
+Publish only when the admin asks. Hand the admin the studioUrl: the studio shows the wizard as a diagram.`;
+/** A wizard definition is a few KB; this leaves room and refuses anything far beyond it. */
+const MAX_BODY_BYTES = 300_000;
+/**
+ * Streamable HTTP MCP endpoint, stateless: every request authenticates — with an access token of
+ * the Manage-App or an API key — and gets a fresh server whose tools act as that admin, in the
+ * tenant the token or key names.
+ */
+export function mcpHandler() {
+    const allowedHosts = [new URL(env.appUrl).hostname, "localhost", "127.0.0.1"];
+    const handler = createMcpHandler((ctx) => {
+        const server = new McpServer({ name: "engenty-wizards", version: "0.1.0" }, { instructions: INSTRUCTIONS, capabilities: { tools: {}, prompts: {} } });
+        const who = principalOf(ctx.authInfo);
+        registerTools(server, who);
+        registerPrompts(server);
+        return server;
+    }, { legacy: "stateless", maxRequestBodySize: MAX_BODY_BYTES });
+    return async (request) => {
+        const rejected = originValidationResponse(request, allowedHosts);
+        if (rejected) {
+            return rejected;
+        }
+        const authInfo = await authenticate(request);
+        if (authInfo instanceof Response) {
+            return authInfo;
+        }
+        const who = principalOf(authInfo);
+        if ((await tenantStatus(who.tenantId)) === "suspended") {
+            return new Response(JSON.stringify({ error: "tenant_suspended" }), { status: 403 });
+        }
+        return withTenant(who.tenantId, () => handler.fetch(request, { authInfo }));
+    };
+}

package/apps/runtime/dist/mcp/scopes.js

@@ -0,0 +1,5 @@
+import { env } from "../env.js";
+/** What an MCP client may do; the Manage-App's consent page lists them, tools register only when granted. */
+export const SCOPES = ["wizards:read", "wizards:write", "wizards:publish", "runs:test"];
+/** The protected resource OAuth tokens are bound to (RFC 8707 / RFC 9728). */
+export const MCP_RESOURCE = `${env.appUrl}/api/mcp`;

package/apps/runtime/dist/mcp/tools.js

@@ -0,0 +1,401 @@
+import { z } from "zod";
+import { authoringGuide } from "../authoring/guide.js";
+import { wizardOpSchema } from "../authoring/ops.js";
+import { importFromRegistry, listConnectors, searchRegistry } from "../connectors/external.js";
+import { RunConflict } from "../engine/runner.js";
+import { ServiceError } from "../services/errors.js";
+import { deleteFile, listFiles, readFileText, writeFile } from "../services/files.js";
+import { marketplaceWizard, searchMarketplace } from "../services/marketplace.js";
+import { defaultProject, listProjects, ownedProject } from "../services/projects.js";
+import { startTestRun, testRunReport } from "../services/runs.js";
+import { checkDraftWidget } from "../services/widgets.js";
+import { createWizard, editWizard, listWizards, ownedWizard, parseDraft, publishWizard, shareUrl, studioUrl, updateWizardSettings, wizardState, writeDraft, } from "../services/wizards.js";
+const definition = z
+    .record(z.string(), z.unknown())
+    .describe("The complete wizard JSON as described by get_authoring_guide.");
+const note = z
+    .string()
+    .max(500)
+    .optional()
+    .describe("One sentence for the admin about what changed, in their language. Shown in the studio.");
+const baseRevision = z
+    .number()
+    .int()
+    .min(0)
+    .describe("The revision you last read. A newer one on the server answers revision_conflict.");
+function ok(value) {
+    return {
+        content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value) }],
+    };
+}
+function failure(err) {
+    let body;
+    if (err instanceof ServiceError) {
+        body = err.toJSON();
+    }
+    else if (err instanceof RunConflict) {
+        body = { error: err.message, code: "conflict" };
+    }
+    else if (err instanceof z.ZodError) {
+        body = { error: "Invalid input", code: "invalid", issues: err.issues };
+    }
+    else {
+        console.error("[mcp]", err);
+        body = { error: "Internal error", code: "internal" };
+    }
+    return { isError: true, content: [{ type: "text", text: JSON.stringify(body) }] };
+}
+export function registerTools(server, who) {
+    const writer = { source: "mcp", client: who.client };
+    const tool = (name, scope, config, run) => {
+        if (!who.scopes.includes(scope)) {
+            return;
+        }
+        server.registerTool(name, {
+            title: config.title,
+            description: config.description,
+            inputSchema: config.input,
+            annotations: { readOnlyHint: config.readOnly ?? false, openWorldHint: false },
+        }, 
+        // The SDK has parsed `args` with `input` before this runs.
+        (async (args) => {
+            try {
+                return ok(await run(args));
+            }
+            catch (err) {
+                return failure(err);
+            }
+        }));
+    };
+    // --- read ------------------------------------------------------------------
+    tool("get_authoring_guide", "wizards:read", {
+        title: "Authoring guide",
+        description: "Read this before writing a wizard: the JSON schema, field kinds, step types and tools, templates, design rules, and the MCP servers of the project.",
+        input: z.object({
+            projectId: z.string().optional().describe("Defaults to the admin's first project."),
+        }),
+        readOnly: true,
+    }, async ({ projectId }) => {
+        const project = projectId
+            ? await ownedProject(who.userId, projectId)
+            : await defaultProject(who.userId);
+        return authoringGuide(project.mcpServers.map((s) => ({ id: s.id, name: s.name })), await listConnectors(project.id));
+    });
+    // --- connectors ------------------------------------------------------------
+    tool("find_connectors", "wizards:read", {
+        title: "Find connectors",
+        description: "Search the integrations registry for a service that can be imported as a connector, from its OpenAPI spec or its MCP server.",
+        input: z.object({ query: z.string().min(1).max(200) }),
+        readOnly: true,
+    }, async ({ query }) => ({ services: await searchRegistry(query) }));
+    tool("list_connectors", "wizards:read", {
+        title: "List connectors",
+        description: "The connectors a project has imported, each with its actions.",
+        input: z.object({ projectId: z.string().optional() }),
+        readOnly: true,
+    }, async ({ projectId }) => {
+        const project = projectId
+            ? await ownedProject(who.userId, projectId)
+            : await defaultProject(who.userId);
+        return { projectId: project.id, connectors: await listConnectors(project.id) };
+    });
+    tool("import_connector", "wizards:write", {
+        title: "Import connector",
+        description: "Import a registry service into a project as a connector. Returns its id, tool prefix, how people connect and its actions. A wizard uses it through a connection { id, connector }.",
+        input: z.object({
+            projectId: z.string().optional(),
+            domain: z.string().describe("A domain from find_connectors, e.g. notion.com"),
+            kind: z.enum(["mcp", "openapi"]).optional(),
+        }),
+    }, async ({ projectId, domain, kind }) => {
+        const project = projectId
+            ? await ownedProject(who.userId, projectId)
+            : await defaultProject(who.userId);
+        return importFromRegistry(who.userId, project.id, { domain, kind });
+    });
+    tool("list_starters", "wizards:read", {
+        title: "List starters",
+        description: "The marketplace's ready-made wizards (tweet with image, video ad, research briefing, dashboard, invoice, offer …), with what each makes and needs. Give a query to search them; without one you get the starters.",
+        input: z.object({ query: z.string().max(200).optional() }),
+        readOnly: true,
+    }, async ({ query }) => (await searchMarketplace({ q: query ?? "", lang: "de", limit: 30 })).entries
+        .filter((s) => s.usable && (query?.trim() || s.starter))
+        .map((s) => ({
+        id: s.id,
+        title: s.title,
+        pitch: s.pitch,
+        formats: s.formats,
+        useCases: s.useCases,
+        capabilities: s.capabilities,
+    })));
+    tool("get_starter", "wizards:read", {
+        title: "Get starter",
+        description: "A starter's complete wizard JSON — the best example to copy from.",
+        input: z.object({ starterId: z.string() }),
+        readOnly: true,
+    }, async ({ starterId }) => {
+        const starter = await marketplaceWizard(starterId, "de");
+        if (!starter) {
+            throw new ServiceError("not_found", `There is no starter "${starterId}".`);
+        }
+        return starter.definition;
+    });
+    tool("list_projects", "wizards:read", {
+        title: "List projects",
+        description: "The admin's projects. Each holds wizards, a brand and MCP servers.",
+        input: z.object({}),
+        readOnly: true,
+    }, async () => (await listProjects(who.userId)).map((p) => ({
+        id: p.id,
+        name: p.name,
+        wizardCount: p.wizardCount,
+    })));
+    tool("list_wizards", "wizards:read", {
+        title: "List wizards",
+        description: "The admin's wizards, newest first.",
+        input: z.object({ projectId: z.string().optional() }),
+        readOnly: true,
+    }, async ({ projectId }) => (await listWizards(who.userId, projectId)).map((w) => ({
+        id: w.id,
+        projectId: w.projectId,
+        title: w.title,
+        revision: w.revision,
+        published: w.published,
+        updatedAt: w.updatedAt,
+        studioUrl: studioUrl(w.id),
+    })));
+    tool("get_wizard", "wizards:read", {
+        title: "Get wizard",
+        description: "A wizard's draft with its revision and validator issues, whether it differs from the published version, and its links.",
+        input: z.object({ wizardId: z.string() }),
+        readOnly: true,
+    }, async ({ wizardId }) => {
+        const s = await wizardState(await ownedWizard(who.userId, wizardId));
+        return {
+            wizardId: s.id,
+            projectId: s.projectId,
+            revision: s.revision,
+            draft: s.draft,
+            issues: s.issues,
+            publishedVersion: s.publishedVersion,
+            dirty: s.dirty,
+            shareEnabled: s.shareEnabled,
+            dailyRunLimit: s.dailyRunLimit,
+            shareUrl: s.shareUrl,
+            studioUrl: s.studioUrl,
+        };
+    });
+    tool("validate_wizard", "wizards:read", {
+        title: "Validate wizard",
+        description: "Check a wizard JSON without saving it. Returns ok and the issues.",
+        input: z.object({ definition }),
+        readOnly: true,
+    }, async (args) => {
+        try {
+            const { issues } = parseDraft(args.definition);
+            return { ok: issues.length === 0, issues };
+        }
+        catch (err) {
+            if (err instanceof ServiceError && err.code === "invalid") {
+                return { ok: false, issues: err.data.issues };
+            }
+            throw err;
+        }
+    });
+    // --- write -----------------------------------------------------------------
+    tool("create_wizard", "wizards:write", {
+        title: "Create wizard",
+        description: "Create a wizard from your JSON, or copy a starter. The draft may still have issues; fix them with edit_wizard.",
+        input: z.object({
+            projectId: z.string().optional().describe("Defaults to the admin's first project."),
+            definition: definition.optional(),
+            starterId: z.string().optional().describe("Copy this starter instead of sending JSON."),
+            note,
+        }),
+    }, async (args) => {
+        const created = await createWizard(who.userId, args, writer);
+        return {
+            wizardId: created.id,
+            revision: created.revision,
+            issues: created.issues,
+            studioUrl: created.studioUrl,
+        };
+    });
+    tool("edit_wizard", "wizards:write", {
+        title: "Edit wizard",
+        description: `Apply ops to the draft atomically, in order:
+- set_meta {title?, description?, avatar?, intro? (null removes)}
+- set_lists {lists} / set_connections {connections}: replace the wizard's lists or connections as a whole
+- upsert_step {step (complete), before?|after?}: replaces the step with that id, else inserts it (default: before the final result step)
+- remove_step {stepId}
+- move_step {stepId, before|after}
+Returns the new revision and the issues.`,
+        input: z.object({
+            wizardId: z.string(),
+            baseRevision,
+            ops: z.array(wizardOpSchema).min(1).max(50),
+            note,
+        }),
+    }, async ({ wizardId, ...input }) => {
+        const { revision, issues } = await editWizard(who.userId, wizardId, input, writer);
+        return { revision, issues };
+    });
+    tool("replace_wizard", "wizards:write", {
+        title: "Replace wizard",
+        description: "Replace the whole draft. Use edit_wizard for smaller changes.",
+        input: z.object({ wizardId: z.string(), baseRevision, definition, note }),
+    }, async ({ wizardId, ...input }) => {
+        const { revision, issues } = await writeDraft(who.userId, wizardId, input, writer);
+        return { revision, issues };
+    });
+    // --- publish ---------------------------------------------------------------
+    tool("publish_wizard", "wizards:publish", {
+        title: "Publish wizard",
+        description: "Publish the draft as a new version behind the share link. Refused while the draft has issues. Only when the admin asked for it.",
+        input: z.object({ wizardId: z.string() }),
+    }, async ({ wizardId }) => publishWizard(who.userId, wizardId));
+    tool("set_sharing", "wizards:publish", {
+        title: "Set sharing",
+        description: "Turn the share link on or off, or change how many runs it allows per day.",
+        input: z.object({
+            wizardId: z.string(),
+            enabled: z.boolean().optional(),
+            dailyRunLimit: z.number().int().min(1).max(10_000).optional(),
+        }),
+    }, async ({ wizardId, enabled, dailyRunLimit }) => {
+        const w = await updateWizardSettings(who.userId, wizardId, {
+            shareEnabled: enabled,
+            dailyRunLimit,
+        });
+        return {
+            shareEnabled: w.shareEnabled,
+            dailyRunLimit: w.dailyRunLimit,
+            shareUrl: shareUrl(w.shareToken),
+        };
+    });
+    // --- test runs ---------------------------------------------------------------
+    tool("start_test_run", "runs:test", {
+        title: "Start test run",
+        description: "Run the draft once with your answers. SPENDS THE ADMIN'S CREDITS (short copy + image ~15, research ~150, video ~250). Pages are filled from `answers`, reviews accepted when acceptReviews is true. Follow it with get_test_run.",
+        input: z.object({
+            wizardId: z.string(),
+            answers: z
+                .record(z.string(), z.unknown())
+                .default({})
+                .describe("Field id → value, for every page (field ids are unique in a wizard). Items fields take an array of row objects."),
+            acceptReviews: z.boolean().default(true),
+        }),
+    }, async ({ wizardId, answers, acceptReviews }) => startTestRun(who.userId, wizardId, { answers, acceptReviews }));
+    tool("get_test_run", "runs:test", {
+        title: "Get test run",
+        description: "Status, recent events, outputs (text clipped) with signed download links valid one hour, credits spent, and what the run waits for.",
+        input: z.object({
+            runId: z.string(),
+            waitSeconds: z
+                .number()
+                .int()
+                .min(0)
+                .max(45)
+                .default(0)
+                .describe("Wait up to this long while the run is still working."),
+        }),
+        readOnly: true,
+    }, async ({ runId, waitSeconds }) => testRunReport(who.userId, runId, waitSeconds));
+    // --- workspace (widget code, libraries, reference data) --------------------
+    tool("list_files", "wizards:read", {
+        title: "List workspace files",
+        description: "The wizard's workspace: widget HTML/JS/CSS, vendored libraries, reference data. Runs use a snapshot of it.",
+        input: z.object({ wizardId: z.string() }),
+        readOnly: true,
+    }, async ({ wizardId }) => (await listFiles(who.userId, wizardId)).map(({ path, mime, size }) => ({ path, mime, size })));
+    tool("read_file", "wizards:read", {
+        title: "Read workspace file",
+        description: "A workspace file as text (binary files are described, not returned).",
+        input: z.object({ wizardId: z.string(), path: z.string() }),
+        readOnly: true,
+    }, async ({ wizardId, path }) => readFileText(who.userId, wizardId, path));
+    tool("write_file", "wizards:write", {
+        title: "Write workspace file",
+        description: "Create or overwrite a workspace file: `content` for text (HTML, JS, CSS, JSON, CSV, SVG) or `base64` for binary (images, fonts). Max 5 MB per file, 25 MB per workspace. A widget may only use files from here — no network when it runs.",
+        input: z.object({
+            wizardId: z.string(),
+            path: z.string().describe('Relative path, e.g. "weather/index.html" or "lib/d3.min.js".'),
+            content: z.string().optional(),
+            base64: z.string().optional(),
+            mime: z.string().optional(),
+        }),
+    }, async ({ wizardId, path, content, base64, mime }) => {
+        if ((content === undefined) === (base64 === undefined)) {
+            throw new ServiceError("invalid", "Pass either content or base64.");
+        }
+        return writeFile(who.userId, wizardId, path, content ?? Buffer.from(base64 ?? "", "base64"), mime);
+    });
+    tool("delete_file", "wizards:write", {
+        title: "Delete workspace file",
+        description: "Remove a file from the workspace.",
+        input: z.object({ wizardId: z.string(), path: z.string() }),
+    }, async ({ wizardId, path }) => {
+        await deleteFile(who.userId, wizardId, path);
+        return { ok: true };
+    });
+    if (who.scopes.includes("wizards:read")) {
+        const input = z.object({
+            wizardId: z.string(),
+            stepId: z.string().describe("A widget step of the draft."),
+            data: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Data to show instead of the step's sample file."),
+        });
+        server.registerTool("check_widget", {
+            title: "Check widget",
+            description: "Load a widget step of the draft in a real browser with its sample data: script errors, the timeline it registered (seconds, for the MP4 export) and a screenshot.",
+            inputSchema: input,
+            annotations: { readOnlyHint: true, openWorldHint: false },
+        }, (async ({ wizardId, stepId, data }) => {
+            try {
+                const r = await checkDraftWidget(who.userId, wizardId, stepId, data);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                errors: r.errors,
+                                timelineSeconds: r.duration,
+                                size: r.size,
+                                bundleBytes: r.bytes,
+                            }),
+                        },
+                        { type: "image", data: Buffer.from(r.png).toString("base64"), mimeType: "image/png" },
+                    ],
+                };
+            }
+            catch (err) {
+                return failure(err);
+            }
+        }));
+    }
+}
+export function registerPrompts(server) {
+    server.registerPrompt("design_wizard", {
+        title: "Design a wizard",
+        description: "Build an engenty wizard from a description.",
+        argsSchema: z.object({ description: z.string().describe("What the wizard should do.") }),
+    }, ({ description }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Build an engenty wizard: ${description}
+
+1. Call get_authoring_guide and follow its rules.
+2. Pick the closest starter (list_starters, get_starter) as an example.
+3. create_wizard with a short note; fix every issue with edit_wizard.
+4. start_test_run with realistic answers, then get_test_run with waitSeconds until it is done; fix what looks wrong.
+5. Give me the studioUrl and a short summary. Publish only if I ask.`,
+                },
+            },
+        ],
+    }));
+}

package/apps/runtime/dist/media/ffmpeg.js

@@ -0,0 +1,121 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { env } from "../env.js";
+let ffmpegCheck = null;
+export function hasFfmpeg() {
+    ffmpegCheck ??= new Promise((resolve) => {
+        const p = spawn(env.ffmpegPath, ["-version"], { stdio: "ignore" });
+        p.on("error", () => resolve(false));
+        p.on("exit", (code) => resolve(code === 0));
+    });
+    return ffmpegCheck;
+}
+/** Runs ffmpeg to its end; what it wrote to stderr comes back either way. */
+export function ffmpeg(args) {
+    return new Promise((resolve, reject) => {
+        const p = spawn(env.ffmpegPath, ["-hide_banner", ...args], {
+            stdio: ["ignore", "ignore", "pipe"],
+        });
+        let stderr = "";
+        p.stderr.on("data", (d) => {
+            stderr = (stderr + String(d)).slice(-20_000);
+        });
+        p.on("error", reject);
+        p.on("exit", (code) => resolve({ code: code ?? 1, stderr }));
+    });
+}
+/** A folder for one job's files, removed when the job is over. */
+export async function withTempDir(use) {
+    const dir = await mkdtemp(join(tmpdir(), "wizard-media-"));
+    try {
+        return await use(dir);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+/** What ffmpeg says about a media file: how long it is, whether it carries sound, its picture size. */
+export async function probeMedia(path) {
+    // Without an output ffmpeg prints the streams and exits with an error; the print is the answer.
+    const { stderr } = await ffmpeg(["-i", path]);
+    const m = stderr.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/);
+    const seconds = m ? Number(m[1]) * 3600 + Number(m[2]) * 60 + Number(m[3]) : 0;
+    const size = stderr.match(/Stream #\d+:\d+.*Video:.*?, (\d{2,5})x(\d{2,5})/);
+    return {
+        seconds,
+        audio: /Stream #\d+:\d+.*Audio:/.test(stderr),
+        width: size ? Number(size[1]) : 0,
+        height: size ? Number(size[2]) : 0,
+    };
+}
+/**
+ * A video no larger than `short` pixels on its short side (720 for 720p), sound kept. One that
+ * fits already comes back as it is; without ffmpeg too.
+ */
+export async function capVideo(bytes, short) {
+    if (!(await hasFfmpeg())) {
+        return bytes;
+    }
+    return withTempDir(async (dir) => {
+        const input = join(dir, "in.mp4");
+        const out = join(dir, "out.mp4");
+        await writeFile(input, bytes);
+        const { width, height } = await probeMedia(input);
+        if (!(width && height) || Math.min(width, height) <= short) {
+            return bytes;
+        }
+        const scale = width >= height ? `scale=-2:${short}` : `scale=${short}:-2`;
+        const { code } = await ffmpeg([
+            "-y",
+            "-loglevel",
+            "error",
+            "-i",
+            input,
+            "-vf",
+            scale,
+            "-c:v",
+            "libx264",
+            "-preset",
+            "veryfast",
+            "-crf",
+            "21",
+            "-pix_fmt",
+            "yuv420p",
+            "-c:a",
+            "copy",
+            "-movflags",
+            "+faststart",
+            out,
+        ]);
+        return code === 0 ? new Uint8Array(await readFile(out)) : bytes;
+    });
+}
+/**
+ * Any audio as MP3 — what every phone and browser plays — with `tags` written into the file
+ * (ID3). An MP3 is not encoded again, only tagged. `null` without ffmpeg.
+ */
+export async function toMp3(bytes, ext, tags = {}) {
+    if (!(await hasFfmpeg())) {
+        return null;
+    }
+    return withTempDir(async (dir) => {
+        const input = join(dir, `in.${ext}`);
+        const out = join(dir, "out.mp3");
+        await writeFile(input, bytes);
+        const { code } = await ffmpeg([
+            "-y",
+            "-loglevel",
+            "error",
+            "-i",
+            input,
+            ...(ext === "mp3" ? ["-codec:a", "copy"] : ["-codec:a", "libmp3lame", "-q:a", "3"]),
+            "-id3v2_version",
+            "3",
+            ...Object.entries(tags).flatMap(([key, value]) => ["-metadata", `${key}=${value}`]),
+            out,
+        ]);
+        return code === 0 ? new Uint8Array(await readFile(out)) : null;
+    });
+}