feat: an effect knows the call that wrote it

The timeline could say a shader ran between two frames. It could not say
what in the scene asked for it, so a row named `Scale` was talking about
the renderer while the person was looking at `scaleTo(0.5, duration=1.2)`.

Every `apply()` now leaves a statement behind — file, line, the library
function the person actually called, and the frames each shader key was
written over. The serialiser hands each run to the statement that covers
most of it, and between statements that cover it equally, to the one that
touched the fewest kinds: a group re-emits position, rotation and scale on
every pass, so `scaleTo` is a better answer for a Scale run than `rotateBy`.

Runs from one statement become one row, and that row is the SHORTEST of
them rather than their union. A group's `scaleTo` writes scale for its own
second and a half and position for as long as anything in the group moves;
the union said the call lasted as long as the group did, so shortening it
left the bar exactly where it was.

`removeCallSpan` is the other half of writing: the span that takes a call
OUT. A link in a chain loses its link, a statement of its own takes its
line with it, and a call nested in something else — the `Square(...)` that
made the element — is refused rather than guessed at.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: anpawo

test/edit_test.py

@@ -13,7 +13,16 @@
 sys.path.insert(0, "test")
 from helpers import check, section, summary
 
-from videocode.edit import argumentSpan, callLine, findCalls, readArgument, removeArgument, setArgument
+from videocode.edit import (
+    argumentSpan,
+    callLine,
+    findCalls,
+    positionalSpan,
+    readArgument,
+    removeArgument,
+    removeCallSpan,
+    setArgument,
+)
 
 SOURCE = '''#!/usr/bin/env python3
 
@@ -130,5 +139,62 @@ def untouched(before: str, after: str, except_: int) -> bool:
 edit = setArgument(broken, 1, "Square", "side", "2")
 check("returned unchanged", edit.source == broken and not edit.changed)
 
+# ── An argument with no name ───────────────────────────────────────────────
+section("positionalSpan — `wait(0.3)` writes its seconds without a name")
+span = positionalSpan(SOURCE, 8, "wait", 0, "0.6")
+check("a span was given", span is not None)
+if span is not None:
+    start, end, text = span
+    check("it replaces the number, nothing more", SOURCE[start:end] == "0.3" and text == "0.6")
+    edited = SOURCE[:start] + text + SOURCE[end:]
+    check("the line reads as written", line(edited, 8) == "wait(0.6)")
+    check("every other line is untouched", untouched(SOURCE, edited, 8))
+
+check("the same value is no span at all", positionalSpan(SOURCE, 8, "wait", 0, "0.3") is None)
+
+empty = "wait()\n"
+span = positionalSpan(empty, 1, "wait", 0, "0.5")
+check("an argument that is not there yet is appended", span is not None)
+if span is not None:
+    start, end, text = span
+    check("with no stray separator", empty[:start] + text + empty[end:] == "wait(0.5)\n")
+
+check("a slot cannot be skipped", positionalSpan(empty, 1, "wait", 2, "0.5") is None)
+
+# ── Taking a call away ─────────────────────────────────────────────────────
+section("removeCallSpan — a link in a chain loses only its link")
+span = removeCallSpan(SOURCE, 10, "scaleTo")
+check("a span was given", span is not None)
+if span is not None:
+    start, end, text = span
+    edited = SOURCE[:start] + text + SOURCE[end:]
+    check("the scale is gone", line(edited, 10) == "Group(square, circle).rotateBy(180, duration=1.5)")
+    check("the file still parses", isinstance(compile(edited, "scene.py", "exec"), object))
+    check("every other line is untouched", untouched(SOURCE, edited, 10))
+
+span = removeCallSpan(SOURCE, 10, "rotateBy")
+check("the middle link goes too, and only it", span is not None)
+if span is not None:
+    start, end, text = span
+    edited = SOURCE[:start] + text + SOURCE[end:]
+    check("what is left is the rest of the chain",
+          line(edited, 10) == "Group(square, circle).scaleTo(0.5, duration=0.5)")
+
+section("removeCallSpan — a statement of its own takes its line")
+alone = "square = Square(side=1)\nsquare.fadeIn()\nsquare.moveBy(x=1)\n"
+span = removeCallSpan(alone, 2, "fadeIn")
+check("a span was given", span is not None)
+if span is not None:
+    start, end, text = span
+    edited = alone[:start] + text + alone[end:]
+    check("the line went with it, newline included",
+          edited == "square = Square(side=1)\nsquare.moveBy(x=1)\n")
+    check("no bare name left behind", "square\n" not in edited)
+
+section("removeCallSpan — what it refuses")
+check("a call that is not there", removeCallSpan(SOURCE, 10, "moveBy") is None)
+check("the call that MADE the element", removeCallSpan(SOURCE, 5, "Square") is None)
+check("broken source", removeCallSpan("square.fadeIn(\n", 1, "fadeIn") is None)
+
 # ── summary ────────────────────────────────────────────────────────────────
 summary()

videocode/context.py

@@ -275,10 +275,18 @@ def _callSite() -> tuple[str, int, str]:
 
         frame = sys._getframe(2)
         cls = ""
+        # The last library function crossed on the way out — `moveBy`,
+        # `scaleTo`, `fadeIn`. The stack knows which method a person called; the
+        # shaders it produced do not, and the editor needs it to offer "remove
+        # this" on the right call of a chain rather than on the whole line.
+        func = ""
         while frame is not None:
             name = frame.f_code.co_filename
             if not name.startswith(library):
+                Context.lastCallFunction = func
                 return (name, frame.f_lineno, cls)
+            if not frame.f_code.co_name.startswith("_") and frame.f_code.co_name not in ("apply", "broadcast", "noteStatement"):
+                func = frame.f_code.co_name
             # The OUTERMOST library frame's `self`, not the innermost: a
             # `Text` builds `Letter`s, and the letter is an implementation
             # detail of the word. Overwriting as the walk goes outward leaves
@@ -287,8 +295,36 @@ def _callSite() -> tuple[str, int, str]:
             if owner is not None:
                 cls = type(owner).__name__
             frame = frame.f_back
+        Context.lastCallFunction = func
         return ("", 0, cls)
 
+    # One entry per apply() that reached the stack: which input, which line of
+    # the person's file, which shader keys, and the frames it covers. A SIDE
+    # TABLE like `origin` — the stack itself is handed to C++ and diffed, so
+    # nothing that is only for the editor may live in it.
+    statements: list[dict[str, Any]] = []
+
+    # Filled by the last `_callSite()`: the library function the person called.
+    lastCallFunction: str = ""
+
+    @staticmethod
+    def noteStatement(inputIndex: int, touched: dict[str, list[int]]) -> None:
+        """
+        Record where a statement was written, and what it covers.
+
+        The line is read here rather than per shader: the walk out of the library
+        costs about 2 µs, an animation is hundreds of shaders, and every one of
+        them came from the same line anyway.
+        """
+        file, line, _ = Context._callSite()
+        Context.statements.append({
+            "file": file,
+            "line": line,
+            "call": Context.lastCallFunction,
+            "input": inputIndex,
+            "keys": {name: (span[0], span[1]) for name, span in touched.items()},
+        })
+
     @staticmethod
     def apply(inputIndex: int, shaderName: str, shaderType: str, shaderArgs: dict[str, Any]):
         frameIdx = shaderArgs["start"]

videocode/edit.py

@@ -214,6 +214,47 @@ def argumentSpan(
     return closing, closing, f"{separator}{name}={value}"
 
 
+def positionalSpan(
+    source: str,
+    line: int,
+    call: str,
+    index: int,
+    value: str,
+    occurrence: int = 0,
+) -> tuple[int, int, str] | None:
+    """
+    The same as `argumentSpan`, for an argument that has no name.
+
+    `wait(0.3)` is the case that asked for it: the number is written in the
+    brackets, not after an `=`, and a timeline that lets you drag a gap has to
+    rewrite exactly that. Missing arguments are appended in order — `wait()`
+    takes a first positional the way `wait(0.3)` already has one.
+    """
+    node = _pick(source, line, call, occurrence)
+    if node is None:
+        return None
+
+    if index < len(node.args):
+        start, end = _span(source, node.args[index])
+        if source[start:end] == value:
+            return None
+        return start, end, value
+
+    # Only the argument straight after the last one written can be added: there
+    # is no way to skip a slot without naming it, and guessing a name here would
+    # be inventing part of a signature.
+    if index != len(node.args) or node.keywords:
+        return None
+
+    start, end = _span(source, node)
+    closing = source.rfind(")", start, end)
+    if closing < 0:
+        return None
+
+    separator = ", " if node.args else ""
+    return closing, closing, f"{separator}{value}"
+
+
 def removeArgument(source: str, line: int, call: str, name: str, occurrence: int = 0) -> Edit:
     """
     Take a keyword argument out, and the separator that came with it.
@@ -249,6 +290,70 @@ def removeArgument(source: str, line: int, call: str, name: str, occurrence: int
     return Edit(source, False, f"no argument named {name!r}")
 
 
+def removeCallSpan(
+    source: str,
+    line: int,
+    call: str,
+    occurrence: int = 0,
+) -> tuple[int, int, str] | None:
+    """
+    The span that takes a call away, as a range to replace with nothing.
+
+    Two shapes, told apart by what is left behind:
+
+    - a link in a chain — `Group(a, b).scaleTo(0.5).rotateBy(180)` — where only
+      `.scaleTo(0.5)` goes, from the end of what it was called on to its own end;
+    - a statement of its own — `square.fadeIn()` — where removing the link would
+      leave the bare name `square` sitting on a line, so the line goes with it,
+      newline included.
+
+    `None` when the call is not there, or when it is nested inside something
+    else (an argument, an assignment's value): taking it out then changes what
+    the surrounding expression means, and a gesture may not do that quietly.
+    """
+    node = _pick(source, line, call, occurrence)
+    if node is None:
+        return None
+
+    start, end = _span(source, node)
+
+    # Where the link begins: just after whatever it was called on.
+    if not isinstance(node.func, ast.Attribute):
+        receiverEnd = start
+    else:
+        receiverEnd = _span(source, node.func.value)[1]
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+
+    # The statement this call sits in, and whether the call IS all of it.
+    for statement in ast.walk(tree):
+        if not isinstance(statement, ast.Expr):
+            continue
+        if _span(source, statement) != (start, end) and _span(source, statement.value) != (start, end):
+            continue
+
+        # Only when nothing else on the line does anything. `square.fadeIn()`
+        # leaves a bare name behind, so the line goes; but the last link of
+        # `Group(a, b).scaleTo(0.5).rotateBy(180)` is also the outermost call,
+        # and taking its line would take the scale with it.
+        if any(isinstance(inner, ast.Call) for inner in ast.walk(node.func)):
+            break
+
+        offsets = _offsets(source)
+        lineStart = offsets[statement.lineno]
+        lineEnd = offsets[(statement.end_lineno or statement.lineno) + 1] if (statement.end_lineno or statement.lineno) + 1 < len(offsets) else len(source)
+        if source[lineStart:_span(source, statement)[0]].strip() == "":
+            return lineStart, lineEnd, ""
+
+    # A link in a chain, and only a link.
+    if receiverEnd == start:
+        return None
+    return receiverEnd, end, ""
+
+
 def callLine(source: str, name: str, occurrence: int = 0) -> int:
     """
     Where a call is, for a caller that knows the name but not the line.

videocode/input/input.py

@@ -94,6 +94,8 @@ def apply(self, *shaders: IShader | Effect | GroupEffect, start: sec = 0, durati
         if Context.waitOffset >= self.meta.transformationOffset:
             self.waitTo(Context.waitOffset)
 
+        touched: dict[str, list[int]] = {}
+
         flatten: list[IShader] = []
         for s in shaders:
             if not isinstance(s, IShader):
@@ -156,12 +158,31 @@ def apply(self, *shaders: IShader | Effect | GroupEffect, start: sec = 0, durati
             args = {k: v for k, v in vars(s).items() if k not in ("start", "duration", "offset")} | {"start": __start, "duration": __duration}
 
             # Add step to the stack
-            Context.apply(self.meta.index, upperFirst(s.__class__.__name__), s._type, args)
+            key = upperFirst(s.__class__.__name__)
+            Context.apply(self.meta.index, key, s._type, args)
+
+            # What this STATEMENT touched, for the editor.
+            #
+            # A shader on the stack says what happens on a frame; it does not say
+            # which line asked for it, and the editor needs that to let you move,
+            # shorten or delete an effect by its bar rather than by finding the
+            # call yourself. Gathered per apply() — one call is one statement —
+            # and the source line is read once at the end, because the walk out
+            # of the library costs 2 µs and an animation is hundreds of shaders.
+            span = touched.get(key)
+            if span is None:
+                touched[key] = [__start, __end]
+            else:
+                span[0] = min(span[0], __start)
+                span[1] = max(span[1], __end)
 
             # Post-callbacks
             for callback in self.meta.postCallbacks.get(type(s), []):
                 callback(s, start, duration, offset if offset is not None else self.meta.transformationOffset)
 
+        if touched:
+            Context.noteStatement(self.meta.index, touched)
+
         return self
 
     def __setattr__(self, name: str, value: Any) -> None:

videocode/serialize.py

@@ -148,11 +148,84 @@ def sceneModel() -> dict:
                 else:
                     spans.append([frame, frame])
 
-        effects = [
-            {"name": key, "start": span[0], "end": span[1]}
-            for key, spans in runs.items()
-            for span in spans
-        ]
+        # Where each run was WRITTEN.
+        #
+        # A run is frames on the stack; the editor needs the line that asked for
+        # them, or an effect can only be read, never moved, shortened or deleted.
+        # `Context.statements` holds one entry per apply() — the line and the
+        # frames it covered — so a run is attributed to the statement of the same
+        # input whose span for that shader key overlaps it. A group emits per
+        # frame, so several statements carry the same line; the earliest wins,
+        # which is the one a person would point at.
+        def wroteIt(key: str, first: int, last: int) -> tuple[int, str]:
+            # Whoever covers the most of it. Consecutive frames are merged into
+            # one run, so a run can span two statements — `Circle().opacity(0)`
+            # writing frame 0 and `fadeIn()` writing the ten after it — and the
+            # one that owns two frames of twelve is not the one a person means.
+            best, call, widest, kinds = 0, "", 0, 99
+            for statement in Context.statements:
+                if statement["input"] != index:
+                    continue
+                span = statement["keys"].get(key)
+                if span is None:
+                    continue
+                overlap = min(span[1], last) - max(span[0], first) + 1
+                if overlap <= 0:
+                    continue
+                # Most of the run wins; between statements that cover it
+                # equally, the one that touched the FEWEST kinds of shader — a
+                # group re-emits position, rotation and scale on every pass, so
+                # `scaleTo` (position and scale) is a better answer for a Scale
+                # run than `rotateBy` (all three).
+                spread = len(statement["keys"])
+                if overlap > widest or (overlap == widest and spread < kinds):
+                    best, call, widest, kinds = statement["line"], statement["call"], overlap, spread
+            return best, call
+
+        effects = []
+        for key, spans in runs.items():
+            for span in spans:
+                line, call = wroteIt(key, span[0], span[1])
+                effects.append({
+                    "name": key,
+                    "start": span[0],
+                    "end": span[1],
+                    "line": line,
+                    # What the person wrote, when it is known: an editor that
+                    # says `scaleTo` is talking about their scene, one that says
+                    # `Scale` is talking about ours.
+                    "call": call,
+                })
+        # One row per STATEMENT, not per kind of shader.
+        #
+        # A single `scaleTo` on a group writes both position and scale, and two
+        # bars called `scaleTo` sitting on the same frames describe one thing
+        # twice. Runs from the same call on the same line become one row, and
+        # what they wrote is kept in `kinds`.
+        #
+        # The row is the SHORTEST of them, not their union. A group's `scaleTo`
+        # writes scale for its own second and a half, and position for as long
+        # as ANYTHING in the group is moving — the rigid recomputation that
+        # keeps the members' places consistent. The union says the call lasts as
+        # long as the group does, which is why shortening it left the bar where
+        # it was; the shortest run is the animation the call actually asked for.
+        folded: dict[tuple[int, str], dict] = {}
+        loose: list[dict] = []
+        for effect in effects:
+            key = (effect["line"], effect["call"])
+            if effect["line"] == 0 or not effect["call"]:
+                loose.append(effect)
+                continue
+            held = folded.get(key)
+            if held is None:
+                folded[key] = effect | {"kinds": [effect["name"]]}
+                continue
+            held["kinds"].append(effect["name"])
+            if effect["end"] - effect["start"] < held["end"] - held["start"]:
+                held["start"] = effect["start"]
+                held["end"] = effect["end"]
+
+        effects = loose + list(folded.values())
         effects.sort(key=lambda e: (e["start"], e["name"]))
 
         # ── When it is actually on screen ─────────────────────────────────