Adding Incidents

addIncident

Incidents can be added to both Groups and Clips. Both provide the same addIncident method.

Syntax

const result = clip.addIncident(incident, millisecond, options);

Arguments

Argument	Type	Description
incident	Incident	The Incident to add (CSSEffect, Combo, Group, plugin Effect, or another Clip used as CAsI)
millisecond	number	The position on the timeline (in ms) where the Incident should start
options	object	(optional) Additional options — see below

Options

Key	Type	Default	Description
skipFlash	boolean	false	When true, skips the full state replay after addition. Only safe for Incidents placed ahead of the current playhead. See skipFlash for details

Returns

An object with the following keys:

Key	Type	Description
result	boolean	true if the addition was valid and executed, false otherwise
errors	array	An array of error descriptions if result is false

Example

import { HTMLClip, CSSEffect, Combo } from "@donkeyclip/motorcortex";

const clip = new HTMLClip({
  host: document.getElementById("app"),
  html: `<div class="box"></div>`,
  css: `.box { width: 100px; height: 100px; background: #f72585; }`,
  containerParams: { width: "400px", height: "400px" },
});

// Add a CSSEffect at millisecond 0
const result = clip.addIncident(
  new CSSEffect({ animatedAttrs: { left: "300px" } }, { selector: ".box", duration: 2000, easing: "easeInOutQuad" }),
  0,
);

if (!result.result) {
  console.error("Failed to add incident:", result.errors);
}

Validation

MotorCortex validates every addition before applying it. An addition will fail (result: false) if:

• The Incident's time range overlaps with another Incident targeting the same element and the same attribute on the same channel
• The selector doesn't match any elements in the Clip's context (for Effects)
• The Incident or its properties are invalid

When an addition fails the Clip's state remains unchanged — nothing is applied.