fablecut 1.13.0 → 1.14.0

package/mcp-server.js

@@ -21,7 +21,7 @@ const { spawn, spawnSync } = require("child_process");
 const { loadEncodeProfiles, listProfilesPublic, resolveProfile, profileSummary } = require("./encode-profiles");
 
 const {
-  APP_DIR, DATA_DIR, MEDIA_DIR, EXPORTS_DIR, ANALYSIS_DIR, LIBRARY_DIR, PROJECT_FILE, ensureDirs,
+  APP_DIR, DATA_DIR, MEDIA_DIR, EXPORTS_DIR, ANALYSIS_DIR, LIBRARY_DIR, PROJECT_FILE, ensureDirs, readSaved, writeSaved,
 } = require("./paths");
 const { downloadImportUrl, kindFromName, maybeFaststart } = require("./import-url");
 const FX = require("./audio-fx");
@@ -30,6 +30,11 @@ const Denoise = require("./denoise");
 const Color = require("./color");
 const Mask = require("./mask");
 const Tracker = require("./tracker");
+const Motion = require("./motion");
+const CompLib = require("./comp");
+const Templates = require("./templates");
+/** The user's saved presets / templates (library/presets, library/templates), validated; bad files skipped. */
+const savedItems = (kind) => readSaved(kind).map((x) => (kind === "presets" ? Templates.normalizePreset(x.data) : Templates.normalizeTemplate(x.data))).filter(Boolean);
 
 /* ROOT is where the code lives (server.js, CLAUDE.md); the user's timeline and
    media live under DATA_DIR. Identical unless FABLECUT_DATA_DIR is set. */
@@ -141,7 +146,7 @@ const TOOLS = [
   },
   {
     name: "fablecut_patch_project",
-    description: "Apply targeted edits to the FableCut project WITHOUT round-tripping the whole document — PREFER THIS over get+set for every edit (it is ~10-100x cheaper in tokens and merge-safe by design: it re-reads the latest document from disk, applies your ops in order, bumps revision once, saves atomically). Ops: {op:'addClip', clip:{…}} (id auto-generated if omitted) · {op:'updateClip', id, set:{…}} · {op:'removeClip', id} · {op:'addMedia', media:{…}} · {op:'removeMedia', id} · {op:'setProject', set:{name|width|height|fps|background|markers|disabledTracks|lockedTracks|untargetedTracks|encodeProfile|master}} (markers = the full list [{t, label?, color?}], color: gold|red|orange|green|cyan|blue|purple|pink; master = {gain}, the master fader in dB) · {op:'setTrack', id:'A1', set:{gain?, pan?, out?}} (audio-track fader in dB −60…+12, pan −1…1, out = a submix bus id or 'master'; null or 0 resets) · {op:'setBus', id:'B1', set:{name?, gain?, pan?, mute?}} (submix bus, created if missing; route tracks into it with setTrack out) · {op:'removeBus', id} · {op:'setFx', target:'clip'|'track'|'bus'|'master', id?, preset?:'podcast'|… OR fx:[{type,…params}], append?:true} (audio effects — validated; presets: clean-voice, podcast, radio, deep-voice, telephone, cinematic, wide, muffled; fx:null clears; on a clip it applies to its linked stems too) · {op:'setFxKeys', target, id?, index?|type?, param, keys:[{t, v, ease?}]|null} (automate one effect parameter: t is clip-local for a clip's effects, timeline seconds otherwise; see the 'Audio mix' docs section) · {op:'setGrade', id | ids:[…], grade:{exposure?, temp?, tint?, lift?, gamma?, gain?, offset?, contrast?, pivot?, blacks?, shadows?, midtones?, highlights?, whites?, lowSoft?, highSoft?, saturation?, curves?:{y?, r?, g?, b?}, hueHue?, hueSat?, hueLuma?, satLuma?, layers?:[…], on?}, replace?:true} (color grade on video / image / svg / adjust clips — wheels are [r, g, b, master]; curves are [[x, y], …] point lists on 0…1 and merge per channel; hue curves are [[hue°, value], …] — one point = a ±40° band; layers replaces the whole layer list; merges key by key, null resets a key, replace:true starts from neutral, grade:null clears; see the 'Color' docs section; measure the result with fablecut_scopes) · {op:'setGradeLayer', id | ids, layer: index | 'name', set:{name?, on?, qualifier?:{hue?:[centre°, width°, soft°], sat?:[lo, hi, soft], luma?:[lo, hi, soft], invert?}, mask?:{shape:'ellipse'|'rect'|'poly', x, y, w, h, rotation?, feather?, invert?, points?, keys?:[{t, x?, y?, …}]}, …any grade key}, replace?:true, remove?:true} (a secondary: a grade applied only where the qualifier × mask select; a new name or index = length adds a layer; qualifier and mask merge key by key; check what it selects with fablecut_scopes matte:{clip, layer}) · {op:'setMask', id | ids, mask?: index | 'name', set:{shape?:'rect'|'ellipse'|'bezier'|'freehand', mode?:'add'|'subtract'|'intersect'|'difference', invert?, opacity?, feather? (px), expand? (px, − shrinks), x?, y? (centre, 0…1 of the clip's picture), w?, h?, scale?, rotation?, points?:[[dx, dy, inX?, inY?, outX?, outY?], …] (bezier, around x, y), stroke?:[[u, v], …] (freehand: fitted into a bezier), keys?:[{t, ease?, x?, y?, w?, h?, scale?, rotation?, feather?, expand?, opacity?, points?}], name?, on?}, replace?:true, remove?:true} (clip masks on video / image / svg / text / adjust clips: the clip shows only where its masks combine to, bottom-up; mask left out, an unknown name or index = length adds one — a new mask needs shape; set merges key by key; masks follow the clip's transform; check with fablecut_scopes mask:{clip}) · {op:'removeMask', id, mask} · {op:'setMaskKeys', id, mask, keys:[…]|null} (animate a mask; t = seconds from the clip's start) · {op:'setMatte', id | ids, matte:'alpha'|'alpha-inverted'|'luma'|'luma-inverted'|null, track?:'V3'|null} (track matte: the picture on the video track directly above — or track — cuts the clip by its alpha or its brightness, inverted or not; that track stops drawing while it is a matte; null clears). · {op:'removeTrack', id, track: name | index} (delete a motion track stored by fablecut_track; what follows it keeps its keys). props.blend: normal · multiply · screen · overlay · darken · lighten · color-dodge · color-burn · hard-light · soft-light · difference · exclusion · hue · saturation · color · luminosity · lighter. TIMELINE EDITS — the editor's own split / ripple / trim code, so linked stems, track targeting (untargetedTracks) and locks behave exactly as in the UI; times in seconds: {op:'split', at, ids?} (no ids: every targeted track) · {op:'rippleDelete', ids} (later clips close the hole) · {op:'closeGap', at} · {op:'lift'|'extract', from?, to?} (remove a range; extract closes it; default = project inPoint/outPoint, which then clear) · {op:'insert'|'overwrite', mediaId, at, in?, duration?} (three-point edit: insert pushes later clips right, overwrite replaces what is there; a video brings one audio stem per channel) · {op:'rippleTrim'|'roll', id, side:'in'|'out', delta} · {op:'slip'|'slide', id, delta} (clamped to the media; the note says what was applied) · {op:'crossfade', ids? | at, duration?} (constant-power audio crossfade, borrowing handles from both sides). Any of these takes tracks:[…] to target lanes for that op only. setProject also takes inPoint / outPoint. updateClip merge rules: top-level keys are replaced (keyframes/transitionIn/transitionOut wholesale), `props` merges key-by-key, and setting any key to null deletes it. LOCKS: the user can lock clips (`locked:true`) and tracks (`lockedTracks`); updateClip / removeClip on a locked clip — or on a clip linked to one — and addClip onto a locked track are refused. Leave locked material alone; only if the user asked you to change it, pass force:true on that op (or unlock first: updateClip set:{locked:null}, which is always allowed). All-or-nothing: an invalid op aborts the whole patch unsaved. Optional baseRevision: the revision your ops were planned against (from fablecut_get_project, fablecut_status or the previous patch result) — if the project has moved past it (e.g. the user edited in the UI meanwhile), the patch is refused with CONFLICT and the current revision, nothing saved; re-check the clips you touch, then retry with the new revision. Omit it to apply on top of whatever is latest.",
+    description: "Apply targeted edits to the FableCut project WITHOUT round-tripping the whole document — PREFER THIS over get+set for every edit (it is ~10-100x cheaper in tokens and merge-safe by design: it re-reads the latest document from disk, applies your ops in order, bumps revision once, saves atomically). Ops: {op:'addClip', clip:{…}} (id auto-generated if omitted) · {op:'updateClip', id, set:{…}} · {op:'removeClip', id} · {op:'addMedia', media:{…}} · {op:'removeMedia', id} · {op:'setProject', set:{name|width|height|fps|background|markers|disabledTracks|lockedTracks|untargetedTracks|encodeProfile|master}} (markers = the full list [{t, label?, color?}], color: gold|red|orange|green|cyan|blue|purple|pink; master = {gain}, the master fader in dB) · {op:'setTrack', id:'A1', set:{gain?, pan?, out?}} (audio-track fader in dB −60…+12, pan −1…1, out = a submix bus id or 'master'; null or 0 resets) · {op:'setBus', id:'B1', set:{name?, gain?, pan?, mute?}} (submix bus, created if missing; route tracks into it with setTrack out) · {op:'removeBus', id} · {op:'setFx', target:'clip'|'track'|'bus'|'master', id?, preset?:'podcast'|… OR fx:[{type,…params}], append?:true} (audio effects — validated; presets: clean-voice, podcast, radio, deep-voice, telephone, cinematic, wide, muffled; fx:null clears; on a clip it applies to its linked stems too) · {op:'setFxKeys', target, id?, index?|type?, param, keys:[{t, v, ease?}]|null} (automate one effect parameter: t is clip-local for a clip's effects, timeline seconds otherwise; see the 'Audio mix' docs section) · {op:'setGrade', id | ids:[…], grade:{exposure?, temp?, tint?, lift?, gamma?, gain?, offset?, contrast?, pivot?, blacks?, shadows?, midtones?, highlights?, whites?, lowSoft?, highSoft?, saturation?, curves?:{y?, r?, g?, b?}, hueHue?, hueSat?, hueLuma?, satLuma?, layers?:[…], on?}, replace?:true} (color grade on video / image / svg / adjust clips — wheels are [r, g, b, master]; curves are [[x, y], …] point lists on 0…1 and merge per channel; hue curves are [[hue°, value], …] — one point = a ±40° band; layers replaces the whole layer list; merges key by key, null resets a key, replace:true starts from neutral, grade:null clears; see the 'Color' docs section; measure the result with fablecut_scopes) · {op:'setGradeLayer', id | ids, layer: index | 'name', set:{name?, on?, qualifier?:{hue?:[centre°, width°, soft°], sat?:[lo, hi, soft], luma?:[lo, hi, soft], invert?}, mask?:{shape:'ellipse'|'rect'|'poly', x, y, w, h, rotation?, feather?, invert?, points?, keys?:[{t, x?, y?, …}]}, …any grade key}, replace?:true, remove?:true} (a secondary: a grade applied only where the qualifier × mask select; a new name or index = length adds a layer; qualifier and mask merge key by key; check what it selects with fablecut_scopes matte:{clip, layer}) · {op:'setMask', id | ids, mask?: index | 'name', set:{shape?:'rect'|'ellipse'|'bezier'|'freehand', mode?:'add'|'subtract'|'intersect'|'difference', invert?, opacity?, feather? (px), expand? (px, − shrinks), x?, y? (centre, 0…1 of the clip's picture), w?, h?, scale?, rotation?, points?:[[dx, dy, inX?, inY?, outX?, outY?], …] (bezier, around x, y), stroke?:[[u, v], …] (freehand: fitted into a bezier), keys?:[{t, ease?, x?, y?, w?, h?, scale?, rotation?, feather?, expand?, opacity?, points?}], name?, on?}, replace?:true, remove?:true} (clip masks on video / image / svg / text / adjust clips: the clip shows only where its masks combine to, bottom-up; mask left out, an unknown name or index = length adds one — a new mask needs shape; set merges key by key; masks follow the clip's transform; check with fablecut_scopes mask:{clip}) · {op:'removeMask', id, mask} · {op:'setMaskKeys', id, mask, keys:[…]|null} (animate a mask; t = seconds from the clip's start) · {op:'setMatte', id | ids, matte:'alpha'|'alpha-inverted'|'luma'|'luma-inverted'|null, track?:'V3'|null} (track matte: the picture on the video track directly above — or track — cuts the clip by its alpha or its brightness, inverted or not; that track stops drawing while it is a matte; null clears). · {op:'removeTrack', id, track: name | index} (delete a motion track stored by fablecut_track; what follows it keeps its keys). MOTION GRAPHICS: a shape layer is addClip {kind:'shape', track, start, duration, props:{shapes:[…]}} (no mediaId); a null is addClip {kind:'null', …} — invisible, a parent for other clips. {op:'setShape', id | ids, shape?: index | 'name' | '2.0' (path into a group), set:{type?:'rect'|'ellipse'|'polygon'|'star'|'line'|'path'|'group', name?, on?, x?, y? (px from the layer's origin), rotation?, scale?, opacity?, w?, h?, radius? (rect corners), sides?, inner? (star 0.05…1), points?:[[x, y, inX?, inY?, outX?, outY?], …] (line: 2, path: 2…128, px around x, y), closed? (path), fill?, stroke? ('#rrggbb' | '#rrggbbaa' | 'none'), strokeWidth?, lineCap?, lineJoin?, dash?:[on, off…], trimStart?, trimEnd? (0…100 — a draw-on), trimOffset?, items?:[…] (group), keys?:[{t, ease?, …any of x y rotation scale opacity w h radius inner strokeWidth trimStart trimEnd trimOffset fill stroke points}]}, replace?:true, remove?:true} (shape left out, an unknown name or index = length adds one — a new shape needs type; set merges key by key) · {op:'removeShape', id, shape} · {op:'setParent', id | ids, parent: clip id | null, keep?: true, at?} (the clip moves, turns and scales with its parent; keep:true — the default — keeps it where it is at time at, default its start; opacity and effects are not inherited). COMPOSITIONS (nested sequences): project.comps = [{id, name, width, height, duration, background?, tracks?, clips:[…]}]; a clip {kind:'comp', compId, start, in, duration} places one (draws like a picture of the comp's size — transform, masks, grade, blend, blur all apply — and its media plays and exports). {op:'addComp', comp:{id?, name, duration, width?, height?, background?, clips?:[…]}} · {op:'updateComp', id, set:{name?, width?, height?, duration?, background?, tracks?}} · {op:'removeComp', id} (refused while used) · {op:'precompose', ids:[…], name?, id?} (the clips move into a new comp; a comp clip takes their place) · {op:'inComp', comp, ops:[…]} (run clip and timeline ops on the comp's own clips — addClip, updateClip, setShape, split, …; nests). PRESETS AND TEMPLATES: {op:'applyPreset', id | ids, preset, length?, at?} keys a named animation onto visual clips, relative to where they sit (in: fade-in, pop-in, slide-up-in, slide-down-in, slide-left-in, slide-right-in, drop-in, zoom-in, spin-in, whip-in, rise-blur, draw-on · out: fade-out, pop-out, slide-up-out, slide-down-out, slide-left-out, slide-right-out, zoom-out, spin-out, whip-out, sink-blur, draw-off · at (an emphasis at timeline time at): pulse, shake, wobble, bounce, flash · loop (the whole clip): float, breathe, sway, spin, wiggle — or a saved one, or an inline {anchor:'in'|'out'|'at'|'whole', length, keys:{channel:[{t, v, ease?}]}} where scale / opacity multiply and the rest add). {op:'addTemplate', template, start?, track?, duration?, fields?:{key: value}, id?, compId?, name?} places a template as its own comp + a comp clip (lower-third-bar, lower-third-underline, lower-third-boxes [name, title, accent…] · logo-ring, logo-slam, logo-lines [logo = a media id, brand / tagline, accent] · social-story 1080x1920, social-quote 1080x1080, social-end-card [text fields, accent, background]); {op:'setTemplate', id: its clip or comp, fields?, duration?} changes the fields or the length (the exit keeps its timing). {op:'savePreset', id, name, anchor?} / {op:'saveTemplate', comp, name?, fields?} save to library/presets and library/templates for every project.MOTION PATHS: x and y keyed at the same time are a position key; curve handles pin / pout (px) on those x and y keys bend the path between keys ({op:'setMotionPath', id | ids, path:'smooth'|'straight', autoOrient?:bool} sets them for you; props.autoOrient turns the clip along its path). props.motionBlur = shutter angle 0…720 (180 = film look), props.motionBlurSamples 2…32. TEXT ON A PATH: {op:'setTextPath', id | ids, path:'line'|'arc'|'circle'|'wave'|{type:'path'|'line'|'ellipse'|'rect'|'polygon'|'star', …shape item geometry, keys?}|null, offset? (% along, keyable as pathOffset), align?:'start'|'center'|'end'} — the title runs along the path (more lines on parallel curves below it), every textAnim plays along it. Every visual clip also has props.anchorX / anchorY (px from its picture's centre: the point x / y place and rotation / scale turn around) and shape clips props.trimStart / trimEnd / trimOffset (trim every path in the layer) — all keyframable. props.blend: normal · multiply · screen · overlay · darken · lighten · color-dodge · color-burn · hard-light · soft-light · difference · exclusion · hue · saturation · color · luminosity · lighter. TIMELINE EDITS — the editor's own split / ripple / trim code, so linked stems, track targeting (untargetedTracks) and locks behave exactly as in the UI; times in seconds: {op:'split', at, ids?} (no ids: every targeted track) · {op:'rippleDelete', ids} (later clips close the hole) · {op:'closeGap', at} · {op:'lift'|'extract', from?, to?} (remove a range; extract closes it; default = project inPoint/outPoint, which then clear) · {op:'insert'|'overwrite', mediaId, at, in?, duration?} (three-point edit: insert pushes later clips right, overwrite replaces what is there; a video brings one audio stem per channel) · {op:'rippleTrim'|'roll', id, side:'in'|'out', delta} · {op:'slip'|'slide', id, delta} (clamped to the media; the note says what was applied) · {op:'crossfade', ids? | at, duration?} (constant-power audio crossfade, borrowing handles from both sides). Any of these takes tracks:[…] to target lanes for that op only. setProject also takes inPoint / outPoint. updateClip merge rules: top-level keys are replaced (keyframes/transitionIn/transitionOut wholesale), `props` merges key-by-key, and setting any key to null deletes it. LOCKS: the user can lock clips (`locked:true`) and tracks (`lockedTracks`); updateClip / removeClip on a locked clip — or on a clip linked to one — and addClip onto a locked track are refused. Leave locked material alone; only if the user asked you to change it, pass force:true on that op (or unlock first: updateClip set:{locked:null}, which is always allowed). All-or-nothing: an invalid op aborts the whole patch unsaved. Optional baseRevision: the revision your ops were planned against (from fablecut_get_project, fablecut_status or the previous patch result) — if the project has moved past it (e.g. the user edited in the UI meanwhile), the patch is refused with CONFLICT and the current revision, nothing saved; re-check the clips you touch, then retry with the new revision. Omit it to apply on top of whatever is latest.",
     inputSchema: {
       type: "object",
       properties: {
@@ -805,6 +810,8 @@ async function callTool(name, args, attempt = 0) {
         letterSpacing: 0, lineHeight: 1.2, textShadow: 12, glow: 0, glowColor: "",
         strokeWidth: 0, strokeColor: "#000", bgColor: "#000", bgOpacity: 0,
         textAnim: "none", wordRate: 0.15, direction: "auto", boxW: 0, boxH: 0, boxFit: false, vAlign: "middle",
+        anchorX: 0, anchorY: 0, trimStart: 0, trimEnd: 100, trimOffset: 0,
+        autoOrient: false, motionBlur: 0, motionBlurSamples: 8, pathOffset: 0, pathAlign: "start",
       };
       const hex = (v) => typeof v === "string" && /^#[0-9a-f]{3}$/i.test(v)
         ? "#" + [...v.slice(1)].map((c) => c + c).join("").toLowerCase()
@@ -820,11 +827,14 @@ async function callTool(name, args, attempt = 0) {
             kept[k] = v;
             continue;
           }
-          if (k === "masks" || k === "tracks") continue;   // summarized below — point lists and samples are long
+          if (k === "masks" || k === "tracks" || k === "shapes" || k === "textPath") continue;   // summarized below — point lists and samples are long
           if (hex(DEFAULTS[k]) !== hex(v)) kept[k] = v;
         }
         const masks = Mask.describe(Mask.normalizeMasks(o.masks)), tracks = Tracker.describe(Tracker.normalizeTracks(o.tracks));
-        return (Object.keys(kept).length ? " " + JSON.stringify(kept) : "") + (masks ? ` [${masks}]` : "") + (tracks ? ` [tracks: ${tracks}]` : "");
+        const shapes = Motion.describe(Motion.normalizeShapes(o.shapes));
+        const tp = o.textPath && Motion.normalizeTextPath(o.textPath);
+        if (tp) kept.textPath = tp.type + (tp.points ? `(${tp.points.length})` : tp.w ? ` ${tp.w}×${tp.h}` : "");
+        return (Object.keys(kept).length ? " " + JSON.stringify(kept) : "") + (shapes ? ` [${shapes}]` : "") + (masks ? ` [${masks}]` : "") + (tracks ? ` [tracks: ${tracks}]` : "");
       };
       // Mixer: only off-default faders / pans, so a fresh project adds no line.
       const signed = (v) => (v > 0 ? "+" : "") + v;
@@ -858,16 +868,29 @@ async function callTool(name, args, attempt = 0) {
           .slice()
           .sort((a, b) => (a.track === b.track ? a.start - b.start : String(a.track).localeCompare(b.track)))
           .map((c) => {
-            const kf = c.keyframes ? " kf:" + Object.entries(c.keyframes).map(([k, v]) => `${k}(${v.length})`).join(",") : "";
+            const kf = c.keyframes ? " kf:" + Object.entries(c.keyframes).map(([k, v]) => `${k}(${v.length})`).join(",") +
+              (Motion.hasPathHandles(c) ? " path:curved" : "") : "";
             const tr = (c.transitionIn ? ` in:${c.transitionIn.type}/${c.transitionIn.duration}` : "") +
                        (c.transitionOut ? ` out:${c.transitionOut.type}/${c.transitionOut.duration}` : "");
             const r3 = (n) => Math.round(n * 1000) / 1000;
             return `  ${c.id} ${c.track} ${r3(c.start)}s+${r3(c.duration)}s ${c.kind}` +
               (c.mediaId ? `(${c.mediaId}${c.in ? ` in:${r3(c.in)}` : ""})` : "") +
-              (c.name ? ` "${c.name}"` : "") + fmtProps(c.props, c.kind) + kf + tr +
+              (c.kind === "comp" ? `(${c.compId}${c.in ? ` in:${r3(c.in)}` : ""})` : "") +
+              (c.name ? ` "${c.name}"` : "") + (c.parent ? ` parent:${c.parent}` : "") + fmtProps(c.props, c.kind) + kf + tr +
               (c.locked === true ? " [locked]" : "") + (c.disabled === true ? " [disabled]" : "") +
               (c.unlinked === true ? " [unlinked]" : "") + fxTag(c.fx);
           }),
+        ...(Array.isArray(doc.comps) && doc.comps.length ? [`COMPS (${doc.comps.length}) — edit their clips with {op:"inComp", comp, ops:[…]}:`,
+          ...doc.comps.flatMap((comp) => [`  ${CompLib.describe(comp)}`,
+            ...(comp.template ? [`    template ${comp.template.id} — fields (setTemplate): ` + (comp.template.fields || []).map((f) => {
+              const v = Templates.fieldValue(comp, f);
+              return `${f.key}=${typeof v === "string" ? JSON.stringify(v.length > 40 ? v.slice(0, 40) + "…" : v) : v}`;
+            }).join(" ")] : []),
+            ...(comp.clips || []).slice().sort((a, b) => a.start - b.start).map((c) => {
+            const r3 = (n) => Math.round(n * 1000) / 1000;
+            return `    ${c.id} ${c.track} ${r3(c.start)}s+${r3(c.duration)}s ${c.kind}` + (c.mediaId ? `(${c.mediaId})` : "") + (c.kind === "comp" ? `(${c.compId})` : "") +
+              (c.name ? ` "${c.name}"` : "") + (c.parent ? ` parent:${c.parent}` : "") + fmtProps(c.props, c.kind);
+          })])] : []),
         `(compact view — full JSON: fablecut_get_project without compact; edit via fablecut_patch_project)`,
       ];
       return lines.join("\n");
@@ -888,6 +911,8 @@ async function callTool(name, args, attempt = 0) {
         `or omit baseRevision to apply on top of the latest anyway.`);
       if (base != null && readRev !== base) throw conflict(readRev);
       const notes = [];
+      const toSave = [];   // [kind, item] — presets / templates written to the library once the project is saved
+      const savedList = (kind) => [...savedItems(kind), ...toSave.filter((x) => x[0] === kind).map((x) => x[1])];
       // Locks mirror the editor: a clip is locked by its own flag or its track,
       // and a linked A/V group with any locked member is locked as a whole.
       const lockedTracks = () => new Set(Array.isArray(proj.lockedTracks) ? proj.lockedTracks : []);
@@ -965,6 +990,50 @@ async function callTool(name, args, attempt = 0) {
         try { n = Tracker.normalizeTracks(c.props.tracks, true); } catch (err) { throw new Error(`${label}: props.${err.message}`); }
         if (n) c.props.tracks = n; else delete c.props.tracks;
       };
+      // props.shapes (shape layers) and clip.parent: validated like setShape / setParent
+      const NO_MEDIA = ["text", "adjust", "shape", "null", "comp"];
+      let inCompId = null;   // set while an inComp op runs its ops inside a comp
+      // a comp clip names a comp that exists, and placing it here makes no loop
+      const checkCompClip = (c, label) => {
+        if (c.kind !== "comp") { if (c.compId != null) throw new Error(`${label}: compId is for kind:"comp" clips`); return; }
+        if (typeof c.compId !== "string" || !CompLib.getComp(proj, c.compId))
+          throw new Error(`${label}: compId must name a comp in project.comps${(proj.comps || []).length ? ` (${proj.comps.map((x) => x.id).join(", ")})` : " — add one with addComp"}`);
+        if (CompLib.wouldCycle(proj, inCompId, c.compId)) throw new Error(`${label}: comp ${c.compId} can't go inside ${inCompId} — that would contain itself`);
+        c.props = c.props || {};
+        if (c.props.fit == null) c.props.fit = "none";   // a comp shows at its own size unless told otherwise
+        if (c.in == null) c.in = 0;
+      };
+      const checkShapes = (c, label) => {
+        if (!c.props || c.props.shapes == null) return;
+        if (c.kind !== "shape") throw new Error(`${label}: shapes go on shape clips (kind:"shape")`);
+        let n;
+        try { n = Motion.normalizeShapes(c.props.shapes, true); } catch (err) { throw new Error(`${label}: props.${err.message}`); }
+        if (n) c.props.shapes = n; else delete c.props.shapes;
+      };
+      const byId = (id) => proj.clips.find((x) => x.id === id) || null;
+      // motion blur, auto-orient, text paths and motion-path handles (pin / pout on x / y keys)
+      const checkMotion = (c, label) => {
+        const p = c.props || {};
+        if (p.motionBlur != null && !(typeof p.motionBlur === "number" && p.motionBlur >= 0 && p.motionBlur <= 720)) throw new Error(`${label}: props.motionBlur is a shutter angle 0…720 (0 = off)`);
+        if (p.motionBlurSamples != null && !(Number.isInteger(p.motionBlurSamples) && p.motionBlurSamples >= 2 && p.motionBlurSamples <= 32)) throw new Error(`${label}: props.motionBlurSamples is a whole number 2…32`);
+        if (p.autoOrient != null && typeof p.autoOrient !== "boolean") throw new Error(`${label}: props.autoOrient is true or false`);
+        if (p.pathAlign != null && !["start", "center", "end"].includes(p.pathAlign)) throw new Error(`${label}: props.pathAlign is start | center | end`);
+        if (p.textPath != null) {
+          if (c.kind !== "text") throw new Error(`${label}: textPath goes on text clips`);
+          try { p.textPath = Motion.normalizeTextPath(p.textPath, true); } catch (err) { throw new Error(`${label}: props.${err.message}`); }
+        }
+        for (const ch of ["x", "y"]) for (const k of (c.keyframes && Array.isArray(c.keyframes[ch]) ? c.keyframes[ch] : []))
+          for (const h of ["pin", "pout"]) if (k && k[h] != null && !(typeof k[h] === "number" && Number.isFinite(k[h])))
+            throw new Error(`${label}: keyframes.${ch} ${h} must be a number (px, the motion path's curve handle)`);
+      };
+      const checkParent = (c, label) => {
+        if (c.parent == null) { delete c.parent; return; }
+        const par = typeof c.parent === "string" && byId(c.parent);
+        if (!par) throw new Error(`${label}: parent ${JSON.stringify(c.parent)} is not a clip`);
+        if (par.id === c.id || Motion.wouldCycle(c.id, par.id, byId)) throw new Error(`${label}: parenting ${c.id} to ${par.id} makes a loop`);
+        if (par.kind === "audio" || par.kind === "adjust" || c.kind === "audio" || c.kind === "adjust")
+          throw new Error(`${label}: parenting is for visual clips (video, image, svg, text, shape, null)`);
+      };
       // blend / matte / matteTrack: checked when the op writes them
       const videoTrackIds = () => {
         const ids = (Array.isArray(proj.tracks) && proj.tracks.length ? proj.tracks : DEFAULT_TRACKS).filter((t) => t.kind === "video").map((t) => t.id);
@@ -977,7 +1046,7 @@ async function callTool(name, args, attempt = 0) {
         try { Mask.checkCompositing(c.props, videoTrackIds(), c.track, true); } catch (err) { throw new Error(`${label}: props.${err.message}`); }
         if (!c.props.matte) delete c.props.matteTrack;
       };
-      for (const op of ops) {
+      const applyOps = (opList) => { for (const op of opList) {
         switch (op.op) {
           case "addClip": {
             const c = op.clip;
@@ -986,9 +1055,14 @@ async function callTool(name, args, attempt = 0) {
             c.id = c.id || "c_" + uid();
             if (proj.clips.some((x) => x.id === c.id)) throw new Error("addClip: duplicate clip id " + c.id);
             refuseLocked("addClip", lockedTracks().has(c.track) ? `track ${c.track} is locked` : null, op);
-            if (c.kind !== "text" && c.kind !== "adjust" && !proj.media.some((m) => m.id === c.mediaId))
+            if (!NO_MEDIA.includes(c.kind) && !proj.media.some((m) => m.id === c.mediaId))
               throw new Error(`addClip: unknown mediaId ${c.mediaId}`);
+            if (NO_MEDIA.includes(c.kind)) c.mediaId = null;
             checkMasks(c, "addClip");
+            checkShapes(c, "addClip");
+            checkParent(c, "addClip");
+            checkMotion(c, "addClip");
+            checkCompClip(c, "addClip");
             checkTracks(c, "addClip");
             checkCompositing(c, "addClip", c.props);
             proj.clips.push(c);
@@ -1008,6 +1082,10 @@ async function callTool(name, args, attempt = 0) {
             mergeInto(c, op.set);
             checkMasks(c, "updateClip");
             if (op.set && op.set.props && "tracks" in op.set.props) checkTracks(c, "updateClip");
+            if (op.set && op.set.props && "shapes" in op.set.props) checkShapes(c, "updateClip");
+            if (op.set && "parent" in op.set) checkParent(c, "updateClip");
+            checkMotion(c, "updateClip");
+            if (op.set && ("compId" in op.set || "kind" in op.set)) checkCompClip(c, "updateClip");
             // a track move re-checks the matte too (a clip can't be its own matte)
             checkCompositing(c, "updateClip", op.set && op.set.track ? c.props : op.set && op.set.props);
             if (c.props && c.props.matteTrack && !c.props.matte) delete c.props.matteTrack;   // matte:null clears its track too
@@ -1018,6 +1096,10 @@ async function callTool(name, args, attempt = 0) {
             const doomed = proj.clips.find((x) => x.id === op.id);
             if (doomed) refuseLocked("removeClip", lockReason(doomed), op);
             const n = proj.clips.length;
+            // its children stay where they are (at their own start), under its own parent if it has one
+            const kids = doomed ? proj.clips.filter((x) => x.parent === op.id).map((x) => x.id) : [];
+            if (doomed) EditOps.detachChildren(proj, new Set([op.id]));
+            for (const id of kids) notes.push(`~${id}.parent(${byId(id).parent || "none"})`);
             proj.clips = proj.clips.filter((x) => x.id !== op.id);
             if (proj.clips.length === n) throw new Error("removeClip: no clip " + op.id);
             notes.push("-" + op.id);
@@ -1036,6 +1118,10 @@ async function callTool(name, args, attempt = 0) {
           case "removeMedia": {
             const used = proj.clips.find((c) => c.mediaId === op.id);
             if (used) throw new Error(`removeMedia: media ${op.id} is used by clip ${used.id}`);
+            for (const comp of proj.comps || []) {
+              const inner = (comp.clips || []).find((c) => c.mediaId === op.id);
+              if (inner) throw new Error(`removeMedia: media ${op.id} is used by clip ${inner.id} in comp ${comp.id}`);
+            }
             const n = proj.media.length;
             proj.media = proj.media.filter((x) => x.id !== op.id);
             if (proj.media.length === n) throw new Error("removeMedia: no media " + op.id);
@@ -1172,6 +1258,315 @@ async function callTool(name, args, attempt = 0) {
             }
             break;
           }
+          case "setShape":
+          case "removeShape": {
+            // {op:"setShape", id | ids, shape?: index | "name" | "2.0" (group path), set:{…}, replace?:true, remove?:true}
+            const name = op.op;
+            const ids = Array.isArray(op.ids) ? op.ids : op.id != null ? [op.id] : [];
+            if (!ids.length) throw new Error(`${name} needs id or ids`);
+            const remove = name === "removeShape" || op.remove === true;
+            if (remove && op.shape == null) throw new Error(`${name} needs shape: an index, a name or a path like "2.0"`);
+            if (!remove && (op.set == null || typeof op.set !== "object" || Array.isArray(op.set))) throw new Error("setShape needs set:{type?, x?, y?, w?, h?, fill?, …} (or remove:true)");
+            const isPath = (v) => Array.isArray(v) || (typeof v === "string" && /^\d+(\.\d+)*$/.test(v.trim()));
+            for (const id of ids) {
+              const c = byId(id);
+              if (!c) throw new Error(`${name}: no clip ${id}`);
+              if (c.kind !== "shape") throw new Error(`${name}: ${id} is a ${c.kind} clip — shapes go on shape clips (addClip kind:"shape")`);
+              refuseLocked(name, lockReason(c), op);
+              const where = `${name}: ${id}`;
+              let list = (Motion.normalizeShapes(c.props?.shapes) || []).slice();
+              // the target as a path [i, j…]; its last index may be one past the end (= add there)
+              let path, named = null;
+              if (op.shape == null) path = [list.length];
+              else if (Number.isInteger(op.shape) && op.shape >= 0) path = [op.shape];
+              else if (isPath(op.shape)) path = (Array.isArray(op.shape) ? op.shape : op.shape.trim().split(".")).map(Number);
+              else if (typeof op.shape === "string" && op.shape.trim()) {
+                path = Motion.itemPaths(list).find((q) => Motion.getItem(list, q).name === op.shape.trim());
+                if (!path) { if (remove) throw new Error(`${where} has no shape named ${JSON.stringify(op.shape)}`); path = [list.length]; named = op.shape.trim(); }
+              } else throw new Error(`${name}: shape is an index (0 = first), a name or a path like "2.0"`);
+              if (path.some((i) => !Number.isInteger(i) || i < 0)) throw new Error(`${name}: bad shape path ${JSON.stringify(op.shape)}`);
+              const parentPath = path.slice(0, -1), last = path[path.length - 1];
+              const group = parentPath.length ? Motion.getItem(list, parentPath) : null;
+              if (parentPath.length && (!group || group.type !== "group")) throw new Error(`${where}: ${parentPath.join(".")} is not a group`);
+              const siblings = group ? group.items : list;
+              const it = siblings[last];
+              if (remove) {
+                if (!it) throw new Error(`${where} has no shape ${JSON.stringify(op.shape)}${list.length ? ` (it has ${Motion.describe(list)})` : ""}`);
+                list = Motion.updateItem(list, path, () => null);
+              } else if (!it) {
+                if (last !== siblings.length) throw new Error(`${where}: ${parentPath.length ? `group ${parentPath.join(".")}` : "the layer"} has ${siblings.length} item(s) — use index ${siblings.length} (or leave shape out) to add one`);
+                if (!op.set.type) throw new Error(`${where}: a new shape needs set.type (${Motion.TYPES.join(" | ")})`);
+                let next;
+                try { next = Motion.normalizeItem({ ...op.set, ...(named && !op.set.name ? { name: named } : {}) }, true, "shape"); }
+                catch (err) { throw new Error(`${where}: ${err.message}`); }
+                list = group ? Motion.updateItem(list, parentPath, (g) => ({ ...g, items: [...g.items, next] })) : [...list, next];
+              } else {
+                let next;
+                const base = op.replace ? { type: it.type, name: it.name, ...(it.type === "group" ? { items: it.items } : {}) } : it;
+                try { next = Motion.mergeItem(base, op.set, true); }
+                catch (err) { throw new Error(`${where}: ${err.message}`); }
+                list = Motion.updateItem(list, path, () => next);
+              }
+              let n;
+              try { n = Motion.normalizeShapes(list, true); } catch (err) { throw new Error(`${where}: ${err.message}`); }
+              c.props = c.props || {};
+              if (n) c.props.shapes = n; else delete c.props.shapes;
+              notes.push(`~${id}.shapes(${Motion.describe(n) || "none"})`);
+            }
+            break;
+          }
+          case "setParent": {
+            // {op:"setParent", id | ids, parent: "c_…" | null, keep?: true, at?: seconds}
+            const ids = Array.isArray(op.ids) ? op.ids : op.id != null ? [op.id] : [];
+            if (!ids.length) throw new Error("setParent needs id or ids");
+            if (op.parent !== null && typeof op.parent !== "string") throw new Error("setParent needs parent: a clip id (or null to unparent)");
+            if (op.at != null && typeof op.at !== "number") throw new Error("setParent: at is a timeline time in seconds");
+            for (const id of ids) {
+              const c = byId(id);
+              if (!c) throw new Error("setParent: no clip " + id);
+              refuseLocked("setParent", lockReason(c), op);
+              const prev = c.parent;
+              c.parent = op.parent;
+              try { checkParent(c, `setParent: ${id}`); } finally { if (prev) c.parent = prev; else delete c.parent; }
+              if (op.keep !== false) {
+                const t = op.at != null ? Math.min(Math.max(op.at, c.start), c.start + c.duration) : c.start;
+                const v = Motion.reparentValues(c, op.parent, byId, t);
+                c.props = c.props || {};
+                for (const [k, val] of Object.entries(v)) if (!c.keyframes?.[k]?.length) c.props[k] = val;
+              }
+              if (op.parent) c.parent = op.parent; else delete c.parent;
+              notes.push(`~${id}.parent(${op.parent || "none"})`);
+            }
+            break;
+          }
+          case "setMotionPath": {
+            // {op:"setMotionPath", id | ids, path?: "smooth" | "straight", autoOrient?: bool}
+            const ids = Array.isArray(op.ids) ? op.ids : op.id != null ? [op.id] : [];
+            if (!ids.length) throw new Error("setMotionPath needs id or ids");
+            if (op.path != null && !["smooth", "straight"].includes(op.path)) throw new Error('setMotionPath: path is "smooth" (curve through the position keys) or "straight"');
+            if (op.autoOrient != null && typeof op.autoOrient !== "boolean") throw new Error("setMotionPath: autoOrient is true or false");
+            if (op.path == null && op.autoOrient == null) throw new Error('setMotionPath needs path:"smooth"|"straight" and / or autoOrient');
+            for (const id of ids) {
+              const c = byId(id);
+              if (!c) throw new Error("setMotionPath: no clip " + id);
+              if (c.kind === "audio" || c.kind === "adjust") throw new Error(`setMotionPath: ${id} is a ${c.kind} clip`);
+              refuseLocked("setMotionPath", lockReason(c), op);
+              if (op.path) {
+                if (Motion.posKeys(c).length < 2) throw new Error(`setMotionPath: ${id} needs x and y keyed together at two or more times first (the position keys)`);
+                c.keyframes = op.path === "smooth" ? Motion.smoothPath(c.keyframes) : Motion.straightPath(c.keyframes);
+              }
+              if (op.autoOrient != null) { c.props = c.props || {}; if (op.autoOrient) c.props.autoOrient = true; else delete c.props.autoOrient; }
+              notes.push(`~${id}.motionPath(${Motion.posKeys(c).length} keys${Motion.hasPathHandles(c) ? ", curved" : ""}${c.props && c.props.autoOrient ? ", auto-orient" : ""})`);
+            }
+            break;
+          }
+          case "setTextPath": {
+            // {op:"setTextPath", id | ids, path: "line" | "arc" | "circle" | "wave" | {type, …} | null, offset?, align?}
+            const ids = Array.isArray(op.ids) ? op.ids : op.id != null ? [op.id] : [];
+            if (!ids.length) throw new Error("setTextPath needs id or ids");
+            if (op.path === undefined && op.offset == null && op.align == null) throw new Error("setTextPath needs path (a preset name, a shape item or null), offset and / or align");
+            let item;
+            if (op.path === null) item = null;
+            else if (typeof op.path === "string") {
+              if (!Motion.TEXT_PATH_PRESETS[op.path]) throw new Error(`setTextPath: path is ${Object.keys(Motion.TEXT_PATH_PRESETS).join(" | ")}, a shape item or null`);
+              item = Motion.normalizeTextPath(Motion.TEXT_PATH_PRESETS[op.path], true);
+            } else if (op.path !== undefined) {
+              try { item = Motion.normalizeTextPath(op.path, true); } catch (err) { throw new Error(`setTextPath: ${err.message}`); }
+            }
+            if (op.offset != null && typeof op.offset !== "number") throw new Error("setTextPath: offset is % of the path's length");
+            if (op.align != null && !["start", "center", "end"].includes(op.align)) throw new Error("setTextPath: align is start | center | end");
+            for (const id of ids) {
+              const c = byId(id);
+              if (!c) throw new Error("setTextPath: no clip " + id);
+              if (c.kind !== "text") throw new Error(`setTextPath: ${id} is a ${c.kind} clip — text paths go on text clips`);
+              refuseLocked("setTextPath", lockReason(c), op);
+              c.props = c.props || {};
+              if (op.path !== undefined) { if (item) c.props.textPath = JSON.parse(JSON.stringify(item)); else delete c.props.textPath; }
+              if (op.offset != null) c.props.pathOffset = op.offset;
+              if (op.align != null) c.props.pathAlign = op.align;
+              notes.push(`~${id}.textPath(${c.props.textPath ? c.props.textPath.type : "none"})`);
+            }
+            break;
+          }
+          case "addComp": {
+            // {op:"addComp", comp:{id?, name, width?, height?, duration, background?, tracks?, clips?:[…]}}
+            const src = op.comp;
+            if (!src || typeof src !== "object") throw new Error("addComp needs comp:{name, duration, …}");
+            const id = src.id || "comp_" + uid();
+            if (CompLib.getComp(proj, id)) throw new Error(`addComp: comp ${id} already exists`);
+            let comp;
+            try { comp = CompLib.normalizeComp({ ...src, id, clips: [] }, true, proj); } catch (err) { throw new Error(`addComp: ${err.message}`); }
+            if (!comp.tracks) comp.tracks = CompLib.DEFAULT_TRACKS.map((t) => ({ ...t }));
+            proj.comps = [...(proj.comps || []), comp];
+            notes.push(`+comp ${id}`);
+            // its clips go in through the same checks as addClip
+            if (Array.isArray(src.clips) && src.clips.length) applyOps([{ op: "inComp", comp: id, ops: src.clips.map((clip) => ({ op: "addClip", clip })) }]);
+            break;
+          }
+          case "updateComp": {
+            // {op:"updateComp", id, set:{name?, width?, height?, duration?, background?, tracks?}}
+            const comp = CompLib.getComp(proj, op.id);
+            if (!comp) throw new Error("updateComp: no comp " + op.id);
+            const set = op.set || {};
+            for (const k of Object.keys(set)) if (!["name", "width", "height", "duration", "background", "tracks", "disabledTracks"].includes(k))
+              throw new Error(`updateComp: ${k} can't be set here (name, width, height, duration, background, tracks, disabledTracks) — edit its clips with inComp`);
+            const next = { ...comp, ...set };
+            for (const [k, v] of Object.entries(set)) if (v === null) delete next[k];
+            let n;
+            try { n = CompLib.normalizeComp(next, true, proj); } catch (err) { throw new Error(`updateComp: ${err.message}`); }
+            proj.comps = proj.comps.map((c) => (c.id === comp.id ? n : c));
+            notes.push(`~comp ${comp.id}`);
+            break;
+          }
+          case "removeComp": {
+            const comp = CompLib.getComp(proj, op.id);
+            if (!comp) throw new Error("removeComp: no comp " + op.id);
+            const used = CompLib.usages(proj, comp.id);
+            if (used.length) throw new Error(`removeComp: ${comp.id} is used by ${used.map((u) => u.clip.id + (u.in ? ` (in ${u.in})` : "")).join(", ")} — remove those clips first`);
+            proj.comps = proj.comps.filter((c) => c.id !== comp.id);
+            notes.push(`-comp ${comp.id}`);
+            break;
+          }
+          case "precompose": {
+            // {op:"precompose", ids:[…], name?, id?} — the clips (here, or inside the comp an inComp op is in) move into a new comp
+            const ids = Array.isArray(op.ids) ? op.ids : [];
+            if (!ids.length) throw new Error("precompose needs ids:[…] (the clips to move into the new comp)");
+            for (const id of ids) {
+              const c = proj.clips.find((x) => x.id === id);
+              if (!c) throw new Error("precompose: no clip " + id + (inCompId ? ` in comp ${inCompId}` : ""));
+              refuseLocked("precompose", lockReason(c), op);
+            }
+            const doc = { clips: proj.clips, comps: proj.comps || [], tracks: proj.tracks, width: proj.width, height: proj.height };
+            let r;
+            try { r = CompLib.precompose(doc, ids, { id: op.id, name: op.name }); } catch (err) { throw new Error(err.message); }
+            proj.clips = doc.clips; proj.comps = doc.comps;
+            r.clip.id = "c_" + uid();
+            notes.push(`+comp ${r.comp.id} (${ids.length} clips) +${r.clip.id}`);
+            break;
+          }
+          case "applyPreset": {
+            // {op:"applyPreset", id | ids, preset: name | {anchor, length, keys…}, length?, at?} — at: timeline seconds, for an "at" (emphasis) preset
+            const ids = Array.isArray(op.ids) ? op.ids : op.id ? [op.id] : [];
+            if (!ids.length) throw new Error("applyPreset needs id or ids:[…]");
+            let p;
+            try { p = Templates.findPreset(op.preset, savedList("presets")); } catch (err) { throw new Error(`applyPreset: ${err.message}`); }
+            if (!p) throw new Error(`applyPreset: no preset ${JSON.stringify(op.preset)} — built in: ${Templates.PRESETS.map((x) => x.id).join(", ")}` +
+              (savedList("presets").length ? `; saved: ${savedList("presets").map((x) => x.id).join(", ")}` : ""));
+            if (op.length != null && !(typeof op.length === "number" && op.length > 0)) throw new Error("applyPreset: length is seconds, more than 0");
+            for (const id of ids) {
+              const c = proj.clips.find((x) => x.id === id);
+              if (!c) throw new Error("applyPreset: no clip " + id + (inCompId ? ` in comp ${inCompId}` : ""));
+              if (c.kind === "audio" || c.kind === "adjust") throw new Error(`applyPreset: clip ${id} is ${c.kind} — presets animate visual clips`);
+              refuseLocked("applyPreset", lockReason(c), op);
+              Templates.applyPreset(c, p, { length: op.length, at: typeof op.at === "number" ? op.at - c.start : undefined });
+            }
+            notes.push(`~${ids.join(",")}.${p.id}`);
+            break;
+          }
+          case "addTemplate": {
+            // {op:"addTemplate", template: name | {…}, start?, track?, duration?, fields?:{key: value}, id?, compId?, name?}
+            let t;
+            try { t = Templates.findTemplate(op.template, savedList("templates")); } catch (err) { throw new Error(`addTemplate: ${err.message}`); }
+            if (!t) throw new Error(`addTemplate: no template ${JSON.stringify(op.template)} — built in: ${Templates.TEMPLATES.map((x) => x.id).join(", ")}` +
+              (savedList("templates").length ? `; saved: ${savedList("templates").map((x) => x.id).join(", ")}` : ""));
+            let r;
+            try {
+              r = Templates.instantiate(proj, t, { compId: op.compId || "comp_" + uid(), clipId: op.id || "c_" + uid(), name: op.name,
+                start: typeof op.start === "number" ? op.start : 0, track: op.track || "V2", duration: op.duration, fields: op.fields });
+            } catch (err) { throw new Error(`addTemplate: ${err.message}`); }
+            notes.push(`+comp ${r.comp.id} (${t.id})`);
+            applyOps([{ op: "addClip", clip: r.clip }]);   // the same checks as any clip: track, locks
+            break;
+          }
+          case "setTemplate": {
+            // {op:"setTemplate", id: comp clip id | comp id, fields?:{key: value}, duration?}
+            let comp = CompLib.getComp(proj, op.id);
+            if (!comp) { const c = proj.clips.find((x) => x.id === op.id && x.kind === "comp"); comp = c && CompLib.getComp(proj, c.compId); }
+            if (!comp) throw new Error("setTemplate: no template clip or comp " + op.id);
+            if (!comp.template) throw new Error(`setTemplate: comp ${comp.id} isn't a placed template — edit its clips with inComp`);
+            try {
+              for (const [k, v] of Object.entries(op.fields || {})) Templates.setField(comp, Templates.slug(k), v, proj);
+              if (op.duration != null) {
+                const old = comp.duration;
+                Templates.retime(comp, op.duration);
+                // clips that showed the comp to its end keep doing so
+                for (const u of CompLib.usages(proj, comp.id)) if (Math.abs((+u.clip.in || 0) + u.clip.duration - old) < 1e-3) u.clip.duration = +(comp.duration - (+u.clip.in || 0)).toFixed(4);
+              }
+            } catch (err) { throw new Error(`setTemplate: ${err.message}`); }
+            notes.push(`~template ${comp.id}`);
+            break;
+          }
+          case "savePreset": {
+            // {op:"savePreset", id: clip id, name, anchor?:"in"|"out"|"whole", from?, to?} (clip seconds) or {op:"savePreset", preset:{…}}
+            let p;
+            try {
+              if (op.preset) p = Templates.normalizePreset(op.preset, true);
+              else {
+                const c = proj.clips.find((x) => x.id === op.id);
+                if (!c) throw new Error("no clip " + op.id);
+                const times = Object.values(c.keyframes || {}).flat().map((x) => x.t);
+                if (!times.length) throw new Error(`clip ${c.id} has no keyframes to save`);
+                const anchor = op.anchor || "in";
+                p = Templates.presetFromClip(c, { name: op.name, anchor,
+                  from: typeof op.from === "number" ? op.from : anchor === "out" ? Math.min(...times) : 0,
+                  to: typeof op.to === "number" ? op.to : anchor === "in" ? Math.max(...times) : c.duration });
+              }
+            } catch (err) { throw new Error(`savePreset: ${err.message}`); }
+            p = Templates.asSaved(p, "presets");
+            toSave.push(["presets", p]);
+            notes.push(`saved preset ${p.id} → library/presets/${p.id}.json`);
+            break;
+          }
+          case "saveTemplate": {
+            // {op:"saveTemplate", comp, name?, fields?, hold?} or {op:"saveTemplate", template:{…}}
+            let t;
+            try {
+              if (op.template) t = Templates.normalizeTemplate(op.template, true);
+              else {
+                const comp = CompLib.getComp(proj, op.comp);
+                if (!comp) throw new Error("no comp " + op.comp);
+                t = Templates.templateFromComp(comp, { name: op.name, fields: op.fields, hold: op.hold, media: proj.media });
+              }
+            } catch (err) { throw new Error(`saveTemplate: ${err.message}`); }
+            t = Templates.asSaved(t, "templates");
+            toSave.push(["templates", t]);
+            notes.push(`saved template ${t.id} → library/templates/${t.id}.json`);
+            break;
+          }
+          case "inComp": {
+            // {op:"inComp", comp, ops:[…clip / timeline ops…]} — run ops on the comp's own clips and tracks
+            const comp = CompLib.getComp(proj, op.comp);
+            if (!comp) throw new Error("inComp: no comp " + op.comp);
+            if (!Array.isArray(op.ops)) throw new Error("inComp needs ops:[…]");
+            const allowed = ["addClip", "updateClip", "removeClip", "setGrade", "setGradeLayer", "setMask", "removeMask", "setMaskKeys", "setMatte",
+              "setShape", "removeShape", "setParent", "setMotionPath", "setTextPath", "setFx", "setFxKeys", "precompose", "inComp",
+              "applyPreset", "addTemplate", "setTemplate",
+              "split", "rippleDelete", "closeGap", "lift", "extract", "rippleTrim", "roll", "slip", "slide", "crossfade"];
+            for (const o of op.ops) {
+              if (!o || !allowed.includes(o.op)) throw new Error(`inComp: ${o && o.op} can't run inside a comp (clip and timeline ops only: ${allowed.join(", ")})`);
+              // the same target rule as fxTarget: no id means master, A… a track, B… a bus — none of them live in a comp
+              const fxAt = o.target || (o.id && /^A\d+$/.test(o.id) ? "track" : o.id && /^B\d+$/.test(o.id) ? "bus" : o.id ? "clip" : "master");
+              if ((o.op === "setFx" || o.op === "setFxKeys") && fxAt !== "clip")
+                throw new Error(`inComp: ${o.op} inside a comp works on its clips only (target:"clip", id) — the ${fxAt} effects are the main timeline's`);
+            }
+            const keep = { clips: proj.clips, tracks: proj.tracks, width: proj.width, height: proj.height, lockedTracks: proj.lockedTracks,
+              untargetedTracks: proj.untargetedTracks, disabledTracks: proj.disabledTracks, inPoint: proj.inPoint, outPoint: proj.outPoint };
+            const prevIn = inCompId;
+            Object.assign(proj, { clips: comp.clips || [], tracks: CompLib.compTracks(comp), width: comp.width, height: comp.height,
+              lockedTracks: [], untargetedTracks: [], disabledTracks: comp.disabledTracks || [], inPoint: null, outPoint: null });
+            inCompId = comp.id;
+            const n0 = notes.length;
+            try { applyOps(op.ops); }
+            finally {
+              const live = CompLib.getComp(proj, comp.id) || comp;
+              live.clips = proj.clips;
+              inCompId = prevIn;
+              Object.assign(proj, keep);
+            }
+            const inner = notes.splice(n0);
+            notes.push(`${comp.id}{${inner.join(" ")}}`);
+            break;
+          }
           case "removeTrack": {
             // {op:"removeTrack", id, track: "name" | index} — what follows it keeps its keys
             const c = proj.clips.find((x) => x.id === op.id);
@@ -1291,10 +1686,12 @@ async function callTool(name, args, attempt = 0) {
             notes.push(timelineEdit(proj, op, refuseLocked, lockReason));
             break;
           default:
-            throw new Error("Unknown op: " + op.op + " (addClip|updateClip|removeClip|addMedia|removeMedia|setProject|setTrack|setBus|removeBus|setFx|setFxKeys|setGrade|setGradeLayer|setMask|removeMask|setMaskKeys|setMatte|removeTrack|" +
-              "split|rippleDelete|closeGap|lift|extract|rippleTrim|roll|slip|slide|insert|overwrite|crossfade)");
+            throw new Error("Unknown op: " + op.op + " (addClip|updateClip|removeClip|addMedia|removeMedia|setProject|setTrack|setBus|removeBus|setFx|setFxKeys|setGrade|setGradeLayer|setMask|removeMask|setMaskKeys|setMatte|removeTrack|setShape|removeShape|setParent|setMotionPath|setTextPath|" +
+              "split|rippleDelete|closeGap|lift|extract|rippleTrim|roll|slip|slide|insert|overwrite|crossfade|" +
+              "addComp|updateComp|removeComp|precompose|inComp|applyPreset|addTemplate|setTemplate|savePreset|saveTemplate)");
         }
-      }
+      } };
+      applyOps(ops);
       // Someone else saved while the ops ran: writing now would drop their change.
       // Without a baseRevision the ops just re-apply on the newer document.
       let diskRev = readRev;
@@ -1306,6 +1703,7 @@ async function callTool(name, args, attempt = 0) {
       proj.revision = readRev + 1;
       writeProject(proj);
       lastReadRevision = proj.revision;
+      for (const [kind, item] of toSave) writeSaved(kind, item.id, item);
       return `Patched (revision ${proj.revision}): ${notes.join(" ")}. Now ${proj.clips.length} clip(s), ${proj.media.length} media. UI hot-reloaded.`;
     }
     case "fablecut_set_project": {
@@ -1313,12 +1711,34 @@ async function callTool(name, args, attempt = 0) {
       if (!doc || typeof doc !== "object") throw new Error("`project` must be an object");
       if (!Array.isArray(doc.clips) || !Array.isArray(doc.media))
         throw new Error("project must contain `clips` and `media` arrays");
-      for (const c of doc.clips) {
-        if (!c.id || !c.track || typeof c.start !== "number" || typeof c.duration !== "number")
-          throw new Error(`clip ${c.id || "?"} needs id, track, numeric start and duration`);
-        if (c.kind !== "text" && c.kind !== "adjust" && !doc.media.some((m) => m.id === c.mediaId))
-          throw new Error(`clip ${c.id} references unknown mediaId ${c.mediaId}`);
+      if (doc.comps != null) {
+        if (!Array.isArray(doc.comps)) throw new Error("comps must be a list of compositions");
+        // saved as normalized (trimmed id, default name and size, rounded duration)
+        try { doc.comps = doc.comps.map((comp) => CompLib.normalizeComp(comp, true, doc)); } catch (err) { throw new Error(err.message); }
+        const seen = new Set();
+        for (const comp of doc.comps) {
+          if (seen.has(comp.id)) throw new Error(`two comps have the id ${comp.id} — comp ids must be unique`);
+          seen.add(comp.id);
+        }
       }
+      // the same checks for clips on the timeline and clips inside comps
+      const checkClip = (c, where) => {
+        const at = where ? `comp ${where}: ` : "";
+        if (!c.id || !c.track || typeof c.start !== "number" || typeof c.duration !== "number")
+          throw new Error(`${at}clip ${c.id || "?"} needs id, track, numeric start and duration`);
+        if (!["text", "adjust", "shape", "null", "comp"].includes(c.kind) && !doc.media.some((m) => m.id === c.mediaId))
+          throw new Error(`${at}clip ${c.id} references unknown mediaId ${c.mediaId}`);
+        if (c.kind === "comp" && !CompLib.getComp(doc, c.compId)) throw new Error(`${at}clip ${c.id} references unknown compId ${c.compId}`);
+        if (c.kind === "comp" && where && CompLib.wouldCycle(doc, where, c.compId))
+          throw new Error(`comp ${where}: clip ${c.id} uses comp ${c.compId}, which is missing or would contain itself`);
+        if (c.kind === "shape" && c.props && c.props.shapes != null) {
+          let n;
+          try { n = Motion.normalizeShapes(c.props.shapes, true); } catch (err) { throw new Error(`${at}clip ${c.id}: props.${err.message}`); }
+          if (n) c.props.shapes = n; else delete c.props.shapes;
+        }
+      };
+      for (const c of doc.clips) checkClip(c, null);
+      for (const comp of doc.comps || []) for (const c of comp.clips) checkClip(c, comp.id);
       let cur = { revision: 0 };
       try { cur = readProject(); } catch {}
       const curRev = cur.revision || 0;
@@ -1581,7 +2001,7 @@ async function handle(msg) {
         result: {
           protocolVersion: negotiateProtocolVersion(params?.protocolVersion),
           capabilities: { tools: {} },
-          serverInfo: { name: "fablecut", version: "1.13.0" },
+          serverInfo: { name: "fablecut", version: "1.14.0" },
         },
       });
     }