@miraiclip/assistant 0.1.0 → 0.1.1

package/dist/index.cjs

@@ -20,8 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  BACKGROUND_TEMPLATE: () => BACKGROUND_TEMPLATE,
   ChatModelError: () => ChatModelError,
   DEFAULT_INSTRUCTIONS: () => DEFAULT_INSTRUCTIONS,
+  applyChecked: () => applyChecked,
   applyCommandsSchema: () => applyCommandsSchema,
   commitFork: () => commitFork,
   createAssistant: () => createAssistant,
@@ -29,14 +31,18 @@ __export(src_exports, {
   defineChatModel: () => defineChatModel,
   defineTool: () => defineTool,
   describeCommands: () => describeCommands,
+  describeForAssistant: () => describeForAssistant,
   editorTools: () => editorTools,
   forkProject: () => forkProject,
   openAIChatModel: () => openAIChatModel,
   parseToolArguments: () => parseToolArguments,
+  rateLimitedChatModel: () => rateLimitedChatModel,
   remoteChatModel: () => remoteChatModel,
+  retryDelayMs: () => retryDelayMs,
   scriptedChatModel: () => scriptedChatModel,
   toOpenAIMessages: () => toOpenAIMessages,
   toolsFromDefinitions: () => toolsFromDefinitions,
+  unknownFields: () => unknownFields,
   withExplicitIds: () => withExplicitIds
 });
 module.exports = __toCommonJS(src_exports);
@@ -87,6 +93,21 @@ function parseToolArguments(raw) {
     return { __invalidArguments: raw };
   }
 }
+var RETRYABLE = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+function retryDelayMs(res, message, attempt) {
+  const header = Number(res.headers.get("retry-after-ms") ?? NaN) || Number(res.headers.get("retry-after") ?? NaN) * 1e3;
+  const m = /try again in ([\d.]+)\s*(ms|s)/i.exec(message);
+  const asked = header || (m ? Number(m[1]) * (m[2].toLowerCase() === "ms" ? 1 : 1e3) : 0);
+  const backoff = Math.min(3e4, 1e3 * 2 ** attempt);
+  return Math.round(Math.min(6e4, Math.max(asked + 250, asked ? 0 : backoff)) * (1 + Math.random() * 0.25));
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason ?? new Error("aborted"));
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => (clearTimeout(t), reject(signal.reason ?? new Error("aborted"))), { once: true });
+  });
+}
 var FINISH = {
   stop: "stop",
   tool_calls: "tool_calls",
@@ -118,15 +139,21 @@ function openAIChatModel(options) {
       if (options.apiKey) headers["Authorization"] = `Bearer ${options.apiKey}`;
       if (options.organization) headers["OpenAI-Organization"] = options.organization;
       if (options.project) headers["OpenAI-Project"] = options.project;
-      const res = await doFetch(`${base}/chat/completions`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-        ...opts.signal ? { signal: opts.signal } : {}
-      });
-      if (!res.ok) {
+      const maxRetries = options.maxRetries ?? 4;
+      let res;
+      for (let attempt = 0; ; attempt++) {
+        res = await doFetch(`${base}/chat/completions`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          ...opts.signal ? { signal: opts.signal } : {}
+        });
+        if (res.ok) break;
         const err = await res.json().catch(() => null);
-        throw new ChatModelError(id, err?.error?.message ?? `HTTP ${res.status}`, res.status);
+        const message = err?.error?.message ?? `HTTP ${res.status}`;
+        const permanent = /quota|credits|billing/i.test(message);
+        if (attempt >= maxRetries || !RETRYABLE.has(res.status) || permanent) throw new ChatModelError(id, message, res.status);
+        await sleep(retryDelayMs(res, message, attempt), opts.signal);
       }
       if (!stream || !res.body || !(res.headers.get("content-type") ?? "").includes("event-stream")) {
         return fromCompletion(await res.json(), opts.onText);
@@ -303,8 +330,163 @@ async function remoteChatModel(endpoint, options = {}) {
   };
 }
 
-// src/tools.ts
+// src/limits.ts
+function rateLimitedChatModel(model, options) {
+  const tpm = options.tokensPerMinute ?? Infinity;
+  const rpm = options.requestsPerMinute ?? Infinity;
+  const estimate = options.estimate ?? ((r) => Math.ceil(JSON.stringify(r).length / 4) + (r.maxOutputTokens ?? 1e3));
+  const window = [];
+  let gate = Promise.resolve();
+  const prune = (now) => {
+    while (window.length && now - window[0].at >= 6e4) window.shift();
+  };
+  const used = () => window.reduce((n2, e) => n2 + e.tokens, 0);
+  const reserve = (tokens, signal) => {
+    const want = Math.min(tokens, tpm);
+    const turn = gate.then(async () => {
+      for (; ; ) {
+        if (signal?.aborted) throw signal.reason ?? new Error("aborted");
+        const now = Date.now();
+        prune(now);
+        if (window.length < rpm && used() + want <= tpm) break;
+        const oldest = window[0];
+        await new Promise((r) => setTimeout(r, oldest ? Math.max(50, 6e4 - (now - oldest.at)) : 50));
+      }
+      const entry = { at: Date.now(), tokens: want };
+      window.push(entry);
+      return entry;
+    });
+    gate = turn.then(
+      () => void 0,
+      () => void 0
+    );
+    return turn;
+  };
+  return {
+    ...model,
+    async complete(request, opts = {}) {
+      const entry = await reserve(estimate(request), opts.signal);
+      const response = await model.complete(request, opts);
+      const real = (response.usage?.inputTokens ?? 0) + (response.usage?.outputTokens ?? 0);
+      if (real > 0) entry.tokens = real;
+      return response;
+    }
+  };
+}
+
+// src/state.ts
 var import_core = require("@miraiclip/core");
+function describeForAssistant(doc) {
+  const lines = [
+    (0, import_core.describeProject)(doc),
+    "",
+    "track names: " + doc.trackOrder.map((id) => {
+      const t = doc.tracks[id];
+      const flags = [t?.hidden && "hidden", t?.muted && "muted", t?.solo && "solo", t?.locked && "locked"].filter(Boolean);
+      return `${id} = "${t?.name ?? id}"${flags.length ? ` (${flags.join(", ")})` : ""}`;
+    }).join(", ") + " (track flags muted / solo / locked / hidden: track/set-property)"
+  ];
+  const cuts = (0, import_core.findCuts)(doc);
+  lines.push(
+    cuts.length ? `cuts (where one clip ends and the next starts on the same track; transitions go here): ${cuts.map((c) => `${n(c.atUs / 1e6)}s ${c.fromClipId}\u2192${c.toClipId}${c.transition ? ` (${c.transition.kind})` : ""}`).join(", ")}` : "cuts: none"
+  );
+  const clips = Object.values(doc.clips).sort((a, b) => a.trackId.localeCompare(b.trackId) || a.startUs - b.startUs);
+  if (clips.length) {
+    lines.push("clip details (transform x/y: 0.5 = center; scale 1 = full size; times in seconds):");
+    for (const clip of clips) lines.push(`- ${clip.id}: ${details(clip)}`);
+  }
+  return lines.join("\n");
+}
+var n = (v) => Number(v.toFixed(3));
+function details(clip) {
+  const parts = [`${clip.kind} on ${clip.trackId}`, `${n(clip.startUs / 1e6)}\u2013${n((clip.startUs + clip.durationUs) / 1e6)}s`];
+  if (clip.kind !== "audio") {
+    const t = clip.transform;
+    parts.push(`x ${n(t.x)} y ${n(t.y)} scale ${n(t.scale)}${t.rotation ? ` rotation ${n(t.rotation)}\xB0` : ""} opacity ${n(t.opacity)}`);
+  }
+  if (clip.kind === "text") {
+    const c = clip;
+    parts.push(`font ${c.fontFamily} ${c.fontSizePx}px${c.fontWeight ? ` weight ${c.fontWeight}` : ""} color ${c.color}${c.textAlign ? ` align ${c.textAlign}` : ""}`);
+  }
+  if (clip.kind === "caption") {
+    const c = clip;
+    parts.push(
+      `words "${c.words.map((w) => w.text).join(" ").slice(0, 80)}" \xB7 style preset ${c.style.preset} color ${c.style.color} highlight ${c.style.highlightColor} box ${c.style.backgroundColor ?? "none"} (style.backgroundColor)`
+    );
+  }
+  if (clip.kind === "html") {
+    const c = clip;
+    parts.push(`params ${JSON.stringify(c.params)} (template placeholders: ${htmlPlaceholders(c.template).join(", ") || "none"})`);
+  }
+  if ("volume" in clip) {
+    const c = clip;
+    parts.push(`volume ${n(c.volume)}${c.fadeInUs ? ` fade-in ${n(c.fadeInUs / 1e6)}s` : ""}${c.fadeOutUs ? ` fade-out ${n(c.fadeOutUs / 1e6)}s` : ""}`);
+    parts.push(`source from ${n(c.trimStartUs / 1e6)}s`);
+  }
+  if (clip.effects?.length) parts.push(`effects ${clip.effects.map((e) => `${e.kind}#${e.id}${e.enabled ? "" : " (off)"}`).join(", ")}`);
+  const volumeKeys = clip.animations?.volume ?? [];
+  if (volumeKeys.length) parts.push(`volume keyframes ${volumeKeys.map((k) => `${n((clip.startUs + (0, import_core.keyframeTimeUs)(k, clip.durationUs)) / 1e6)}s=${n(k.value)}`).join(", ")}`);
+  const visual = Object.entries(clip.animations ?? {}).some(([prop, list]) => prop !== "volume" && list && list.length);
+  if (visual) {
+    const read = readClipAnimation(clip);
+    parts.push(read.custom ? `custom keyframes (not presets): ${describeKeyframes(clip)}` : `animation ${(0, import_core.describeAnimation)(read.recipe)}`);
+  }
+  return parts.join(" \xB7 ");
+}
+function htmlPlaceholders(template) {
+  return [...new Set([...template.matchAll(/\{\{\s*([\w.-]+)\s*\}\}/g)].map((m) => m[1]))];
+}
+function readClipAnimation(clip) {
+  const read = (0, import_core.readAnimation)(clip);
+  if (read.custom) return { recipe: {}, custom: true };
+  if (read.stale && read.recipe.loop) {
+    const preset = (0, import_core.animationPreset)(read.recipe.loop.preset);
+    const props = Object.keys(preset?.build(clip.transform, 1e6, "linear") ?? {});
+    const count = props.reduce((sum, prop) => sum + (clip.animations?.[prop]?.length ?? 0), 0);
+    if (count < 4) return { recipe: {}, custom: true };
+  }
+  return { recipe: read.recipe, custom: false };
+}
+function describeKeyframes(clip) {
+  return Object.entries(clip.animations ?? {}).filter(([prop, list]) => prop !== "volume" && list?.length).map(([prop, list]) => `${prop} ${list.map((k) => `${n((clip.startUs + (0, import_core.keyframeTimeUs)(k, clip.durationUs)) / 1e6)}s ${n(k.value)}`).join(" \u2192 ")}`).join("; ");
+}
+
+// src/strict.ts
+function branches(schema) {
+  const alts = schema.anyOf ?? schema.oneOf;
+  return alts ? alts.flatMap(branches) : [schema];
+}
+function unknownIn(schema, value, prefix = "") {
+  const props = schema.properties;
+  if (!props || schema.additionalProperties !== void 0 && schema.additionalProperties !== false) return [];
+  const out = [];
+  for (const [key, v] of Object.entries(value)) {
+    const sub = props[key];
+    if (!sub) out.push(prefix + key);
+    else if (!prefix && v && typeof v === "object" && !Array.isArray(v)) {
+      const objectBranch = branches(sub).find((b) => b.properties);
+      if (objectBranch) out.push(...unknownIn(objectBranch, v, `${key}.`));
+    }
+  }
+  return out;
+}
+function unknownFields(schema, payload) {
+  if (!schema || !payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const value = payload;
+  let candidates = branches(schema).filter((b) => b.properties);
+  if (candidates.length === 0) return null;
+  const byKind = candidates.filter((b) => b.properties.kind?.const !== void 0 && b.properties.kind.const === value.kind);
+  if (byKind.length) candidates = byKind;
+  let best = null;
+  for (const b of candidates) {
+    const unknown = unknownIn(b, value);
+    if (!best || unknown.length < best.unknown.length) best = { unknown, allowed: Object.keys(b.properties) };
+  }
+  return best && best.unknown.length ? best : null;
+}
+
+// src/tools.ts
+var import_core2 = require("@miraiclip/core");
 function defineTool(tool) {
   if (!/^[a-zA-Z0-9_-]{1,64}$/.test(tool.name)) throw new Error(`Tool name must match ^[a-zA-Z0-9_-]{1,64}$ (got "${tool.name}")`);
   return tool;
@@ -327,7 +509,17 @@ function toolsFromDefinitions(definitions, run, options = {}) {
   });
 }
 var S = 1e6;
+var SLIDE_IN = { "from-right": "left", "from-left": "right", "from-bottom": "up", "from-top": "down" };
+var SLIDE_OUT = { "to-left": "left", "to-right": "right", "to-top": "up", "to-bottom": "down" };
+function slideAliases(input) {
+  const out = {};
+  if (typeof input.in === "string" && SLIDE_IN[input.in]) out.in = SLIDE_IN[input.in];
+  if (typeof input.out === "string" && SLIDE_OUT[input.out]) out.out = SLIDE_OUT[input.out];
+  return out;
+}
+var BACKGROUND_TEMPLATE = '<div style="width:100%;height:100%;background:{{color}}"></div>';
 var seconds = (us) => `${Math.round(us / 1e5) / 10}s`;
+var n3 = (v) => Number(v.toFixed(3));
 var toUs = (s) => typeof s === "number" && Number.isFinite(s) ? Math.round(s * S) : void 0;
 var PHRASES = {
   "clip/add": (p) => p.kind === "text" ? `Added text "${String(p.text ?? "").slice(0, 40)}" at ${seconds(Number(p.startUs))}` : `Added a ${p.kind} clip at ${seconds(Number(p.startUs))}`,
@@ -365,19 +557,19 @@ function describeCommands(commands) {
 }
 var US_NOTE = "Times in commands are integer MICROSECONDS (1 s = 1000000).";
 function editorTools(options = {}) {
-  const transitionKinds = options.transitionKinds ?? Object.keys(import_core.builtinTransitionParamSchemas);
-  const presetIds = (slot) => import_core.ANIMATION_PRESETS.filter((p) => p.slot === slot).map((p) => p.id.split(":")[1]);
+  const transitionKinds = options.transitionKinds ?? Object.keys(import_core2.builtinTransitionParamSchemas);
+  const presetIds = (slot) => import_core2.ANIMATION_PRESETS.filter((p) => p.slot === slot).map((p) => p.id.split(":")[1]);
   return [
     defineTool({
       name: "get_state",
-      description: `The project as it is now (after your edits so far): settings, assets, tracks with clips (ids, kinds, time ranges), transitions. ${US_NOTE}`,
+      description: `The project as it is now (after your edits so far): settings, assets, tracks with clips (ids, kinds, time ranges), transitions, and each clip's position, size, opacity, text style, volume, effects and animation. ${US_NOTE}`,
       inputSchema: {
         type: "object",
         properties: { includeJson: { type: "boolean", description: "Also return the full document JSON (verbose; only for exact field values)." } },
         additionalProperties: false
       },
       run(input, { project }) {
-        const summary = (0, import_core.describeProject)(project.toJSON());
+        const summary = describeForAssistant(project.toJSON());
         return { ok: true, result: input.includeJson ? { summary, document: project.toJSON() } : summary };
       }
     }),
@@ -399,18 +591,16 @@ function editorTools(options = {}) {
     defineTool({
       name: "apply_commands",
       description: `Apply editing commands as one all-or-nothing batch. On failure nothing changes and the error names the failing index and why (invalid payload issues, or the engine's rejection reason) \u2014 fix it and retry. Give new clips, tracks and assets your own readable ids. ${US_NOTE}`,
-      inputSchema: applyCommandsSchema(options.commandCatalog ?? (0, import_core.commandCatalog)()),
+      inputSchema: applyCommandsSchema(options.commandCatalog ?? (0, import_core2.commandCatalog)()),
       run(input, { project }) {
         const commands = input.commands;
         if (!Array.isArray(commands) || commands.length === 0) return { ok: false, error: "commands must be a non-empty array of { type, payload }" };
-        const result = (0, import_core.applyCommands)(project, commands);
-        if (!result.ok) return { ok: false, error: result };
-        return { ok: true, result: { applied: result.applied }, changes: describeCommands(commands) };
+        return applyChecked(project, commands);
       }
     }),
     defineTool({
       name: "add_transition",
-      description: "Add (or replace, or remove) a transition on cuts \u2014 where one clip ends exactly where the next starts on the same video track. Pick the cut by its two clip ids, by a time near it, or all cuts. A transition overlaps both clips around the cut, so its length is capped by the spare footage there; cuts with none are skipped and reported.",
+      description: 'Add (or replace, or remove) a transition on cuts \u2014 where one clip ends exactly where the next starts on the same video track. Pick the cut by its two clip ids, by a time near it, or all cuts. A transition overlaps both clips around the cut, so its length is capped by the spare footage there; cuts with none are skipped and reported. When a video clip directly follows another on its track, "fade into / dissolve to / slide in / wipe to" that clip means a transition on the cut before it, not an animation. Slide / wipe direction is the direction of motion: "from the left" = right.',
       inputSchema: {
         type: "object",
         properties: {
@@ -426,15 +616,23 @@ function editorTools(options = {}) {
         additionalProperties: false
       },
       run(input, { project }) {
-        const cuts = (0, import_core.findCuts)(project.getState().doc);
+        const cuts = (0, import_core2.findCuts)(project.getState().doc);
         if (cuts.length === 0) return { ok: false, error: "There are no cuts: transitions need two clips touching on the same video track." };
         let targets;
         if (input.allCuts === true) targets = cuts;
         else if (typeof input.fromClipId === "string" || typeof input.toClipId === "string") {
           targets = cuts.filter((c) => (!input.fromClipId || c.fromClipId === input.fromClipId) && (!input.toClipId || c.toClipId === input.toClipId));
+          if (targets.length === 0) return { ok: false, error: { error: noCutReason(project, input.fromClipId, input.toClipId), cuts: cuts.map(cutInfo) } };
         } else {
           const at = toUs(input.nearSeconds) ?? project.getState().playheadUs;
-          targets = [cuts.reduce((a, b) => Math.abs(b.atUs - at) < Math.abs(a.atUs - at) ? b : a)];
+          const nearest = cuts.reduce((a, b) => Math.abs(b.atUs - at) < Math.abs(a.atUs - at) ? b : a);
+          if (input.nearSeconds !== void 0 && Math.abs(nearest.atUs - at) > 1.5 * S) {
+            return {
+              ok: false,
+              error: { error: `There is no cut near ${seconds(at)} (the nearest is at ${seconds(nearest.atUs)}). Transitions only go on cuts; nothing was added. Use one of these cuts, or tell the user there isn't one there.`, cuts: cuts.map(cutInfo) }
+            };
+          }
+          targets = [nearest];
         }
         if (targets.length === 0) return { ok: false, error: { error: "no cut matches", cuts: cuts.map(cutInfo) } };
         const kind = String(input.kind);
@@ -459,7 +657,7 @@ function editorTools(options = {}) {
           changes.push(`${cut.transition ? "Replaced the transition with" : "Added"} ${kind} at ${seconds(cut.atUs)} (${seconds(durationUs)})`);
         }
         if (commands.length) {
-          const result = (0, import_core.applyCommands)(project, commands);
+          const result = (0, import_core2.applyCommands)(project, commands);
           if (!result.ok) return { ok: false, error: result };
         }
         return { ok: true, result: { changed: changes.length, skipped }, changes };
@@ -467,27 +665,35 @@ function editorTools(options = {}) {
     }),
     defineTool({
       name: "animate_clip",
-      description: `Give a visual clip (video, image, text) an entrance (in), a loop while on screen, and/or an exit (out), as keyframes. Slots you leave out keep their current animation; "none" removes one; reset:true removes all. In/out presets: ${presetIds("in").join(", ")}. Loops: ${presetIds("loop").join(", ")}. Exits stay on the clip's end through trims.`,
+      description: `Give a visual clip (video, image, text) an entrance (in), a loop while on screen, and/or an exit (out), as keyframes. Slots you leave out keep their current animation; "none" removes one; reset:true removes all. In/out presets: ${presetIds("in").join(", ")}. Loops: ${presetIds("loop").join(", ")}. Exits stay on the clip's end through trims. Slides: give the edge, in: "from-right" (enters from the right edge, moving left), "from-left", "from-top", "from-bottom"; out: "to-left", "to-right", "to-top", "to-bottom". For text, logos and overlays; between two video clips prefer add_transition. The clip's current animation is in get_state; pass only the slots to change. Fading the whole VIDEO in at the start and out at the end is two calls: in on the FIRST clip of the main video track, out on the LAST one (an out on the first clip would fade to black at its cut).`,
       inputSchema: {
         type: "object",
         properties: {
           clipId: { type: "string" },
-          in: { type: "string", enum: [...presetIds("in"), "none"] },
+          in: { type: "string", enum: [...presetIds("in"), ...Object.keys(SLIDE_IN), "none"], description: 'For slides, prefer "from-left" / "from-right" / "from-top" / "from-bottom": the edge the clip enters from.' },
           loop: { type: "string", enum: [...presetIds("loop"), "none"] },
-          out: { type: "string", enum: [...presetIds("out"), "none"] },
+          out: { type: "string", enum: [...presetIds("out"), ...Object.keys(SLIDE_OUT), "none"], description: 'For slides, prefer "to-left" / "to-right" / "to-top" / "to-bottom": the edge the clip leaves by.' },
           inSeconds: { type: "number", minimum: 0.2, maximum: 3, description: "Default 0.6." },
           outSeconds: { type: "number", minimum: 0.2, maximum: 3, description: "Default 0.6." },
-          easing: { type: "string", enum: import_core.ANIMATION_EASINGS.map((e) => e.id), description: "Default smooth." },
+          easing: { type: "string", enum: import_core2.ANIMATION_EASINGS.map((e) => e.id), description: "Default smooth." },
           reset: { type: "boolean" }
         },
         required: ["clipId"],
         additionalProperties: false
       },
       run(input, { project }) {
+        input = { ...input, ...slideAliases(input) };
         const clip = project.getState().doc.clips[String(input.clipId)];
         if (!clip) return { ok: false, error: `no clip "${input.clipId}"` };
         if (clip.kind === "audio") return { ok: false, error: "audio clips have no picture to animate (use volume or fades)" };
-        const current = input.reset === true ? {} : (0, import_core.readAnimation)(clip).recipe;
+        const reading = readClipAnimation(clip);
+        if (reading.custom && input.reset !== true) {
+          return {
+            ok: false,
+            error: `${clip.id} has its own keyframes (${describeKeyframes(clip)}), not presets; presets would overwrite them. To remove one property's animation, apply_commands keyframe/clear { clipId, property }. To edit them, use set_keyframes. To replace them all with presets, pass reset: true. Nothing was changed.`
+          };
+        }
+        const current = input.reset === true ? {} : reading.recipe;
         const next = { ...current };
         const easing = typeof input.easing === "string" ? input.easing : "smooth";
         for (const slot of ["in", "loop", "out"]) {
@@ -500,20 +706,405 @@ function editorTools(options = {}) {
           const durationUs = slot === "loop" ? 0 : toUs(input[slot === "in" ? "inSeconds" : "outSeconds"]) ?? current[slot]?.durationUs ?? 6e5;
           next[slot] = { preset: `${slot}:${name}`, durationUs, easing: slot === "loop" ? "linear" : easing };
         }
-        const recipe = (0, import_core.fitAnimation)(next, clip.durationUs);
-        const result = (0, import_core.applyCommands)(project, (0, import_core.animationCommands)(clip, recipe));
+        const recipe = (0, import_core2.fitAnimation)(next, clip.durationUs);
+        const result = (0, import_core2.applyCommands)(project, (0, import_core2.animationCommands)(clip, recipe));
         if (!result.ok) return { ok: false, error: result };
-        const summary = (0, import_core.describeAnimation)(recipe) || "no animation";
-        return { ok: true, result: { clipId: clip.id, animation: summary }, changes: [`${clip.id}: ${summary}`] };
+        const summary = (0, import_core2.describeAnimation)(recipe) || "no animation";
+        const atCut = input.in && input.in !== "none" && clip.kind === "video" ? (0, import_core2.findCuts)(project.getState().doc).find((c) => c.toClipId === clip.id) : void 0;
+        return {
+          ok: true,
+          result: {
+            clipId: clip.id,
+            animation: summary,
+            ...atCut ? { note: `${clip.id} starts at a cut right after ${atCut.fromClipId}. If the user meant going from ${atCut.fromClipId} into ${clip.id} ("fade into", "slide in", "dissolve to"), that is add_transition on this cut: undo this entrance with in:"none" and add the transition.` } : {}
+          },
+          changes: [`${clip.id}: ${summary}`]
+        };
+      }
+    }),
+    defineTool({
+      name: "add_effect",
+      description: "Add a visual effect to one or more clips (video, image, text). Kinds, with their params (min\u2013max, default): " + import_core2.EFFECT_CATALOG.map((e) => `${e.kind} (${e.label}${e.params.length ? `: ${e.params.map((p) => p.type === "number" ? `${p.key} ${p.min}\u2013${p.max}, ${p.default}` : `${p.key} color`).join("; ")}` : ""})`).join(", ") + ". Omitted params take their defaults. Black & white is mono; brightness, contrast, saturation and hue are colorAdjust params (-1\u20131, 0 = unchanged).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          clipIds: { type: "array", items: { type: "string" }, minItems: 1 },
+          kind: { type: "string", enum: import_core2.EFFECT_CATALOG.map((e) => e.kind) },
+          params: { type: "object", description: "Effect params by key; see the list above." }
+        },
+        required: ["clipIds", "kind"],
+        additionalProperties: false
+      },
+      run(input, { project }) {
+        const ids = input.clipIds ?? [];
+        const doc = project.getState().doc;
+        const missing = ids.filter((id) => !doc.clips[id]);
+        if (missing.length) return { ok: false, error: `no clip ${missing.map((m) => `"${m}"`).join(", ")}` };
+        const audio = ids.filter((id) => doc.clips[id].kind === "audio");
+        if (audio.length) return { ok: false, error: `audio clips have no picture: ${audio.join(", ")}` };
+        const params = input.params && typeof input.params === "object" ? input.params : void 0;
+        const out = applyChecked(project, ids.map((clipId) => ({ type: "effect/add", payload: { clipId, kind: input.kind, ...params ? { params } : {} } })));
+        if (!out.ok) return out;
+        const label = import_core2.EFFECT_CATALOG.find((e) => e.kind === input.kind)?.label ?? String(input.kind);
+        return { ...out, changes: [`Added ${label} to ${ids.join(", ")}`] };
+      }
+    }),
+    defineTool({
+      name: "remove_effects",
+      description: "Delete effects from clips: one kind, or every effect when kind is omitted. To turn effects off but keep them, use set_effects_enabled.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          clipIds: { type: "array", items: { type: "string" }, minItems: 1 },
+          kind: { type: "string", description: "Only effects of this kind (default: all)." }
+        },
+        required: ["clipIds"],
+        additionalProperties: false
+      },
+      run(input, { project }) {
+        const doc = project.getState().doc;
+        const commands = [];
+        for (const id of input.clipIds ?? []) {
+          const clip = doc.clips[id];
+          if (!clip) return { ok: false, error: `no clip "${id}"` };
+          for (const e of clip.effects ?? []) if (!input.kind || e.kind === input.kind) commands.push({ type: "effect/remove", payload: { clipId: id, effectId: e.id } });
+        }
+        if (!commands.length) return { ok: true, result: { removed: 0, note: "those clips had no matching effects" } };
+        const out = applyChecked(project, commands);
+        return out.ok ? { ...out, result: { removed: commands.length }, changes: [`Removed ${commands.length} effect${commands.length > 1 ? "s" : ""}`] } : out;
+      }
+    }),
+    defineTool({
+      name: "trim_clip",
+      description: "Trim a clip like an editor's edge drag, in seconds. removeFromStart cuts that much off the beginning (the clip's end stays put; for video/audio the source moves on too). removeFromEnd cuts off the end. setDuration sets the length, keeping the start. startSeconds / endSeconds put the clip's edges at those timeline times (e.g. 0 and the composition length to cover the whole video; a video/audio clip's source shifts with its start edge). ripple:true shifts later clips on the same track to close (or open) the gap.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          clipId: { type: "string" },
+          removeFromStart: { type: "number", exclusiveMinimum: 0 },
+          removeFromEnd: { type: "number", exclusiveMinimum: 0 },
+          setDuration: { type: "number", exclusiveMinimum: 0 },
+          startSeconds: { type: "number", minimum: 0, description: "Timeline time for the clip's start edge." },
+          endSeconds: { type: "number", exclusiveMinimum: 0, description: "Timeline time for the clip's end edge." },
+          ripple: { type: "boolean" }
+        },
+        required: ["clipId"],
+        additionalProperties: false
+      },
+      run(input, { project }) {
+        const doc = project.getState().doc;
+        const clip = doc.clips[String(input.clipId)];
+        if (!clip) return { ok: false, error: `no clip "${input.clipId}"` };
+        const head = toUs(input.removeFromStart) ?? 0;
+        const tail = toUs(input.removeFromEnd) ?? 0;
+        const ripple = input.ripple === true;
+        const startAt = toUs(input.startSeconds);
+        const endAt = toUs(input.endSeconds);
+        if ((startAt !== void 0 || endAt !== void 0) && (head || tail)) return { ok: false, error: "use either startSeconds / endSeconds or removeFromStart / removeFromEnd, not both" };
+        let duration = clip.durationUs - head - tail;
+        const set = toUs(input.setDuration);
+        if (set) duration = set;
+        let start = ripple ? clip.startUs : clip.startUs + head;
+        let sourceShift = head;
+        if (startAt !== void 0) {
+          start = startAt;
+          sourceShift = startAt - clip.startUs;
+          if (endAt === void 0 && !set) duration = clip.startUs + clip.durationUs - startAt;
+        }
+        if (endAt !== void 0) duration = endAt - start;
+        if (duration <= 0) return { ok: false, error: `that leaves the clip ${seconds(duration)} long; it is ${seconds(clip.durationUs)} (${seconds(clip.startUs)}\u2013${seconds(clip.startUs + clip.durationUs)})` };
+        const trimmable = "trimStartUs" in clip;
+        if (trimmable && clip.trimStartUs + sourceShift < 0) {
+          return { ok: false, error: `${clip.id}'s media has only ${seconds(clip.trimStartUs)} before its current start, so its start edge can move back at most that far` };
+        }
+        const commands = [
+          {
+            type: "clip/trim",
+            payload: {
+              clipId: clip.id,
+              startUs: start,
+              durationUs: duration,
+              ...trimmable && sourceShift ? { trimStartUs: clip.trimStartUs + sourceShift } : {}
+            }
+          }
+        ];
+        if (ripple) {
+          const oldEnd = clip.startUs + clip.durationUs;
+          const delta = start + duration - oldEnd;
+          const later = Object.values(doc.clips).filter((c) => c.trackId === clip.trackId && c.id !== clip.id && c.startUs >= oldEnd).sort((x, y) => delta < 0 ? x.startUs - y.startUs : y.startUs - x.startUs);
+          for (const c of later) commands.push({ type: "clip/move", payload: { clipId: c.id, startUs: Math.max(0, c.startUs + delta) } });
+        }
+        const out = applyChecked(project, commands);
+        if (!out.ok) return out;
+        const after = project.getState().doc.clips[clip.id];
+        return { ...out, changes: [`Trimmed ${clip.id} to ${seconds(after.startUs)}\u2013${seconds(after.startUs + after.durationUs)}`] };
+      }
+    }),
+    defineTool({
+      name: "set_effects_enabled",
+      description: "Turn effects off (or back on) without deleting them, keeping their settings: one kind, or every effect when kind is omitted. To delete effects use remove_effects.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          clipIds: { type: "array", items: { type: "string" }, minItems: 1 },
+          kind: { type: "string", description: "Only effects of this kind (default: all)." },
+          enabled: { type: "boolean" }
+        },
+        required: ["clipIds", "enabled"],
+        additionalProperties: false
+      },
+      run(input, { project }) {
+        const doc = project.getState().doc;
+        const enabled = input.enabled === true;
+        const commands = [];
+        for (const id of input.clipIds ?? []) {
+          const clip = doc.clips[id];
+          if (!clip) return { ok: false, error: `no clip "${id}"` };
+          for (const e of clip.effects ?? []) {
+            if ((!input.kind || e.kind === input.kind) && e.enabled !== enabled) commands.push({ type: "effect/update", payload: { clipId: id, effectId: e.id, enabled } });
+          }
+        }
+        if (!commands.length) return { ok: true, result: { changed: 0, note: `no matching effects that are ${enabled ? "off" : "on"}` } };
+        const out = applyChecked(project, commands);
+        return out.ok ? { ...out, result: { changed: commands.length }, changes: [`Turned ${enabled ? "on" : "off"} ${commands.length} effect${commands.length > 1 ? "s" : ""}`] } : out;
+      }
+    }),
+    defineTool({
+      name: "set_keyframes",
+      description: `Animate one property of a clip so it CHANGES over time, with keyframes at TIMELINE seconds (the same times as get_state). Replaces that property's existing keyframes (including a preset's) unless keep:true. Between points the value moves smoothly; before the first and after the last it holds. Properties: x, y (0\u20131, 0.5 = center), scale (1 = full size), rotation (degrees; 360 = one full turn, so a static 360 looks like 0), opacity (0\u20131), volume (0\u20131, audio/video). Not for constant values ("rotate 45\xB0", "music at 30%", "louder": set those with clip/set-property) or for removing an animation (keyframe/clear). Use it for motion and timed changes the presets don't cover: a spin (rotation 0 \u2192 360 over the clip), a pan, ducking music (volume: normal \u2192 low just before a range, low \u2192 normal just after), or fading audio between two times.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          clipId: { type: "string" },
+          property: { type: "string", enum: ["x", "y", "scale", "rotation", "opacity", "volume"] },
+          points: {
+            type: "array",
+            minItems: 1,
+            items: {
+              type: "object",
+              properties: { atSeconds: { type: "number", minimum: 0 }, value: { type: "number" } },
+              required: ["atSeconds", "value"],
+              additionalProperties: false
+            }
+          },
+          easing: { type: "string", enum: ["linear", "easeIn", "easeOut", "easeInOut", "hold"], description: "Curve between points (default linear)." },
+          keep: { type: "boolean", description: "Keep the property's other keyframes (default false: replace them)." }
+        },
+        required: ["clipId", "property", "points"],
+        additionalProperties: false
+      },
+      run(input, { project }) {
+        const clip = project.getState().doc.clips[String(input.clipId)];
+        if (!clip) return { ok: false, error: `no clip "${input.clipId}"` };
+        const property = String(input.property);
+        if (property === "volume" && !("volume" in clip)) return { ok: false, error: `${clip.id} is a ${clip.kind} clip and has no volume` };
+        if (property !== "volume" && clip.kind === "audio") return { ok: false, error: "audio clips only animate volume" };
+        const end = clip.startUs + clip.durationUs;
+        const points = input.points.map((p) => ({ atUs: toUs(p.atSeconds), value: p.value }));
+        const outside = points.filter((p) => p.atUs < clip.startUs - 1e3 || p.atUs > end + 1e3);
+        if (outside.length) return { ok: false, error: `${clip.id} runs ${seconds(clip.startUs)}\u2013${seconds(end)}; points must be inside that range (got ${outside.map((p) => seconds(p.atUs)).join(", ")})` };
+        if (input.keep !== true && new Set(points.map((p) => p.value)).size < 2) {
+          const how = property === "volume" ? "clip/set-property { volume }" : `clip/set-property { transform: { ${property} } }`;
+          return {
+            ok: false,
+            error: `Keyframes are for a value that CHANGES over time; ${points.length === 1 ? "one point" : "these points"} hold${points.length === 1 ? "s" : ""} a single value. For a constant ${property}, set it directly with apply_commands ${how}. To remove an animation, apply keyframe/clear { clipId, property }. Nothing was changed.`
+          };
+        }
+        const commands = [];
+        if (input.keep !== true && (clip.animations?.[property]?.length ?? 0) > 0) commands.push({ type: "keyframe/clear", payload: { clipId: clip.id, property } });
+        const easing = typeof input.easing === "string" ? input.easing : "linear";
+        for (const p of points) {
+          commands.push({ type: "keyframe/set", payload: { clipId: clip.id, property, timeUs: Math.min(clip.durationUs, Math.max(0, p.atUs - clip.startUs)), value: p.value, easing } });
+        }
+        const out = applyChecked(project, commands);
+        if (!out.ok) return out;
+        const list = points.map((p) => `${seconds(p.atUs)} ${n3(p.value)}`).join(" \u2192 ");
+        return { ...out, changes: [`${clip.id}: ${property} ${list}`] };
+      }
+    }),
+    defineTool({
+      name: "set_background",
+      description: `A solid color background behind everything (an html clip on a Background track at the very bottom). Adds one, recolors or re-times the existing one, or removes it with color "none". Covers the whole video unless fromSeconds / toSeconds say otherwise. Only visible where nothing opaque is on top (behind scaled-down, faded or transparent clips, or where there's no footage).`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          color: { type: "string", description: 'CSS color, e.g. "#1E3A8A", or "none" to remove the background.' },
+          fromSeconds: { type: "number", minimum: 0 },
+          toSeconds: { type: "number", exclusiveMinimum: 0 }
+        },
+        required: ["color"],
+        additionalProperties: false
+      },
+      run(input, { project }) {
+        const doc = project.getState().doc;
+        const color = String(input.color).trim();
+        const existing = Object.values(doc.clips).find(
+          (c) => c.kind === "html" && (c.template === BACKGROUND_TEMPLATE || doc.tracks[c.trackId]?.name === "Background")
+        );
+        if (color.toLowerCase() === "none") {
+          if (!existing) return { ok: true, result: { note: "there is no background to remove" } };
+          const commands2 = [{ type: "clip/remove", payload: { clipId: existing.id } }];
+          if (!Object.values(doc.clips).some((c) => c.trackId === existing.trackId && c.id !== existing.id)) commands2.push({ type: "track/remove", payload: { id: existing.trackId } });
+          const out2 = applyChecked(project, commands2);
+          return out2.ok ? { ...out2, changes: ["Removed the background"] } : out2;
+        }
+        let endUs = 0;
+        for (const c of Object.values(doc.clips)) if (c.id !== existing?.id) endUs = Math.max(endUs, c.startUs + c.durationUs);
+        const startUs = toUs(input.fromSeconds) ?? (existing && input.toSeconds === void 0 ? existing.startUs : 0);
+        const stopUs = toUs(input.toSeconds) ?? (existing && input.fromSeconds === void 0 ? existing.startUs + existing.durationUs : endUs || 10 * S);
+        if (stopUs <= startUs) return { ok: false, error: `toSeconds must be after fromSeconds (got ${seconds(startUs)}\u2013${seconds(stopUs)})` };
+        const commands = [];
+        if (existing) {
+          const params = existing;
+          const key = htmlPlaceholders(params.template).find((k) => /colou?r|background|bg/i.test(k)) ?? "color";
+          if (params.params[key] !== color) commands.push({ type: "clip/set-property", payload: { clipId: existing.id, params: { [key]: color } } });
+          if (existing.startUs !== startUs || existing.durationUs !== stopUs - startUs) commands.push({ type: "clip/trim", payload: { clipId: existing.id, startUs, durationUs: stopUs - startUs } });
+          if (!commands.length) return { ok: true, result: { note: "the background already looks like that" } };
+        } else {
+          const trackId = doc.tracks.background ? `background-${Object.keys(doc.tracks).length}` : "background";
+          commands.push({ type: "track/add", payload: { id: trackId, kind: "video", name: "Background", index: 0 } });
+          commands.push({ type: "clip/add", payload: { kind: "html", id: `${trackId}-clip`, trackId, startUs, durationUs: stopUs - startUs, template: BACKGROUND_TEMPLATE, params: { color } } });
+        }
+        const out = applyChecked(project, commands);
+        if (!out.ok) return out;
+        return { ...out, changes: [`${existing ? "Changed the background to" : "Added a background:"} ${color}, ${seconds(startUs)}\u2013${seconds(stopUs)}`] };
+      }
+    }),
+    defineTool({
+      name: "close_gaps",
+      description: "Close the empty gaps on a track so its clips run back to back, keeping their order (the first clip stays where it is, or starts at 0 with fromZero).",
+      inputSchema: {
+        type: "object",
+        properties: { trackId: { type: "string" }, fromZero: { type: "boolean" } },
+        required: ["trackId"],
+        additionalProperties: false
+      },
+      run(input, { project }) {
+        const doc = project.getState().doc;
+        if (!doc.tracks[String(input.trackId)]) return { ok: false, error: `no track "${input.trackId}"` };
+        const clips = Object.values(doc.clips).filter((c) => c.trackId === input.trackId).sort((a, b) => a.startUs - b.startUs);
+        let cursor = input.fromZero === true ? 0 : clips[0]?.startUs ?? 0;
+        const commands = [];
+        for (const c of clips) {
+          if (c.startUs !== cursor) commands.push({ type: "clip/move", payload: { clipId: c.id, startUs: cursor } });
+          cursor += c.durationUs;
+        }
+        if (!commands.length) return { ok: true, result: { moved: 0, note: "no gaps on that track" } };
+        const out = applyChecked(project, commands);
+        return out.ok ? { ...out, changes: [`Closed ${commands.length} gap${commands.length > 1 ? "s" : ""} on ${input.trackId}`] } : out;
       }
     })
   ];
 }
+var Abort = class extends Error {
+};
+function applyChecked(project, commands) {
+  const catalog = project.commandCatalog();
+  const nothing = commands.length > 1 ? "Nothing in this batch was applied (not even the commands before it): resend the whole corrected batch." : "Nothing was applied.";
+  const templates = /* @__PURE__ */ new Map();
+  for (const [index, command] of commands.entries()) {
+    if (!catalog[command?.type]) {
+      const looksLikeTool = /^[a-z]+(_[a-z]+)+$/.test(String(command?.type));
+      return {
+        ok: false,
+        error: {
+          failedIndex: index,
+          kind: "unknown-command",
+          commandType: command?.type,
+          error: `"${command?.type}" is not a command${looksLikeTool ? ": it is a tool. Call it as its own tool call, not inside apply_commands" : ""}. ${nothing}`,
+          validTypes: Object.keys(catalog).sort()
+        }
+      };
+    }
+    const htmlError = checkHtmlParams(project, command, templates);
+    if (htmlError) return { ok: false, error: { failedIndex: index, commandType: command.type, error: `${htmlError} ${nothing}` } };
+    const extra = unknownFields(catalog[command?.type], command?.payload);
+    if (extra) {
+      return {
+        ok: false,
+        error: {
+          failedIndex: index,
+          commandType: command.type,
+          error: `unknown field${extra.unknown.length > 1 ? "s" : ""} ${extra.unknown.map((f) => `"${f}"`).join(", ")}: ${command.type} would ignore ${extra.unknown.length > 1 ? "them" : "it"}. Its fields are: ${extra.allowed.join(", ")}. ${nothing}`
+        }
+      };
+    }
+  }
+  const unchanged = [];
+  let failure;
+  try {
+    project.transaction(() => {
+      commands.forEach((command, index) => {
+        const before = project.getState().doc;
+        const result = (0, import_core2.tryDispatch)(project, command);
+        if (!result.ok) {
+          const hint = rejectionHint(result.error, command);
+          const skipped = commands.length > 1 ? { notApplied: describeCommands(commands.filter((_, i) => i !== index)) } : {};
+          failure = { failedIndex: index, ...result.error, ...hint ? { hint } : {}, note: nothing, ...skipped };
+          throw new Abort();
+        }
+        if (project.getState().doc === before) unchanged.push(index);
+      });
+    });
+  } catch (err) {
+    if (err instanceof Abort) return { ok: false, error: failure };
+    throw err;
+  }
+  const changed = commands.filter((_, i) => !unchanged.includes(i));
+  return {
+    ok: true,
+    result: {
+      applied: changed.length,
+      ...unchanged.length ? { unchanged: unchanged.map((i) => ({ index: i, type: commands[i].type, note: "changed nothing: the project already had these values. Check the field names and values." })) } : {}
+    },
+    ...changed.length ? { changes: describeCommands(changed) } : {}
+  };
+}
+function checkHtmlParams(project, command, templates) {
+  const p = command.payload ?? {};
+  let template;
+  if (command.type === "clip/add" && p.kind === "html" && typeof p.template === "string") {
+    template = p.template;
+    if (typeof p.id === "string") templates.set(p.id, template);
+  } else if (command.type === "clip/set-property" && p.params && typeof p.params === "object") {
+    const clip = project.getState().doc.clips[String(p.clipId)];
+    template = templates.get(String(p.clipId)) ?? (clip?.kind === "html" ? clip.template : void 0);
+  }
+  if (template === void 0 || !p.params || typeof p.params !== "object") return void 0;
+  const names = htmlPlaceholders(template);
+  const unknown = Object.keys(p.params).filter((k) => !names.includes(k));
+  if (!unknown.length) return void 0;
+  return `html params ${unknown.map((k) => `"${k}"`).join(", ")} match no {{placeholder}} in the template, so they would change nothing. Its placeholders: ${names.join(", ") || "none"}.`;
+}
+function rejectionHint(error, _command) {
+  switch (error.code) {
+    case "no-audio":
+      return "fadeInUs / fadeOutUs fade audio only. To fade a text, image or video picture in or out, call animate_clip (in / out: fade).";
+    case "asset-not-found":
+      return "Clips can only use assets already in the project (see get_state). Audio found with search_audio is added with add_audio, which imports it.";
+    case "not-caption":
+    case "not-html":
+    case "not-text":
+      return "That field belongs to another clip kind: text clips take color / font fields, caption clips take style, html clips take params (named by the template's {{placeholders}}, shown in get_state).";
+    default:
+      return void 0;
+  }
+}
+function noCutReason(project, fromId, toId) {
+  const doc = project.getState().doc;
+  const a = typeof fromId === "string" ? doc.clips[fromId] : void 0;
+  const b = typeof toId === "string" ? doc.clips[toId] : void 0;
+  const tail = "Nothing was added. Don't substitute a different cut: tell the user, and offer an animation (animate_clip) instead if that fits.";
+  for (const [given, clip] of [[fromId, a], [toId, b]]) if (typeof given === "string" && !clip) return `There is no clip "${given}". ${tail}`;
+  if (a && b && a.trackId !== b.trackId) return `${a.id} is on track ${a.trackId} and ${b.id} on track ${b.trackId}: a transition joins two clips that touch on the SAME track, so these two have no cut between them. ${tail}`;
+  if (a && b) return `${a.id} and ${b.id} don't touch (${a.id} ends at ${seconds(a.startUs + a.durationUs)}, ${b.id} starts at ${seconds(b.startUs)}). ${tail}`;
+  return `No cut ${a ? `starts after ${a.id}` : `leads into ${b.id}`} (it isn't directly after/before another clip on its track). ${tail}`;
+}
 function cutInfo(c) {
   return { fromClipId: c.fromClipId, toClipId: c.toClipId, atSeconds: c.atUs / S, maxSeconds: c.maxTransitionUs / S, ...c.transition ? { transition: c.transition.kind } : {} };
 }
 function applyCommandsSchema(catalog) {
-  const [dispatch] = (0, import_core.toToolDefinitions)(catalog, { mode: "dispatch" });
+  const [dispatch] = (0, import_core2.toToolDefinitions)(catalog, { mode: "dispatch" });
   return {
     type: "object",
     properties: {
@@ -525,7 +1116,7 @@ function applyCommandsSchema(catalog) {
 }
 
 // src/fork.ts
-var import_core2 = require("@miraiclip/core");
+var import_core3 = require("@miraiclip/core");
 var seq = 0;
 var genId = (prefix) => `${prefix}-${Date.now().toString(36)}${(++seq).toString(36)}${Math.random().toString(36).slice(2, 6)}`;
 function withExplicitIds(command) {
@@ -544,7 +1135,7 @@ function withExplicitIds(command) {
   }
 }
 function forkProject(project, options = {}) {
-  const fork = (options.createFork ?? ((doc) => (0, import_core2.createProject)(doc)))(project.toJSON());
+  const fork = (options.createFork ?? ((doc) => (0, import_core3.createProject)(doc)))(project.toJSON());
   const state = project.getState();
   fork.setPlayhead(state.playheadUs);
   fork.setSelection([...state.selection]);
@@ -598,21 +1189,33 @@ function commitFork(project, fork, label) {
 }
 
 // src/run.ts
-var import_core3 = require("@miraiclip/core");
 var MAX_TOOL_RESULT = 2e4;
 var MAX_OLD_TOOL_RESULT = 2e3;
 var DEFAULT_INSTRUCTIONS = `You are the editing assistant inside a video editor. You change the user's project by calling tools; every change you make lands as ONE undo step when you finish, so act confidently.
 
 How to work:
 - The current project is summarized below. Clip, track and asset ids there are what tools expect. Call get_state to re-read it after big changes.
-- Prefer the high-level tools when they fit (add_transition, animate_clip, and any audio or media tools). Use apply_commands for everything else, batching related commands; look up a command's payload with get_command_schema the first time you use it.
+- Prefer the high-level tools when they fit (add_transition, animate_clip, add_effect, set_effects_enabled, set_background, trim_clip, set_keyframes, close_gaps, and any audio or media tools). Call tools directly; apply_commands takes only editing commands like "clip/add", never tool names. Use apply_commands for everything else, batching related commands; look up a command's payload with get_command_schema the first time you use it, and use only the fields it lists.
+- Fading a picture (text, image, logo, video) in or out is animate_clip (in / out: fade). fadeInUs / fadeOutUs are audio fades. "Fade the video in at the start / out at the end" means the first clip's entrance and the last clip's exit.
+- Constant values are set directly with clip/set-property: rotation ("rotate 45\xB0", "tilt"), volume ("lower to 30%", "louder"), position, size, opacity. Only values that CHANGE over a time range ("duck the music between 10 and 15 s", "fade to silence between 18 and 20 s", "spin one full turn", "pan across") are keyframes: set_keyframes, with times in timeline seconds. Remove an animation with keyframe/clear.
+- "Cuts" are the ones listed in the project summary; use their times (e.g. one sound per cut).
+- "Add N more seconds of footage" adds a new clip (clip/add with trimStartUs for the source point) after the last one; it does not stretch an existing clip.
+- Caption looks (box behind the text, outline, shadow, colors, word preset) are the caption clip's style (clip/set-property { style }).
+- "The whole video" means from 0 to the composition length (trim_clip startSeconds / endSeconds).
+- A solid color background behind everything is set_background (add, recolor, remove). Other html clips are recolored through the params their template uses (shown in the clip details). A new track goes on top unless track/add gets index 0 (the bottom).
+- "Replace X with Y" removes X and adds Y in the same turn, whichever tool adds Y (audio tools take replaceClipId, which does both).
+- Solo / mute / lock / hide a track with track/set-property (solo, muted, locked, hidden). "Solo X" is solo: true on X, not muting the others.
+- Relative requests ("bigger", "louder", "a bit brighter", "twice as big") start from the current values in the clip details below: make a visible change in the asked direction (about 25% for "bigger"/"smaller", \xD72 for "twice").
+- When something is selected, "this", "it", "the clip" and any request that names no target mean ONLY the selection, even with words like "at the end" (the end of that clip). Edit nothing else. "Here" / "now" / "this point" mean the playhead. "Clips" without a kind mean the video clips on the main video track.
+- "Again" / "also" / "another" mean keep the original and add a copy (clip/duplicate, or clip/add with the same asset); never move the original. "Instead" means move or replace.
+- Removing a clip leaves a gap; when asked to close it, also run close_gaps (or trim_clip with ripple).
 - Commands use integer microseconds (1 second = 1000000). High-level tools take seconds.
 - Positions (transform x, y) are fractions of the frame: 0.5, 0.5 is the center.
 - Only reference media that exists in the project or that a tool returned. Never invent file URLs.
-- If a tool fails, read the error, fix the input and retry. If something can't be done, say why.
+- If a tool fails, read the error, fix the input and retry. A failed apply_commands batch applied NONE of its commands: resend all of them, corrected. If something can't be done, say why.
 - If the request is ambiguous in a way that matters, ask one short question instead of guessing.
 
-When you're done, reply in one to three short sentences: what you changed, in plain words (times in seconds, names over ids). No markdown headings.`;
+When you're done, reply in one to three short sentences: what you changed, in plain words (times in seconds, names over ids). Describe only edits your tools reported as applied; if a tool says something changed nothing or failed, fix it or say so. No markdown headings.`;
 function createAssistant(options) {
   const tools = options.tools ?? editorTools();
   const byName = new Map(tools.map((t) => [t.name, t]));
@@ -632,8 +1235,9 @@ function createAssistant(options) {
         DEFAULT_INSTRUCTIONS,
         options.instructions?.trim(),
         `Current project:
-${(0, import_core3.describeProject)(fork.toJSON())}`,
-        turn.context?.trim() ? `What the user is looking at: ${turn.context.trim()}` : void 0
+${describeForAssistant(fork.toJSON())}`,
+        turn.context?.trim() ? `What the user is looking at: ${turn.context.trim()}` : void 0,
+        selectionNote(fork.toJSON(), fork.getState().selection)
       ].filter(Boolean).join("\n\n");
       let reply = "";
       let status = "no-changes";
@@ -760,6 +1364,12 @@ function abortError() {
   err.name = "AbortError";
   return err;
 }
+function selectionNote(doc, selection) {
+  const clips = selection.map((id) => doc.clips[id]).filter((c) => !!c);
+  if (!clips.length) return void 0;
+  const list = clips.map((c) => `${c.id} (${c.kind}, ${Number((c.startUs / 1e6).toFixed(2))}\u2013${Number(((c.startUs + c.durationUs) / 1e6).toFixed(2))}s)`).join(", ");
+  return `Selected: ${list}. In this request, "this", "it", "the clip" and anything that names no target mean ONLY ${clips.map((c) => c.id).join(", ")}. Leave every other clip alone.`;
+}
 
 // src/testing.ts
 function scriptedChatModel(steps, options = {}) {
@@ -775,7 +1385,7 @@ function scriptedChatModel(steps, options = {}) {
       i++;
       const s = typeof step === "string" ? { text: step } : step;
       if (s.text) opts.onText?.(s.text);
-      const toolCalls = (s.toolCalls ?? []).map((c, n) => ({ id: c.id ?? `call_${i}_${n}`, name: c.name, arguments: c.arguments }));
+      const toolCalls = (s.toolCalls ?? []).map((c, n2) => ({ id: c.id ?? `call_${i}_${n2}`, name: c.name, arguments: c.arguments }));
       return { content: s.text ?? "", toolCalls, finish: toolCalls.length ? "tool_calls" : "stop", usage: { inputTokens: 10, outputTokens: 5 } };
     }
   });