davinci-resolve-mcp 2.27.2 → 2.28.0

package/src/utils/project_spec.py

@@ -0,0 +1,428 @@
+"""Declarative project spec — "kubectl apply" for a Resolve project.
+
+A `project.dvr.yaml` (or .json) describes the *desired* project: settings, color
+preset, timelines, markers, and optional before/after hooks. `plan_spec` diffs
+the desired state against live state and emits an ordered `Action` list **without
+mutating**; `apply_spec` executes that plan through an injected executor.
+
+Separation of concerns so it unit-tests without Resolve:
+  - load_spec / validation / plan_spec  → pure (dicts + dataclasses)
+  - apply_spec                          → orchestrator over an injected executor
+                                          (the server provides a live executor;
+                                          tests provide a fake one)
+
+Structure adapted from the MIT-licensed `mhadifilms/dvr` `spec.py`/`apply`:
+SETTINGS_ORDER (color framework before dependent keys), preset-merge (explicit
+settings override the named preset), marker idempotency, and error accumulation.
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+from src.utils import structural_diff
+
+
+# ── Color presets ────────────────────────────────────────────────────────────
+# Minimal, real starting set. Explicit `settings:` in the spec override these.
+COLOR_PRESETS: Dict[str, Dict[str, str]] = {
+    "rec709_gamma24": {
+        "colorScienceMode": "davinciYRGBColorManagedv2",
+        "colorSpaceTimeline": "Rec.709 (Scene)",
+        "colorSpaceOutput": "Rec.709 Gamma 2.4",
+    },
+    "rec2020_pq_4000": {
+        "colorScienceMode": "davinciYRGBColorManagedv2",
+        "colorSpaceTimeline": "Rec.2020",
+        "colorSpaceOutput": "Rec.2020 ST2084 (4000 nits)",
+        "hdrMasteringLuminanceMax": "4000",
+    },
+    "aces_cct": {
+        "colorScienceMode": "acescct",
+        "colorAcesIDT": "ACES",
+        "colorAcesODT": "Rec.709",
+    },
+}
+
+# Keys applied first (in this relative order) so the color framework is enabled
+# before dependent input/output/HDR keys. Everything not listed is applied after.
+SETTINGS_ORDER: List[str] = [
+    "colorScienceMode",
+    "rcmPresetMode",
+    "colorVersion",
+    "colorAcesIDT",
+    "colorAcesNodeLUTProcessingSpace",
+    "colorAcesODT",
+    "colorSpaceInput",
+    "colorSpaceTimeline",
+    "colorSpaceOutput",
+    "hdrMasteringLuminanceMax",
+]
+
+
+# ── Dataclasses ──────────────────────────────────────────────────────────────
+@dataclass
+class TimelineSpec:
+    name: str
+    fps: Optional[float] = None
+    settings: Dict[str, str] = field(default_factory=dict)
+    markers: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class Hook:
+    when: str          # "before" | "after"
+    command: str
+    name: str = ""
+
+
+@dataclass
+class Spec:
+    project: str
+    color_preset: Optional[str] = None
+    settings: Dict[str, str] = field(default_factory=dict)
+    timelines: List[TimelineSpec] = field(default_factory=list)
+    hooks: List[Hook] = field(default_factory=list)
+
+
+@dataclass
+class Action:
+    op: str            # create | ensure | set | noop
+    target: str        # "project:Show", "timeline:Edit_v2/setting:timelineFrameRate", ...
+    detail: str = ""
+    payload: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"op": self.op, "target": self.target, "detail": self.detail, "payload": self.payload}
+
+
+class SpecError(Exception):
+    """Raised on malformed spec or accumulated apply failures.
+
+    Carries `state` so the server can surface it in the structured error envelope.
+    """
+
+    def __init__(self, message: str, *, state: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.message = message
+        self.state = state or {}
+
+
+# ── Loading & validation ─────────────────────────────────────────────────────
+def _parse_hooks(raw: Any) -> List[Hook]:
+    hooks: List[Hook] = []
+    if not raw:
+        return hooks
+    for when in ("before", "after"):
+        for entry in (raw.get(when) or []) if isinstance(raw, dict) else []:
+            if isinstance(entry, str):
+                hooks.append(Hook(when=when, command=entry))
+            elif isinstance(entry, dict) and entry.get("command"):
+                hooks.append(Hook(when=when, command=str(entry["command"]), name=str(entry.get("name", ""))))
+            else:
+                raise SpecError(f"Invalid {when}-hook entry: {entry!r}")
+    return hooks
+
+
+def spec_from_dict(data: Dict[str, Any]) -> Spec:
+    """Validate a plain dict into a `Spec`. Raises `SpecError` on bad shape."""
+    if not isinstance(data, dict):
+        raise SpecError("Spec must be a mapping at the top level.")
+    project = data.get("project")
+    if not project or not isinstance(project, str):
+        raise SpecError("Spec requires a non-empty string `project`.", state={"got": data.get("project")})
+
+    preset = data.get("color_preset")
+    if preset is not None and preset not in COLOR_PRESETS:
+        raise SpecError(
+            f"Unknown color_preset '{preset}'.",
+            state={"known_presets": sorted(COLOR_PRESETS)},
+        )
+
+    settings = data.get("settings") or {}
+    if not isinstance(settings, dict):
+        raise SpecError("`settings` must be a mapping.")
+
+    timelines: List[TimelineSpec] = []
+    for raw_tl in (data.get("timelines") or []):
+        if not isinstance(raw_tl, dict) or not raw_tl.get("name"):
+            raise SpecError(f"Each timeline needs a `name`: {raw_tl!r}")
+        timelines.append(TimelineSpec(
+            name=str(raw_tl["name"]),
+            fps=float(raw_tl["fps"]) if raw_tl.get("fps") is not None else None,
+            settings=dict(raw_tl.get("settings") or {}),
+            markers=list(raw_tl.get("markers") or []),
+        ))
+
+    return Spec(
+        project=str(project),
+        color_preset=preset,
+        settings={str(k): str(v) for k, v in settings.items()},
+        timelines=timelines,
+        hooks=_parse_hooks(data.get("hooks")),
+    )
+
+
+def load_spec(path: str) -> Spec:
+    """Load a spec from a YAML or JSON file. YAML needs PyYAML; JSON always works."""
+    if not os.path.isfile(path):
+        raise SpecError(f"Spec file not found: {path}", state={"path": path})
+    with open(path, "r", encoding="utf-8") as fh:
+        text = fh.read()
+    data: Any
+    if path.endswith((".yaml", ".yml")):
+        try:
+            import yaml  # type: ignore
+        except ImportError as exc:  # pragma: no cover - env-dependent
+            raise SpecError(
+                "PyYAML is required to load .yaml specs (pip install pyyaml), "
+                "or provide the spec as .json.",
+                state={"path": path},
+            ) from exc
+        data = yaml.safe_load(text)
+    else:
+        data = json.loads(text)
+    return spec_from_dict(data)
+
+
+# ── Effective settings (preset merge + ordering) ─────────────────────────────
+def effective_settings(spec: Spec) -> "Dict[str, str]":
+    """Preset settings overlaid by explicit spec.settings (explicit wins)."""
+    merged: Dict[str, str] = {}
+    if spec.color_preset:
+        merged.update(COLOR_PRESETS[spec.color_preset])
+    merged.update(spec.settings)
+    return merged
+
+
+def _ordered_setting_keys(keys: List[str]) -> List[str]:
+    head = [k for k in SETTINGS_ORDER if k in keys]
+    tail = sorted(k for k in keys if k not in SETTINGS_ORDER)
+    return head + tail
+
+
+def _norm_setting_value(value: Any) -> str:
+    """Canonicalize a setting value for comparison. Resolve reports numeric
+    settings with float formatting (e.g. timelineFrameRate -> "24.0") even when
+    the spec says "24"; normalize both so reconcile actually converges (and apply
+    is idempotent). Non-numeric values are returned as plain strings."""
+    s = str(value)
+    try:
+        f = float(s)
+    except (TypeError, ValueError):
+        return s
+    return str(int(f)) if f == int(f) else repr(f)
+
+
+def _settings_equal(a: Any, b: Any) -> bool:
+    return _norm_setting_value(a) == _norm_setting_value(b)
+
+
+# ── Plan ─────────────────────────────────────────────────────────────────────
+def plan_spec(spec: Spec, live: Dict[str, Any]) -> Dict[str, Any]:
+    """Compute the ordered action list + a structural diff. PURE — no mutation.
+
+    `live` is the current state:
+        {"project": str|None, "projects": [names],
+         "settings": {k: v},
+         "timelines": [{"name", "fps", "settings": {...}, "markers": [{frame,...}]}]}
+    """
+    live = live or {}
+    actions: List[Action] = []
+
+    # Project
+    known = set(live.get("projects") or [])
+    if spec.project in known or live.get("project") == spec.project:
+        actions.append(Action("noop", f"project:{spec.project}", "exists"))
+    else:
+        actions.append(Action("create", f"project:{spec.project}", "create project"))
+
+    # Project settings (preset-merged, dependency-ordered)
+    live_settings = live.get("settings") or {}
+    desired = effective_settings(spec)
+    for key in _ordered_setting_keys(list(desired)):
+        want = desired[key]
+        if _settings_equal(live_settings.get(key, ""), want):
+            actions.append(Action("noop", f"project:{spec.project}/setting:{key}", "matches"))
+        else:
+            actions.append(Action(
+                "set", f"project:{spec.project}/setting:{key}",
+                f"{live_settings.get(key)!r} -> {want!r}", {"key": key, "value": want},
+            ))
+
+    # Timelines + their settings + markers. NOTE: `fps` is a *creation-time*
+    # property handled by ensure_timeline — Resolve refuses SetSetting on
+    # timelineFrameRate after a timeline exists — so it is never emitted as a
+    # per-timeline `set` action.
+    live_tls = {tl.get("name"): tl for tl in (live.get("timelines") or [])}
+    for tl in spec.timelines:
+        live_tl = live_tls.get(tl.name)
+        if live_tl is None:
+            actions.append(Action("ensure", f"timeline:{tl.name}", "create timeline",
+                                   {"fps": tl.fps}))
+        else:
+            actions.append(Action("noop", f"timeline:{tl.name}", "exists"))
+
+        live_tl_settings = (live_tl or {}).get("settings") or {}
+        for key in _ordered_setting_keys(list(tl.settings)):
+            want = tl.settings[key]
+            if _settings_equal(live_tl_settings.get(key, ""), want):
+                actions.append(Action("noop", f"timeline:{tl.name}/setting:{key}", "matches"))
+            else:
+                actions.append(Action("set", f"timeline:{tl.name}/setting:{key}",
+                                       f"{live_tl_settings.get(key)!r} -> {want!r}",
+                                       {"key": key, "value": want}))
+
+        live_frames = {m.get("frame") for m in ((live_tl or {}).get("markers") or [])}
+        for marker in tl.markers:
+            frame = marker.get("frame")
+            if frame in live_frames:
+                actions.append(Action("noop", f"timeline:{tl.name}/marker:{frame}", "exists"))
+            else:
+                actions.append(Action("set", f"timeline:{tl.name}/marker:{frame}",
+                                       "add marker", {"marker": marker}))
+
+    diff = structural_diff.compare(
+        _spec_normalized_state(live, spec),
+        _spec_desired_state(spec),
+        left_label="live", right_label="spec",
+    )
+    return {
+        "actions": [a.to_dict() for a in actions],
+        "diff": diff.to_dict(),
+        "change_count": sum(1 for a in actions if a.op != "noop"),
+    }
+
+
+def _spec_desired_state(spec: Spec) -> Dict[str, Any]:
+    return {
+        "project": spec.project,
+        "settings": {k: _norm_setting_value(v) for k, v in effective_settings(spec).items()},
+        "timelines": [
+            {
+                "name": tl.name,
+                "settings": {k: _norm_setting_value(v) for k, v in tl.settings.items()},
+                "markers": [{"frame": m.get("frame"), **{k: v for k, v in m.items() if k != "frame"}}
+                            for m in tl.markers],
+            }
+            for tl in spec.timelines
+        ],
+    }
+
+
+def _spec_normalized_state(live: Dict[str, Any], spec: Spec) -> Dict[str, Any]:
+    """Project live state onto only the keys the spec cares about, so the diff
+    reports drift toward the spec rather than every unrelated live setting.
+    Values are normalized so numeric formatting (24 vs 24.0) is not a phantom
+    diff."""
+    desired = effective_settings(spec)
+    live_settings = live.get("settings") or {}
+    spec_tl_names = {tl.name for tl in spec.timelines}
+    live_tls = {tl.get("name"): tl for tl in (live.get("timelines") or [])}
+    return {
+        "project": live.get("project"),
+        "settings": {k: _norm_setting_value(live_settings.get(k)) for k in desired if k in live_settings},
+        "timelines": [
+            {
+                "name": name,
+                "settings": {k: _norm_setting_value((live_tls[name].get("settings") or {}).get(k))
+                             for k in (next((t.settings for t in spec.timelines if t.name == name), {}))
+                             if k in (live_tls[name].get("settings") or {})},
+                "markers": live_tls[name].get("markers") or [],
+            }
+            for name in spec_tl_names if name in live_tls
+        ],
+    }
+
+
+# ── Apply (orchestrator over an injected executor) ───────────────────────────
+def apply_spec(
+    spec: Spec,
+    executor: Any,
+    *,
+    dry_run: bool = False,
+    run_hooks: bool = False,
+    continue_on_error: bool = False,
+    run_hook: Optional[Callable[[Hook], Any]] = None,
+) -> Dict[str, Any]:
+    """Reconcile live state toward `spec` through `executor`.
+
+    `executor` is duck-typed; it must provide:
+        live_state() -> dict
+        ensure_project(name) -> bool
+        set_project_setting(key, value) -> bool
+        ensure_timeline(name, fps) -> bool
+        set_timeline_setting(timeline_name, key, value) -> bool
+        add_marker(timeline_name, marker: dict) -> bool
+
+    Hooks execute only when `run_hooks=True` AND a `run_hook` callable is given —
+    arbitrary shell from a spec stays opt-in. Failures accumulate when
+    `continue_on_error`; otherwise the first failure raises `SpecError`.
+    """
+    live = executor.live_state()
+    plan = plan_spec(spec, live)
+    if dry_run:
+        return {"success": True, "dry_run": True, **plan}
+
+    failures: List[Dict[str, Any]] = []
+    applied: List[Dict[str, Any]] = []
+
+    def _record(ok: bool, target: str, detail: str = "") -> None:
+        entry = {"target": target, "detail": detail}
+        if ok:
+            applied.append(entry)
+        else:
+            failures.append(entry)
+            if not continue_on_error:
+                raise SpecError(
+                    f"apply failed at {target}",
+                    state={"project": spec.project, "failures": failures, "applied": applied},
+                )
+
+    befores = [h for h in spec.hooks if h.when == "before"]
+    afters = [h for h in spec.hooks if h.when == "after"]
+
+    if run_hooks and run_hook:
+        for h in befores:
+            _record(bool(run_hook(h)), f"hook:before:{h.name or h.command}")
+
+    # Project + settings
+    _record(bool(executor.ensure_project(spec.project)), f"project:{spec.project}")
+    desired = effective_settings(spec)
+    for key in _ordered_setting_keys(list(desired)):
+        if _settings_equal((live.get("settings") or {}).get(key, ""), desired[key]):
+            continue
+        _record(bool(executor.set_project_setting(key, desired[key])),
+                f"project:{spec.project}/setting:{key}", str(desired[key]))
+
+    # Timelines. `fps` is creation-time only (ensure_timeline); never set as a
+    # post-creation timelineFrameRate setting — Resolve refuses that.
+    live_tls = {tl.get("name"): tl for tl in (live.get("timelines") or [])}
+    for tl in spec.timelines:
+        _record(bool(executor.ensure_timeline(tl.name, tl.fps)), f"timeline:{tl.name}")
+        live_tl_settings = (live_tls.get(tl.name) or {}).get("settings") or {}
+        for key in _ordered_setting_keys(list(tl.settings)):
+            if _settings_equal(live_tl_settings.get(key, ""), tl.settings[key]):
+                continue
+            _record(bool(executor.set_timeline_setting(tl.name, key, tl.settings[key])),
+                    f"timeline:{tl.name}/setting:{key}", str(tl.settings[key]))
+        live_frames = {m.get("frame") for m in ((live_tls.get(tl.name) or {}).get("markers") or [])}
+        for marker in tl.markers:
+            if marker.get("frame") in live_frames:
+                continue
+            _record(bool(executor.add_marker(tl.name, marker)),
+                    f"timeline:{tl.name}/marker:{marker.get('frame')}")
+
+    if run_hooks and run_hook:
+        for h in afters:
+            _record(bool(run_hook(h)), f"hook:after:{h.name or h.command}")
+
+    return {
+        "success": not failures,
+        "applied_count": len(applied),
+        "applied": applied,
+        "failures": failures,
+        "project": spec.project,
+    }

package/src/utils/structural_diff.py

@@ -0,0 +1,175 @@
+"""Structural diff over plain JSON-able state (snapshots, specs).
+
+A general recursive diff that classifies every leaf change as added / removed /
+changed, and — crucially — aligns *lists* by a stable identity key before
+comparing, so a reordered or trimmed element reads as a move/change instead of a
+wholesale delete+add. This is the substrate the timeline-version diff and the
+declarative-spec `plan` both build on.
+
+Pure and Resolve-free: every function takes plain dicts/lists and returns plain
+data, so it unit-tests without a live Resolve instance.
+
+Design ported (with adaptation) from the MIT-licensed `mhadifilms/dvr` `diff.py`
+`_walk` smart-alignment idea; the identity-key precedence here is tuned for our
+snapshots (stable media id / shot id first, then frame/index, then name).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+# Identity keys tried in order when aligning two lists of dicts. The first key
+# present in an element wins; alignment then matches elements sharing that key's
+# value. Falls back to positional (index) alignment when no key is shared.
+DEFAULT_LIST_KEYS: Tuple[str, ...] = (
+    "clip_hash",            # our rename-stable canonical hash (issue #51)
+    "media_pool_item_id",   # Resolve GetUniqueId — stable across renames
+    "shot_id",
+    "id",
+    "uid",
+    "frame",                # markers
+    "name",
+)
+
+
+@dataclass
+class Change:
+    """One leaf-level difference. `op` ∈ {added, removed, changed}.
+
+    `path` is a dotted/bracketed location, e.g. ``tracks.video[1].name`` or
+    ``markers[frame=0].color``. `before`/`after` are the scalar values (None on
+    the side where the element/leaf is absent).
+    """
+
+    op: str
+    path: str
+    before: Any = None
+    after: Any = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"op": self.op, "path": self.path, "before": self.before, "after": self.after}
+
+
+@dataclass
+class Diff:
+    changes: List[Change] = field(default_factory=list)
+    left_label: str = "before"
+    right_label: str = "after"
+
+    def added(self) -> List[Change]:
+        return [c for c in self.changes if c.op == "added"]
+
+    def removed(self) -> List[Change]:
+        return [c for c in self.changes if c.op == "removed"]
+
+    def changed(self) -> List[Change]:
+        return [c for c in self.changes if c.op == "changed"]
+
+    def is_empty(self) -> bool:
+        return not self.changes
+
+    def summary(self) -> Dict[str, int]:
+        return {
+            "added": len(self.added()),
+            "removed": len(self.removed()),
+            "changed": len(self.changed()),
+            "total": len(self.changes),
+        }
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "left_label": self.left_label,
+            "right_label": self.right_label,
+            "summary": self.summary(),
+            "changes": [c.to_dict() for c in self.changes],
+        }
+
+
+def _identity_key(item: Any, list_keys: Tuple[str, ...]) -> Optional[Tuple[str, Any]]:
+    """Return (key_name, value) for the first identity key present on a dict item."""
+    if not isinstance(item, dict):
+        return None
+    for key in list_keys:
+        if key in item and item[key] is not None:
+            return (key, item[key])
+    return None
+
+
+def _align_lists(
+    left: List[Any], right: List[Any], list_keys: Tuple[str, ...]
+) -> List[Tuple[Optional[Any], Optional[Any], str]]:
+    """Pair up elements of two lists.
+
+    Returns a list of (left_item, right_item, label) triples. When a shared
+    identity key exists, elements are matched by it (so reorders don't read as
+    delete+add); otherwise alignment is positional. `label` is the path segment
+    used for the pair (``[key=value]`` for keyed, ``[i]`` for positional).
+    """
+    # Try keyed alignment first: only viable if *both* sides expose the same key.
+    left_keyed = [(_identity_key(x, list_keys), x) for x in left]
+    right_keyed = [(_identity_key(x, list_keys), x) for x in right]
+    if all(k is not None for k, _ in left_keyed) and all(k is not None for k, _ in right_keyed):
+        pairs: List[Tuple[Optional[Any], Optional[Any], str]] = []
+        right_by_key: Dict[Tuple[str, Any], Any] = {k: v for k, v in right_keyed}  # type: ignore[misc]
+        consumed: set = set()
+        for k, lv in left_keyed:
+            label = f"[{k[0]}={k[1]}]"  # type: ignore[index]
+            if k in right_by_key:
+                pairs.append((lv, right_by_key[k], label))
+                consumed.add(k)
+            else:
+                pairs.append((lv, None, label))
+        for k, rv in right_keyed:
+            if k not in consumed:
+                pairs.append((None, rv, f"[{k[0]}={k[1]}]"))  # type: ignore[index]
+        return pairs
+
+    # Positional fallback.
+    pairs = []
+    for i in range(max(len(left), len(right))):
+        lv = left[i] if i < len(left) else None
+        rv = right[i] if i < len(right) else None
+        pairs.append((lv, rv, f"[{i}]"))
+    return pairs
+
+
+def _walk(left: Any, right: Any, path: str, out: List[Change], list_keys: Tuple[str, ...]) -> None:
+    # Type mismatch or one side missing → record as a changed/added/removed leaf.
+    if isinstance(left, dict) and isinstance(right, dict):
+        for key in sorted(set(left) | set(right)):
+            child_path = f"{path}.{key}" if path else key
+            if key not in left:
+                out.append(Change("added", child_path, None, right[key]))
+            elif key not in right:
+                out.append(Change("removed", child_path, left[key], None))
+            else:
+                _walk(left[key], right[key], child_path, out, list_keys)
+        return
+
+    if isinstance(left, list) and isinstance(right, list):
+        for lv, rv, seg in _align_lists(left, right, list_keys):
+            child_path = f"{path}{seg}"
+            if lv is None:
+                out.append(Change("added", child_path, None, rv))
+            elif rv is None:
+                out.append(Change("removed", child_path, lv, None))
+            else:
+                _walk(lv, rv, child_path, out, list_keys)
+        return
+
+    if left != right:
+        out.append(Change("changed", path or "", left, right))
+
+
+def compare(
+    left: Any,
+    right: Any,
+    *,
+    left_label: str = "before",
+    right_label: str = "after",
+    list_keys: Tuple[str, ...] = DEFAULT_LIST_KEYS,
+) -> Diff:
+    """Diff two JSON-able structures into a `Diff` of leaf-level changes."""
+    out: List[Change] = []
+    _walk(left, right, "", out, list_keys)
+    return Diff(changes=out, left_label=left_label, right_label=right_label)

package/src/utils/timeline_versioning.py

@@ -347,32 +347,54 @@ def diff_versions(
 
     before = _snapshot(from_version)
     after = _snapshot(to_version)
-    # Key on (media_pool_item_id, track_type, track_index, in_frame) — a clip
-    # moved to a different track or trimmed differently counts as a change.
+    # Position key: (media id, track type, track index, in_frame). Same key in
+    # both versions = same placement; a differing out_frame on that same key is
+    # a *trim*. A differing track/in_frame for the same media id is a *move*.
     def _key(row: Dict[str, Any]) -> Tuple[str, str, int, int]:
         return (row["media_pool_item_id"], row["track_type"], row["track_index"], row["in_frame"])
 
-    before_keys = {_key(r) for r in before}
-    after_keys = {_key(r) for r in after}
+    before_by_key = {_key(r): r for r in before}
+    after_by_key = {_key(r): r for r in after}
+    before_keys = set(before_by_key)
+    after_keys = set(after_by_key)
+
     added = [r for r in after if _key(r) not in before_keys]
     removed = [r for r in before if _key(r) not in after_keys]
-    # "moved" approximation: same media id, different (track or in_frame).
+
+    # Trimmed: same placement key in both, but the out_frame differs.
+    trimmed: List[Dict[str, Any]] = []
+    for key in before_keys & after_keys:
+        if before_by_key[key]["out_frame"] != after_by_key[key]["out_frame"]:
+            row = dict(after_by_key[key])
+            row["out_frame_before"] = before_by_key[key]["out_frame"]
+            trimmed.append(row)
+
+    # Moved: same media id present on both sides but at a different placement
+    # (so it shows up in both `added` and `removed` above). Report it once.
     before_by_id: Dict[str, List[Dict[str, Any]]] = {}
     for r in before:
         before_by_id.setdefault(r["media_pool_item_id"], []).append(r)
     moved: List[Dict[str, Any]] = []
-    for r in after:
+    for r in added:
         prevs = before_by_id.get(r["media_pool_item_id"])
-        if not prevs:
-            continue
-        if any(_key(p) != _key(r) for p in prevs):
+        if prevs and any(_key(p) != _key(r) for p in prevs):
             moved.append(r)
+
     return {
         "from_version": from_version,
         "to_version": to_version,
         "added": added,
         "removed": removed,
         "moved": moved,
+        "trimmed": trimmed,
+        "summary": {
+            "added": len(added),
+            "removed": len(removed),
+            "moved": len(moved),
+            "trimmed": len(trimmed),
+            "before_clip_count": len(before),
+            "after_clip_count": len(after),
+        },
     }