fablecut 1.12.1 → 1.14.0

package/color.js

@@ -42,16 +42,20 @@
      layers: [{ name?, on?, qualifier?, mask?, …grade keys }]
      qualifier: { hue?: [centre°, width°, soft°], sat?: [lo, hi, soft],
                   luma?: [lo, hi, soft], invert? }   — measured on the layer's input
-     mask: { shape: ellipse | rect | poly, x, y (centre, 0…1 of the picture),
+     mask: { shape: ellipse | rect | poly | bezier, x, y (centre, 0…1 of the picture),
              w, h (size, 0…1), rotation°, feather (0…0.5 of the height),
              invert?, points?: [[dx, dy], …] (poly, relative to x, y),
+             bezier: [[dx, dy, inX?, inY?, outX?, outY?], …] — anchors with
+             handles, the outline mask.js draws (a free-hand stroke,
+             { shape: "freehand", stroke: [[u, v], …] }, is fitted into one),
              keys?: [{ t, ease?, x?, y?, w?, h?, rotation?, feather? }] }
    matte = qualifier × mask (each 1 when absent); out = mix(in, graded, matte). */
 (function (root, factory) {
-  const api = factory();
-  if (typeof module === "object" && module.exports) module.exports = api;
+  const node = typeof module === "object" && module.exports;
+  const api = factory(node ? require("./mask") : root.FableCutMask);
+  if (node) module.exports = api;
   else root.FableCutColor = api;
-})(typeof self !== "undefined" ? self : this, function () {
+})(typeof self !== "undefined" ? self : this, function (MaskLib) {
   "use strict";
 
   const WHEELS = ["lift", "gamma", "gain", "offset"];
@@ -91,7 +95,9 @@
   const HUE_N = 360;          // hue-curve lookup-table size (also sat 0…1 for satLuma)
   const MAX_LAYERS = 8;
   const MAX_POLY = 16;
-  const MASK_SHAPES = ["ellipse", "rect", "poly"];
+  const MAX_BEZIER = 24;      // bezier anchors on a grade mask
+  const MAX_OUTLINE = 96;     // the flattened outline the shader walks
+  const MASK_SHAPES = ["ellipse", "rect", "poly", "bezier"];
   const MASK_KEYED = ["x", "y", "w", "h", "rotation", "feather"];
   const KEY_RANGE = { x: [-1, 2], y: [-1, 2], w: [0.001, 4], h: [0.001, 4], rotation: [-720, 720], feather: [0, 0.5] };
   const WB_STOPS = 1 / 100;   // temp / tint ±100 → ±1 stop per channel
@@ -487,6 +493,12 @@
     if (m == null) return null;
     const bad = (msg) => { if (strict) throw new Error(`${where}.mask${msg}`); return null; };
     if (typeof m !== "object" || Array.isArray(m)) return bad(" must be {shape, x, y, w, h, rotation?, feather?, invert?}");
+    if (m.shape === "freehand") {
+      if (!Array.isArray(m.stroke) || m.stroke.length < 3 || m.stroke.some((p) => !Array.isArray(p) || !isNum(p[0]) || !isNum(p[1])))
+        return bad(".stroke must be at least 3 [u, v] points (fractions of the picture)");
+      m = { ...m, ...MaskLib.fitStroke(m.stroke, m.aspect, MAX_BEZIER), shape: "bezier" };
+      delete m.stroke; delete m.aspect;
+    }
     const shape = m.shape == null ? "ellipse" : m.shape;
     if (!MASK_SHAPES.includes(shape)) return bad(`.shape must be ${MASK_SHAPES.join(" | ")}`);
     for (const k of Object.keys(m)) if (![...MASK_KEYED, "shape", "invert", "points", "keys"].includes(k)) bad(`.${k}: unknown key`);
@@ -509,6 +521,11 @@
       if (!Array.isArray(pts) || pts.length < 3 || pts.length > MAX_POLY || pts.some((p) => !Array.isArray(p) || p.length !== 2 || !p.every(isNum)))
         return bad(`.points must be 3…${MAX_POLY} [dx, dy] pairs around x, y (fractions of the picture)`);
       out.points = pts.map(([a, b]) => [+clamp(a, -2, 2).toFixed(4), +clamp(b, -2, 2).toFixed(4)]);
+    } else if (shape === "bezier") {
+      const pts = m.points;
+      if (!Array.isArray(pts) || pts.length < 3 || pts.length > MAX_BEZIER || pts.some((p) => !Array.isArray(p) || (p.length !== 2 && p.length !== 6) || !p.every(isNum)))
+        return bad(`.points must be 3…${MAX_BEZIER} anchors [dx, dy] or [dx, dy, inX, inY, outX, outY] around x, y (fractions of the picture)`);
+      out.points = pts.map((p) => p.map((v) => +clamp(v, -2, 2).toFixed(4)));
     }
     if (m.keys != null) {
       if (!Array.isArray(m.keys)) return bad(".keys must be a list of {t, x?, y?, w?, h?, rotation?, feather?}");
@@ -596,10 +613,26 @@
       const qx = Math.abs(px) - rx, qy = Math.abs(py) - ry;
       return Math.hypot(Math.max(qx, 0), Math.max(qy, 0)) + Math.min(Math.max(qx, qy), 0);
     }
-    if (m.shape === "poly") return polyDist(m.points.map(([a, b]) => [a * aspect, b]), px, py);
+    if (m.shape === "poly" || m.shape === "bezier") return polyDist(outlineAt(m, aspect), px, py);
     const k0 = Math.hypot(px / rx, py / ry), k1 = Math.hypot(px / (rx * rx), py / (ry * ry));
     return k0 < 1e-6 ? -Math.min(rx, ry) : k0 * (k0 - 1) / k1;
   }
+  /** A bezier mask's outline as a polygon around its centre (fractions of the
+   *  picture, unrotated) — at most MAX_OUTLINE corners, the shader's budget. */
+  /** The poly / bezier outline in aspect-scaled units, cached per points array — the CPU path asks per pixel. */
+  const outlines = new WeakMap();
+  function outlineAt(m, aspect) {
+    let o = outlines.get(m.points);
+    if (!o || o.aspect !== aspect) {
+      o = { aspect, pts: (m.shape === "bezier" ? bezierOutline(m) : m.points).map(([a, b]) => [a * aspect, b]) };
+      outlines.set(m.points, o);
+    }
+    return o.pts;
+  }
+  function bezierOutline(m) {
+    const A = MaskLib.anchors({ shape: "bezier", x: 0, y: 0, scale: 1, rotation: 0, points: m.points }, 1, 1);
+    return MaskLib.flatten(A, Math.max(1, Math.min(16, Math.floor(MAX_OUTLINE / A.length))));
+  }
   function polyDist(pts, px, py) {
     let d = (px - pts[0][0]) ** 2 + (py - pts[0][1]) ** 2, s = 1;
     for (let i = 0, j = pts.length - 1; i < pts.length; j = i, i++) {
@@ -757,10 +790,10 @@
       u.uMRot = m ? m.rotation * Math.PI / 180 : 0;
       u.uMFeather = m ? Math.max(0.002, m.feather) : 0.002;
       u.uMInv = m && m.invert ? 1 : 0;
-      const pts = new Float32Array(MAX_POLY * 2);
-      if (m && m.points) m.points.forEach(([a, b], i) => { pts[i * 2] = a; pts[i * 2 + 1] = b; });
+      const pts = new Float32Array(MAX_OUTLINE * 2), P = m && m.points ? (m.shape === "bezier" ? bezierOutline(m) : m.points) : [];
+      P.forEach(([a, b], i) => { pts[i * 2] = a; pts[i * 2 + 1] = b; });
       u.uMPts = pts;
-      u.uMN = m && m.points ? m.points.length : 0;
+      u.uMN = P.length;
       passes.push(u);
     }
     return passes;
@@ -800,10 +833,10 @@ uniform int uLayer, uMatte, uPremul;   // layer pass: mix by its matte · show t
 uniform int uQOn, uQInv;
 uniform ivec3 uQUse;                   // hue, sat, luma ranges in use
 uniform vec3 uQHue, uQSat, uQLuma;     // hue: centre, half width, soft (turns) · sat / luma: low, high, soft
-uniform int uMShape, uMInv, uMN;       // 0 none · 1 ellipse · 2 rect · 3 poly
+uniform int uMShape, uMInv, uMN;       // 0 none · 1 ellipse · 2 rect · 3 poly · 4 bezier (flattened)
 uniform vec2 uMC, uMW;
 uniform float uMRot, uMFeather, uAspect;
-uniform vec2 uMPts[${MAX_POLY}];
+uniform vec2 uMPts[${MAX_OUTLINE}];
 in vec2 vPos;
 out vec4 outColor;
 vec4 lutAt(sampler2D t, int n, float x) {
@@ -862,10 +895,10 @@ float maskDist(vec2 uv) {
     vec2 q = abs(p) - r;
     return length(max(q, 0.0)) + min(max(q.x, q.y), 0.0);
   }
-  if (uMShape == 3) {
+  if (uMShape >= 3) {
     vec2 v0 = uMPts[0] * vec2(uAspect, 1.0);
     float dd = dot(p - v0, p - v0), s = 1.0;
-    for (int i = 0; i < ${MAX_POLY}; i++) {
+    for (int i = 0; i < ${MAX_OUTLINE}; i++) {
       if (i >= uMN) break;
       int j = i == 0 ? uMN - 1 : i - 1;
       vec2 vi = uMPts[i] * vec2(uAspect, 1.0), vj = uMPts[j] * vec2(uAspect, 1.0);
@@ -1034,7 +1067,7 @@ void main() {
     GRADE_PARAMS, GRADE_KEYS, WHEELS, GRADE_VERT, GRADE_FRAG, SKIN_ANGLE,
     CURVE_CHANNELS, HUE_CURVES, HUE_KEYS, CURVE_N, HUE_N, BAND,
     normalizeGrade, fullGrade, isNeutral, mergeGrade, summarizeGrade, withoutCurves,
-    MAX_LAYERS, MAX_POLY, MASK_SHAPES, MASK_KEYED, mergeLayer, layerGrade, maskAt, gradeAt, qualAlpha, maskAlpha, maskDist, gradePasses,
+    MAX_LAYERS, MAX_POLY, MAX_BEZIER, MASK_SHAPES, MASK_KEYED, mergeLayer, layerGrade, maskAt, gradeAt, qualAlpha, maskAlpha, maskDist, gradePasses,
     monotone, curveFn, rgbToHsv, hsvToRgb,
     wbGains, solveWhiteBalance, srgbToLinear, linearToSrgb, wheelToRgb, rgbToWheel, ycbcr,
     prepareGrade, gradePixel, gradeImageData, gradeUniforms,

package/comp.js

@@ -0,0 +1,195 @@
+/* FableCut compositions — nested sequences. Zero dependencies beyond edit-ops
+   (for re-basing keyframes). Loaded by the editor as a plain script (global
+   `FableCutComp`) and required by the MCP server and the tests.
+
+   A composition lives in `project.comps`:
+     { id, name, width, height, duration, background?, tracks?: [{id, kind}], clips: [ …clips… ] }
+   Its clips are ordinary clips (any kind, comp clips too) on the comp's own
+   tracks, with times inside the comp. A clip of kind "comp" places one on a
+   timeline: { kind: "comp", compId, start, in, duration, props… } — `in` is
+   where in the comp it starts. It draws like a picture of the comp's size (so
+   it moves, scales, masks, grades and blends like an image), and the media in
+   it — video frames, audio — plays and exports as if it were on the timeline.
+
+   flatten() turns every comp clip's contents into "virtual" clips on the main
+   timeline: ids "<compClip>><clip>", start shifted to timeline time, trimmed
+   to the comp clip's window, keyframes / masks / shape keys re-based, parents
+   and links renamed into the same instance. Playback, export seeking, the
+   audio mix and the comp renderer all work from that list. */
+(function (root, factory) {
+  const node = typeof module === "object" && module.exports;
+  const api = factory(node ? require("./edit-ops") : root.FableCutEdit);
+  if (node) module.exports = api;
+  else root.FableCutComp = api;
+})(typeof self !== "undefined" ? self : this, function (EditLib) {
+  "use strict";
+
+  const MAX_DEPTH = 4;
+  const SEP = ">";
+  const DEFAULT_TRACKS = [
+    { id: "V3", kind: "video" }, { id: "V2", kind: "video" }, { id: "V1", kind: "video" },
+    { id: "A1", kind: "audio" }, { id: "A2", kind: "audio" },
+  ];
+  const isObj = (v) => v != null && typeof v === "object" && !Array.isArray(v);
+  const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+  const r4 = (v) => +(+v).toFixed(4);
+  const compTracks = (comp) => (Array.isArray(comp.tracks) && comp.tracks.length ? comp.tracks : DEFAULT_TRACKS);
+
+  /** A comp, validated. strict: throw on bad input (agent). doc: for width / height defaults. */
+  function normalizeComp(c, strict = false, doc = {}) {
+    const bad = (m) => { if (strict) throw new Error(m); return null; };
+    if (!isObj(c)) return bad("a comp must be an object like {id, name, duration, clips:[…]}");
+    if (typeof c.id !== "string" || !c.id.trim()) return bad("a comp needs an id");
+    const out = { ...c, id: c.id.trim() };
+    out.name = typeof c.name === "string" && c.name.trim() ? c.name.trim().slice(0, 80) : out.id;
+    for (const [k, def] of [["width", doc.width || 1280], ["height", doc.height || 720]]) {
+      const v = c[k] == null ? def : c[k];
+      if (!Number.isInteger(v) || v < 16 || v > 8192) { bad(`comp ${out.id}: ${k} must be a whole number of px (16…8192)`); out[k] = def; }
+      else out[k] = v;
+    }
+    if (!isNum(c.duration) || c.duration <= 0) return bad(`comp ${out.id}: duration must be a number of seconds > 0`);
+    out.duration = r4(c.duration);
+    if (c.background != null && typeof c.background !== "string") bad(`comp ${out.id}: background is a colour string (or leave it out for transparent)`);
+    if (c.tracks != null) {
+      if (!Array.isArray(c.tracks) || c.tracks.some((t) => !isObj(t) || typeof t.id !== "string" || !["video", "audio"].includes(t.kind)))
+        bad(`comp ${out.id}: tracks is a list of {id, kind:"video"|"audio"}`);
+    }
+    if (c.clips != null && !Array.isArray(c.clips)) return bad(`comp ${out.id}: clips must be a list`);
+    out.clips = Array.isArray(c.clips) ? c.clips : [];
+    for (const x of out.clips) {
+      if (!isObj(x) || typeof x.id !== "string" || !isNum(x.start) || !isNum(x.duration))
+        return bad(`comp ${out.id}: every clip needs id, numeric start and duration`);
+    }
+    return out;
+  }
+  function getComp(doc, id) { return (doc && Array.isArray(doc.comps) ? doc.comps : []).find((c) => c.id === id) || null; }
+  /** Comp ids that comp `id` uses, directly or through nested comps. */
+  function usedComps(doc, id, out = new Set(), depth = 0) {
+    const comp = getComp(doc, id);
+    if (!comp || depth > 32) return out;
+    for (const c of comp.clips || []) if (c.kind === "comp" && c.compId && !out.has(c.compId)) { out.add(c.compId); usedComps(doc, c.compId, out, depth + 1); }
+    return out;
+  }
+  /** Would placing comp `childId` inside comp `parentId` (null = the main timeline) make a loop? */
+  function wouldCycle(doc, parentId, childId) {
+    if (!parentId) return false;
+    if (parentId === childId) return true;
+    return usedComps(doc, childId).has(parentId);
+  }
+  /** Where comp `id` is used: [{in: compId | null (main), clip}] */
+  function usages(doc, id) {
+    const out = [];
+    for (const c of doc.clips || []) if (c.kind === "comp" && c.compId === id) out.push({ in: null, clip: c });
+    for (const comp of doc.comps || []) for (const c of comp.clips || []) if (c.kind === "comp" && c.compId === id) out.push({ in: comp.id, clip: c });
+    return out;
+  }
+
+  /* ── Flattening ── */
+  const clipEnd = (c) => c.start + c.duration;
+  const speedOf = (c) => (c.props && +c.props.speed) || 1;
+  /** Keyframe times re-based by -offset, every key kept (keys before 0 still shape the curve). */
+  function shiftAll(kfs, offset) {
+    if (!kfs) return kfs;
+    const out = {};
+    for (const [k, arr] of Object.entries(kfs)) out[k] = Array.isArray(arr) ? arr.map((kf) => ({ ...kf, t: r4(kf.t - offset) })) : arr;
+    return out;
+  }
+  /** A comp's clip as a clip on the timeline: shifted by `offset`, trimmed to `win`, renamed under `prefix`. */
+  function virtualize(inner, prefix, offset, win, inst, on) {
+    const start = inner.start + offset, end = start + inner.duration;
+    const a = Math.max(start, win[0]), b = Math.min(end, win[1]);
+    if (b - a <= 1e-6) return null;
+    const head = a - start;
+    const v = { ...inner, id: prefix + inner.id, start: r4(a), duration: r4(b - a), _comp: inst, _src: inner.id, _on: on && inner.disabled !== true };
+    if (inner.props) v.props = { ...inner.props };
+    if (head > 1e-6) {
+      const shifted = { ...inner, start };
+      if (inner.kind === "video" || inner.kind === "audio") v.in = r4(EditLib.mediaTimeAt(shifted, a));
+      else if (inner.kind === "comp") v.in = r4((inner.in || 0) + head);
+      v.keyframes = shiftAll(inner.keyframes, head);
+      v.transitionIn = undefined;
+      if (v.props) EditLib.shiftMasks(v, head);
+    }
+    if (end - b > 1e-6) v.transitionOut = undefined;
+    if (inner.parent) v.parent = prefix + inner.parent;
+    if (inner.linkGroup) v.linkGroup = prefix + inner.linkGroup;
+    if (inner.linkedId) v.linkedId = prefix + inner.linkedId;
+    return v;
+  }
+  /** Every clip the comp clips in `clips` bring onto the timeline, depth first:
+   *  [{…virtual clip, _comp: the comp clip's id (its instance), _on: renders}]. */
+  function flatten(doc, clips = doc.clips, opts = {}) {
+    const out = [];
+    const walk = (list, depth, seen, renders) => {
+      for (const c of list || []) {
+        if (c.kind !== "comp") continue;
+        const comp = getComp(doc, c.compId);
+        if (!comp || seen.has(comp.id) || depth >= MAX_DEPTH) continue;
+        const on = renders(c);
+        const offset = c.start - (c.in || 0), win = [c.start, Math.min(clipEnd(c), c.start - (c.in || 0) + comp.duration)];
+        const disabled = new Set(comp.disabledTracks || []);
+        const kids = [];
+        for (const inner of comp.clips || []) {
+          const v = virtualize(inner, c.id + SEP, offset, win, c.id, on && !disabled.has(inner.track));
+          if (v) { kids.push(v); out.push(v); }
+        }
+        const next = new Set(seen); next.add(comp.id);
+        walk(kids, depth + 1, next, (x) => x._on);
+      }
+    };
+    walk(clips, 0, new Set(opts.inComp ? [opts.inComp] : []), opts.renders || ((c) => c.disabled !== true));
+    return out;
+  }
+  /** The tracks a comp draws in, bottom first (V1 under V2 …), and its audio tracks. */
+  function drawOrder(comp) {
+    const tr = compTracks(comp);
+    return { video: tr.filter((t) => t.kind === "video").map((t) => t.id).reverse(), audio: tr.filter((t) => t.kind === "audio").map((t) => t.id) };
+  }
+
+  /* ── Precompose ── */
+  /** Move `ids` (clips on the main timeline or in comp `from`) into a new comp; put a comp clip
+   *  in their place. Returns { comp, clip }. Times in the comp start at the earliest clip. */
+  function precompose(doc, ids, { id, name, from = null, track } = {}) {
+    const host = from ? getComp(doc, from) : doc;
+    if (!host) throw new Error(`precompose: no comp ${from}`);
+    const set = new Set(ids);
+    const moving = (host.clips || []).filter((c) => set.has(c.id));
+    if (!moving.length) throw new Error("precompose: none of those clips are there");
+    const t0 = Math.min(...moving.map((c) => c.start)), t1 = Math.max(...moving.map(clipEnd));
+    const hostTracks = from ? compTracks(host) : (Array.isArray(doc.tracks) && doc.tracks.length ? doc.tracks : DEFAULT_TRACKS);
+    const used = [...new Set(moving.map((c) => c.track))];
+    const tracks = hostTracks.filter((t) => used.includes(t.id)).map((t) => ({ id: t.id, kind: t.kind }));
+    const compId = id || "comp_" + Math.random().toString(36).slice(2, 8);
+    if (getComp(doc, compId)) throw new Error(`precompose: comp ${compId} already exists`);
+    const comp = {
+      id: compId, name: name || "Comp " + ((doc.comps || []).length + 1),
+      width: from ? host.width : (doc.width || 1280), height: from ? host.height : (doc.height || 720),
+      duration: r4(t1 - t0), tracks,
+      clips: moving.map((c) => ({ ...c, start: r4(c.start - t0) })),
+    };
+    // a hidden track stays hidden inside the comp
+    const hidden = (host.disabledTracks || []).filter((t) => used.includes(t));
+    if (hidden.length) comp.disabledTracks = hidden;
+    // parents outside the moved set can't follow into the comp
+    for (const c of comp.clips) if (c.parent && !set.has(c.parent)) delete c.parent;
+    const videoTracks = moving.filter((c) => c.kind !== "audio").map((c) => c.track);
+    const lane = track || videoTracks.sort((a, b) => (parseInt(a.slice(1), 10) || 0) - (parseInt(b.slice(1), 10) || 0))[0] || "V1";
+    const clip = { id: "c_" + Math.random().toString(36).slice(2, 9), kind: "comp", compId, mediaId: null, track: lane, start: r4(t0), in: 0, duration: comp.duration, name: comp.name, props: { fit: "none" } };
+    host.clips = host.clips.filter((c) => !set.has(c.id));
+    host.clips.push(clip);
+    // clips that were parented to a moved clip now follow nothing
+    for (const c of host.clips) if (c.parent && set.has(c.parent)) delete c.parent;
+    doc.comps = [...(doc.comps || []), comp];
+    return { comp, clip };
+  }
+
+  /** One line per comp for status readouts. */
+  function describe(comp) {
+    const kinds = {};
+    for (const c of comp.clips || []) kinds[c.kind] = (kinds[c.kind] || 0) + 1;
+    return `${comp.id} "${comp.name}" ${comp.width}x${comp.height} ${comp.duration}s, ${(comp.clips || []).length} clips` +
+      (Object.keys(kinds).length ? ` (${Object.entries(kinds).map(([k, n]) => `${n} ${k}`).join(", ")})` : "");
+  }
+
+  return { MAX_DEPTH, SEP, DEFAULT_TRACKS, normalizeComp, getComp, usedComps, wouldCycle, usages, compTracks, virtualize, flatten, drawOrder, precompose, describe };
+});

package/edit-ops.js

@@ -19,10 +19,12 @@
    `forDoc(doc, opts)` builds the env from the document itself (its tracks,
    lockedTracks and untargetedTracks) for headless callers. */
 (function (root, factory) {
-  const api = factory();
-  if (typeof module === "object" && module.exports) module.exports = api;
+  const node = typeof module === "object" && module.exports;
+  const api = factory(node ? require("./mask") : root.FableCutMask, node ? require("./tracker") : root.FableCutTracker,
+    node ? require("./motion") : root.FableCutMotion);
+  if (node) module.exports = api;
   else root.FableCutEdit = api;
-})(typeof self !== "undefined" ? self : this, function () {
+})(typeof self !== "undefined" ? self : this, function (MaskLib, TrackLib, MotionLib) {
   "use strict";
 
   const MIN_DUR = 0.05;
@@ -40,8 +42,10 @@
   /* ── Pure clip helpers ── */
   const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
   const clipEnd = (c) => c.start + c.duration;
-  const clipSpeed = (c) => clamp(+(c.props?.speed) || 1, 0.1, 8);
+  const clipSpeed = (c) => (c.kind === "comp" ? 1 : clamp(+(c.props?.speed) || 1, 0.1, 8));
   const isMediaClip = (c) => c.kind === "video" || c.kind === "audio";
+  /** Clips with a source window (`in` into something with a length): media, and comp clips (into their comp). */
+  const hasSourceTime = (c) => isMediaClip(c) || c.kind === "comp";
   const EASE = {
     linear: (u) => u,
     "ease-in": (u) => u * u,
@@ -64,7 +68,7 @@
     return fallback;
   }
   function hasSpeedRamp(c) {
-    return Array.isArray(c.keyframes?.speed) && c.keyframes.speed.length > 0;
+    return c.kind !== "comp" && Array.isArray(c.keyframes?.speed) && c.keyframes.speed.length > 0;   // comps run at 1×
   }
   /** Source time at timeline time t: in + ∫speed (trapezoid, 1/120 s steps). */
   function mediaTimeAt(c, t) {
@@ -92,6 +96,42 @@
     }
     return Object.keys(out).length ? out : undefined;
   }
+  /** A clip's head moved by `offset` s: its mask keys, shape keys and track samples follow, like shiftKF does for keyframes. */
+  function shiftMasks(c, offset) {
+    if (!offset || !c.props) return;
+    const ms = c.props.masks, ts = c.props.tracks, ss = c.props.shapes;
+    if (MotionLib && Array.isArray(ss)) c.props = { ...c.props, shapes: MotionLib.shiftKeys(ss, offset) };
+    if (MaskLib && Array.isArray(ms)) {
+      const next = MaskLib.shiftKeys(ms, offset);
+      if (next !== ms) c.props = { ...c.props, masks: next };
+    }
+    if (TrackLib && Array.isArray(ts)) {
+      const next = TrackLib.shiftTracks(ts, offset);
+      c.props = { ...c.props };
+      if (next.length) c.props.tracks = next; else delete c.props.tracks;
+    }
+  }
+  /** Clips are leaving the document: their children stay where they are. Each child is
+   *  re-parented to the nearest ancestor that stays (or to nothing), with its static
+   *  position / rotation / scale rewritten to hold its place at its own start. Keyed
+   *  channels keep their keys. Call it before the clips are removed. */
+  function detachChildren(project, goneIds) {
+    if (!MotionLib || !goneIds || !goneIds.size) return 0;
+    const byId = (id) => project.clips.find((x) => x.id === id) || null;
+    let n = 0;
+    for (const k of project.clips) {
+      if (!k.parent || goneIds.has(k.id) || !goneIds.has(k.parent)) continue;
+      let up = byId(k.parent), guard = 0;
+      while (up && goneIds.has(up.id) && guard++ < 64) up = up.parent ? byId(up.parent) : null;
+      const next = up && !goneIds.has(up.id) ? up.id : null;
+      const v = MotionLib.reparentValues(k, next, byId, k.start || 0);
+      k.props = { ...(k.props || {}) };
+      for (const [p, val] of Object.entries(v)) if (!(k.keyframes && Array.isArray(k.keyframes[p]) && k.keyframes[p].length)) k.props[p] = val;
+      if (next) k.parent = next; else delete k.parent;
+      n++;
+    }
+    return n;
+  }
   /** Default stereo pan for an isolated linked stem (L −1, R +1, else center). */
   function defaultPanForChannel(ch) {
     if (ch === 0) return -1;
@@ -105,9 +145,16 @@
     const timeAt = env.mediaTimeAt || mediaTimeAt;
     const removed = (c) => { if (env.onRemove) env.onRemove(c); };
     const getMedia = (id) => P().media.find((m) => m.id === id);
+    /** Length of what c's `in` points into (media or comp), 0 when unknown. */
+    const sourceLen = (c) => {
+      if (c.kind === "comp") { const k = (P().comps || []).find((x) => x.id === c.compId); return k ? +k.duration || 0 : 0; }
+      const m = getMedia(c.mediaId);
+      return m ? +m.duration || 0 : 0;
+    };
     const getClip = (id) => P().clips.find((c) => c.id === id) || null;
     const dropClips = (pred) => {
       const project = P();
+      detachChildren(project, new Set(project.clips.filter(pred).map((x) => x.id)));
       const keep = [];
       for (const x of project.clips) { if (pred(x)) removed(x); else keep.push(x); }
       project.clips = keep;
@@ -190,6 +237,7 @@
         linkedId: undefined,
         linkGroup: undefined,
       };
+      shiftMasks(right, cut);
       c.duration = cut;
       c.keyframes = shiftKF(c.keyframes, 0, cut);
       c.transitionOut = undefined;
@@ -270,10 +318,11 @@
         const dIn = t0 - start;
         if (dIn > 1e-6) {
           c.start = t0;
-          if (isMediaClip(c)) c.in += dIn * clipSpeed(c);
+          if (hasSourceTime(c)) c.in += dIn * clipSpeed(c);
           else c.in = 0;
           c.duration -= dIn;
           c.keyframes = shiftKF(c.keyframes, dIn, c.duration);
+          shiftMasks(c, dIn);
           c.transitionIn = undefined;
           changed++;
         }
@@ -559,6 +608,7 @@
               c.start = +t1.toFixed(4);
               c.transitionIn = undefined;
               c.keyframes = shiftKF(c.keyframes, t1 - oldStart, c.duration);
+              shiftMasks(c, t1 - oldStart);
             } else {
               // Stubs on both sides → effectively inside the window.
               drop(c);
@@ -595,6 +645,7 @@
           c.start = +t1.toFixed(4);
           c.transitionIn = undefined;
           c.keyframes = shiftKF(c.keyframes, t1 - oldStart, c.duration);
+          shiftMasks(c, t1 - oldStart);
         }
       }
     }
@@ -657,10 +708,10 @@
 
     /** Longest this clip may run before it runs out of source media. */
     function maxClipDur(c) {
-      if (!isMediaClip(c)) return Infinity;
-      const m = getMedia(c.mediaId);
-      if (!m || !(m.duration > 0)) return Infinity;
-      return Math.max(MIN_DUR, (m.duration - c.in) / clipSpeed(c));
+      if (!hasSourceTime(c)) return Infinity;
+      const len = sourceLen(c);
+      if (!(len > 0)) return Infinity;
+      return Math.max(MIN_DUR, (len - c.in) / clipSpeed(c));
     }
     /* A linked group shares its timing, but a partner may run at a different
        speed (links are inferred from timing alone), so every source limit is the
@@ -671,7 +722,7 @@
     }
     /** How far c's group can pull its head back before any member reaches source 0. */
     function groupHeadRoom(c) {
-      return Math.min(...withLinked([c]).map((x) => (isMediaClip(x) ? x.in / clipSpeed(x) : Infinity)));
+      return Math.min(...withLinked([c]).map((x) => (hasSourceTime(x) ? x.in / clipSpeed(x) : Infinity)));
     }
     /** The clip butting against c's head ("in") or tail ("out") on its track. */
     function adjacentClip(c, side) {
@@ -707,9 +758,10 @@
     function trimGroupHead(c, d, moveStart) {
       for (const x of withLinked([c])) {
         if (moveStart) x.start = +(x.start + d).toFixed(4);
-        if (isMediaClip(x)) x.in = +(x.in + d * clipSpeed(x)).toFixed(4);
+        if (hasSourceTime(x)) x.in = +(x.in + d * clipSpeed(x)).toFixed(4);
         x.duration = +(x.duration - d).toFixed(4);
         x.keyframes = shiftKF(x.keyframes, d, x.duration);
+        shiftMasks(x, d);
         clampTransitions(x);
       }
     }
@@ -776,7 +828,7 @@
      *  delta > 0 drags the picture right, i.e. earlier source. Position and
      *  length stay; clip-local keyframes stay put on the timeline. */
     function slipClip(c, delta) {
-      if (!isMediaClip(c)) return "Slip needs a video or audio clip — stills and titles have no source time";
+      if (!hasSourceTime(c)) return "Slip needs a video or audio clip, or a comp clip — stills and titles have no source time";
       if (isGroupLocked(c)) return TRIM_LOCKED;
       const sp = clipSpeed(c);
       const group = withLinked([c]);
@@ -784,9 +836,9 @@
       // consumes its own span of source (speed can differ across the group).
       let maxIn = Infinity;
       for (const x of group) {
-        if (!isMediaClip(x)) continue;
-        const m = getMedia(x.mediaId);
-        if (m && m.duration > 0) maxIn = Math.min(maxIn, Math.max(0, m.duration - (timeAt(x, clipEnd(x)) - x.in)));
+        if (!hasSourceTime(x)) continue;
+        const len = sourceLen(x);
+        if (len > 0) maxIn = Math.min(maxIn, Math.max(0, len - (timeAt(x, clipEnd(x)) - x.in)));
       }
       const newIn = clampD(c.in - delta * sp, 0, maxIn);
       const d = (c.in - newIn) / sp;
@@ -885,6 +937,7 @@
           x.in = +Math.max(0, x.in - e2 * sp).toFixed(4);
           x.duration = +(x.duration + e2).toFixed(4);
           x.keyframes = shiftKF(x.keyframes, -e2, x.duration);
+          shiftMasks(x, -e2);
         }
       }
       d = +Math.min(d, a.duration, b.duration).toFixed(3);
@@ -956,7 +1009,7 @@
 
   return {
     MIN_DUR, MIN_TRANS_DUR, CROSSFADE_DUR, GAP_EPS, TRIM_LOCKED, DEFAULT_TRACKS,
-    clipEnd, clipSpeed, kfChannel, hasSpeedRamp, mediaTimeAt, shiftKF, defaultPanForChannel,
+    clipEnd, clipSpeed, isMediaClip, hasSourceTime, kfChannel, hasSpeedRamp, mediaTimeAt, shiftKF, shiftMasks, detachChildren, defaultPanForChannel,
     create, forDoc,
   };
 });

package/export-jobs.js

@@ -103,14 +103,15 @@ function createExportJobs(opts) {
 
   return {
     /** Queue an export. where: auto (open tab, else headless) · tab · headless.
-     *  kind "scopes" measures one still at `time` instead (fablecut_scopes). */
-    request({ kind = "export", range, profile, time, revision, where = "auto", matte = null }) {
+     *  kind "scopes" measures one still at `time` instead (fablecut_scopes);
+     *  kind "track" follows a region of a clip and saves it (fablecut_track). */
+    request({ kind = "export", range, profile, time, revision, where = "auto", matte = null, mask = null, track = null }) {
       if (!["auto", "tab", "headless"].includes(where)) throw Object.assign(new Error("where must be auto, tab or headless"), { code: 400 });
-      if (kind !== "export" && kind !== "scopes") throw Object.assign(new Error("kind must be export or scopes"), { code: 400 });
+      if (!["export", "scopes", "track"].includes(kind)) throw Object.assign(new Error("kind must be export, scopes or track"), { code: 400 });
       if (time != null && !(Number.isFinite(time) && time >= 0)) throw Object.assign(new Error("time must be seconds ≥ 0"), { code: 400 });
       if (range != null && range !== "entire" && range !== "in-out") throw Object.assign(new Error("range must be \"entire\" or \"in-out\""), { code: 400 });
       const busy = [...jobs.values()].find((j) => !isEnded(j));
-      if (busy) throw Object.assign(new Error(`${busy.kind === "scopes" ? "scope reading" : "export"} ${busy.id} is still ${busy.status} — wait for it, or cancel it`), { code: 409 });
+      if (busy) throw Object.assign(new Error(`${busy.kind === "scopes" ? "scope reading" : busy.kind === "track" ? "tracking job" : "export"} ${busy.id} is still ${busy.status} — wait for it, or cancel it`), { code: 409 });
       const tabs = opts.editors();
       if (where === "tab" && !tabs) throw Object.assign(new Error("no editor tab is open — open the editor, or use where:\"headless\""), { code: 409 });
       const now = Date.now();
@@ -118,6 +119,8 @@ function createExportJobs(opts) {
         id: "x_" + Math.random().toString(36).slice(2, 10), kind, status: "pending", progress: 0,
         range: range || null, profile: profile || null, time: time ?? null, revision: Number.isFinite(revision) ? revision : null,
         matte: kind === "scopes" && matte ? { clip: String(matte.clip), layer: matte.layer } : null,
+        mask: kind === "scopes" && mask ? { clip: String(mask.clip) } : null,
+        track: kind === "track" && track ? track : null,
         via: where === "headless" || (where === "auto" && !tabs) ? "headless" : "tab",
         created: now, updated: now,
       };
@@ -129,7 +132,7 @@ function createExportJobs(opts) {
     },
     get(id) { const j = jobs.get(id); return j ? view(j) : null; },
     /** What a tab needs to run the job (headless pages fetch it by id). */
-    ticket(id) { const j = jobs.get(id); return j ? { id: j.id, kind: j.kind, range: j.range, profile: j.profile, time: j.time, revision: j.revision, matte: j.matte || null, status: j.status } : null; },
+    ticket(id) { const j = jobs.get(id); return j ? { id: j.id, kind: j.kind, range: j.range, profile: j.profile, time: j.time, revision: j.revision, matte: j.matte || null, mask: j.mask || null, track: j.track || null, status: j.status } : null; },
     /** First tab to claim a pending job runs it. */
     claim(id) {
       const j = jobs.get(id);