Seek-sicheres Bewegen (Seek-safe motion)
HyperFrames spielt die Timeline nicht ab. Es sucht sie (seekt): Für jedes Bild setzt der Renderer die Timeline auf den Zeitpunkt des Frames und erfasst die Seite. Mit HyperFrames 0.8.x geschieht dies mit drei parallelen Workern, die jeweils jedes dritte Bild übernehmen, und jeder Suchschritt geht 1 ms zurück und dann vorwärts, um sich zu stabilisieren. Jeder Frame muss also eine reine Funktion seiner Zeit sein. Alles, was von vorherigen Rendern, der Uhr oder dem Zufall abhängt, wird in jedem Worker anders gerendert, und das Ergebnis ist ein Element, das in jedem dritten Frame fehlt.
Dieser Fehler ist in der Studio-Vorschau (die in der Reihenfolge abspielt) und in einzelnen Schnappschüssen unsichtbar. In der Produktion, aus der diese Skills stammen, war es der einzige Fehler, der zum Reviewer gelangte: der Eröffnungstitel „stotterte und flackerte“ während seiner ersten sieben Sekunden.
Zuerst linten
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" <video_dir>/video
Es liest index.html, src/*.tpl und die *.js daneben (nur Inline-Skripte), gibt file:line: severity RULE: why sowie den Fix aus und beendet sich mit Exit-Code 1 bei jedem Fehler (--strict lässt auch Warnungen fehlschlagen, --json für Tools). Führe es nach jeder Bearbeitung der Timeline und vor jedem Render aus. Es ist statisch: Es kann keine zur Laufzeit berechneten Variablen sehen (zählt sie als „nicht prüfbar“) oder zwei Tweens, die sich zeitlich überlappen. Diese bleiben bei dir, mit der Reproduktion unten. qa.py (render-qa) führt es ebenfalls aus und meldet einen Fehler im Report.
Die Regeln und warum es sie gibt
- Jeder Schlüssel in einem
fromTo-fromVars erscheint auch in dessen toVars (SS001, Fehler). Wenn der Frame eines Workers genau auf den Start eines Tweens fällt, macht der 1-ms-Schritt zurück den Tween rückgängig, und ein Schlüssel, der nur in fromVars existiert, wird nie wieder gesetzt. Der Titel-Tween warfromTo(sel, {yPercent: 110, opacity: 1}, {yPercent: 0}):opacity: 1existierte nur in fromVars, also behielt ein Worker den Titel für den Rest des Tweens bei deckkraft 0. Schreibe{yPercent: 110, opacity: 1}zu{yPercent: 0, opacity: 1}, oder eintl.set()gefolgt von einemtl.to(). Gleiches gilt fürstartAtinnerhalb einesto()(SS002). immediateRender: falsebei jedemfromTonach Zeit 0 (SS003, Warnung). Andernfalls schreibt der Tween seine Startwerte beim Erstellen der Timeline und überschreibt, was frühere Tweens gesetzt haben; ein Seek in die Mitte der Timeline beginnt mit dem falschen Zustand.- Bevorzuge
fromTogegenüberfrom(SS004, Warnung). Einfrom()endet auf dem, was das Element zur Bauzeit hatte; sobald frühere Tweens das Element berühren, sind sich die Worker uneinig. displayodervisibilityniemals animieren (SS005, Fehler). Sie können nicht interpoliert werden; sie springen an einem willkürlichen Punkt des Tweens. Ändere sie mit einem nulldauerndentl.set()zu einer expliziten Zeit und blende mitopacityoderautoAlpha.- Keine Uhr, kein Zufall, keine Timer (SS006, Fehler): kein
Date,performance.now(),Math.random(),setTimeout,setIntervaloderrequestAnimationFramefür sichtbare Elemente. Ein Tippzittern oder eine Wellenform verwendet einen gesäten Generator; ein auf dem Bildschirm angezeigter Anruftimer wird austl.time()innerhalb desonUpdateder Timeline berechnet. - Eine pausierte Timeline, registriert, nie abgespielt (SS007, SS011, SS012). Erstelle sie mit
gsap.timeline({ paused: true }), baue sie vollständig auf (innerhalb vondocument.fonts.readywenn Positionen von Textmetriken abhängen) und weise erst dannwindow.__timelines["<composition id>"] = tlzu. Das Registrieren einer leeren Timeline vor Bauende rendert ein leeres Video;tl.play()bekämpft die Seeks des Renderers. - Scrolls werden mit
fromTomit explizitem Start und Ende erstellt, sodass jeder Worker den gleichen Offset berechnet, begrenzt auf den tatsächlichen Inhalt, damit keine Linie oder kein Icon-Stopp an einer Kante abschneidet. - Niemals zwei Tweens auf derselben Eigenschaft desselben Elements gleichzeitig. Ein Cursor-Reset, der innerhalb der nächsten Bewegung lag, hinterließ den Zeiger nach einem Seek an der falschen Stelle. Nicht gelintet: Prüfe die Zeittabelle des Builds.
- Transformiere, nicht Layout (SS009, Warnung):
x,y,scale,clip-pathstattleft,top,width,margin. Layout-Tweens führen ein Reflow pro Frame durch undhyperframes checkmarkiert sie alsgsap_non_transform_motion. Eine kurze Breitenänderung an einem echten Produkt-Steuerelement (z. B. eine aufgeklappte Seitenleiste) kann akzeptiert werden, wenn sie das Produkt reproduziert. - Niemals ein
.clip-Element anfassen (SS010, Fehler). HyperFrames kontrolliert die Sichtbarkeit eines Clips überdata-startunddata-duration; animiere stattdessen einen Wrapper darin. - Endliche Wiederholungen (SS008, Warnung).
repeat: -1ist nur unter einer endlichen Root-data-durationerlaubt; berechne eine Anzahl mitMath.max(0, Math.floor(span / period) - 1). - Setze jeden Startzustand explizit bei Zeit 0. Ein Helfer, der
gsap.set(sel, vars)ausführt, sollte auchtl.set(sel, vars, 0)machen, damit ein Seek zurück auf 0 den ersten Frame wiederherstellt, anstatt den letzten Zustand zu behalten, den ein Worker gerendert hat.
Reproduziere einen vermuteten Fehler vor dem Rendern
Der Linter findet Muster; ein Schnappschuss beweist Pixel. Für einen verdächtigen Tween, der bei t0 beginnt:
npx --yes hyperframes@<pinned> snapshot . --at <t0 + 0.3> --no-end --describe false -o a
npx --yes hyperframes@<pinned> snapshot . --at <t0>,<t0 + 0.3> --no-end --describe false -o b
Der Frame bei t0 + 0.3 muss in a und b identisch sein. Wenn er sich unterscheidet, hat das Suchen durch den Tween-Start den Zustand geändert. Um einen Worker genau zu reproduzieren, mache Schnappschüsse der Frames 0, 3, 6, ... in dieser Reihenfolge bis kurz nach dem Tween. Halbiere den Zeitbereich, bis nur ein Tween übrig ist. Nach dem Rendern meldet scan_render.py (render-qa) denselben Fehler als WORKER PATTERN-Lauf: Ausreißer-Frames, die alle einen Frame-Index modulo 3 gemeinsam haben.
Referenzen
references/patterns.md: Vorher-Nachher-Code für jede Regel, die Hilfsfunktionen, die eine Vorlage sicher halten (lineIn,init, Tippen, Scrollen, Cursorklicks), und was der Linter sehen kann und was nicht. Lies es, wenn du einen neuen Helfer schreibst oder einen Lint-Fund behebst.