@runtypelabs/persona 3.16.0 → 3.17.0

package/src/types.ts

@@ -680,6 +680,167 @@ export type AgentWidgetReasoningDisplayFeature = {
   loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
 };
 
+/**
+ * Reveal animation applied to assistant message text while it is streaming.
+ *
+ * Built-in types always available:
+ * - `none` — text appears as tokens arrive (default).
+ * - `typewriter` — characters fade in with a blinking caret.
+ * - `pop-bubble` — the bubble scales in; text streams normally afterward.
+ * - `letter-rise` — per-char translateY + fade reveal.
+ * - `word-fade` — per-word blur + translateY fade-in.
+ *
+ * Subpath plugins (import from `@runtypelabs/persona/animations/*` to register):
+ * - `wipe`, `glyph-cycle`.
+ *
+ * Custom types are allowed — register a plugin with any string name and
+ * reference it by that name in `type`.
+ */
+export type AgentWidgetStreamAnimationBuiltinType =
+  | "none"
+  | "typewriter"
+  | "word-fade"
+  | "letter-rise"
+  | "glyph-cycle"
+  | "wipe"
+  | "pop-bubble";
+
+export type AgentWidgetStreamAnimationType =
+  | AgentWidgetStreamAnimationBuiltinType
+  | (string & {});
+
+/**
+ * Placeholder shown inside a streaming assistant bubble before the first token arrives.
+ * - `none` — use the default typing-dots indicator (existing behavior).
+ * - `skeleton` — shimmer bars, replaced by streaming content once it starts.
+ */
+export type AgentWidgetStreamAnimationPlaceholder = "none" | "skeleton";
+
+/**
+ * How much of the accumulated streaming content to display while tokens are
+ * still arriving. Trimming to a boundary means in-progress words or lines
+ * stay hidden until they complete — useful for animations that benefit from
+ * unit-complete reveals (e.g. wipe, glyph-cycle).
+ * - `none` — show every character as it arrives (default).
+ * - `word` — trim to the last whitespace boundary.
+ * - `line` — trim to the last newline boundary.
+ */
+export type AgentWidgetStreamAnimationBuffer = "none" | "word" | "line";
+
+/**
+ * Context passed to plugin lifecycle hooks. Carries the live DOM references
+ * and resolved animation settings for the currently-streaming message.
+ */
+export type StreamAnimationContext = {
+  /** The `.persona-message-content` element owning the streamed text. */
+  container: HTMLElement;
+  /** The outer message bubble element. */
+  bubble: HTMLElement;
+  /** ID of the streaming message. */
+  messageId: string;
+  /** Read-only reference to the message being streamed. */
+  message: AgentWidgetMessage;
+  /** Effective `speed` from `streamAnimation.speed`. */
+  speed: number;
+  /** Effective `duration` from `streamAnimation.duration`. */
+  duration: number;
+};
+
+/**
+ * Pluggable stream animation. Third-party packages and inline registrations
+ * implement this interface to add custom reveal effects.
+ *
+ * Lifecycle:
+ * - When the widget mounts and detects a plugin (either passed via config or
+ *   auto-registered in the IIFE bundle), it injects `styles` once into the
+ *   widget's style host.
+ * - For each streaming assistant message whose `type` matches `name`, the
+ *   widget applies `containerClass` / `bubbleClass`, wraps text per `wrap`,
+ *   and — if `useCaret` is true — appends a blinking caret.
+ * - Hooks fire after the live DOM is morphed; plugins use stable element IDs
+ *   and `data-preserve-animation` to safely mutate per-char or per-word spans
+ *   without idiomorph clobbering in-flight work.
+ */
+export type StreamAnimationPlugin = {
+  /** Plugin identifier. Matches the `type` field in `streamAnimation`. */
+  name: string;
+  /** Class added to `.persona-message-content` while streaming. */
+  containerClass?: string;
+  /** Class added to the bubble element (e.g. a one-shot scale animation). */
+  bubbleClass?: string;
+  /** Wrap mode applied to text nodes during streaming. @default "none" */
+  wrap?: "none" | "char" | "word";
+  /**
+   * HTML tags whose descendant text is skipped during wrapping. Defaults to
+   * `["pre", "code", "a", "script", "style"]` — useful for keeping code
+   * blocks legible and link click-targets intact. Plugins that want to
+   * animate characters inside inline code (e.g. `glyph-cycle`) can narrow
+   * the list.
+   */
+  skipTags?: string[];
+  /** Append a blinking caret after the last rendered char/word. */
+  useCaret?: boolean;
+  /** CSS string injected into the widget style host on first activation. */
+  styles?: string;
+  /**
+   * Optional custom buffering strategy. Returns the portion of `content`
+   * that should be rendered during streaming. Use this for buffering
+   * schemes beyond the built-in `word` / `line` strategies.
+   */
+  bufferContent?: (content: string, message: AgentWidgetMessage) => string;
+  /**
+   * Fires once when the plugin is first activated inside a widget instance.
+   * Use this to set up MutationObservers or other long-lived listeners.
+   * Return an optional cleanup function that runs on widget destroy.
+   */
+  onAttach?: (root: HTMLElement | ShadowRoot) => (() => void) | void;
+  /** Fires after each render that reaches the live DOM. */
+  onAfterRender?: (ctx: StreamAnimationContext) => void;
+  /** Fires when a streamed message's `streaming` flag flips to false. */
+  onStreamComplete?: (ctx: StreamAnimationContext) => void;
+  /**
+   * Report whether the plugin still has in-flight animation work for a
+   * message. When `true`, the widget keeps rendering the message in its
+   * "streaming-animated" mode even after `message.streaming` flips false —
+   * preventing the final non-animated render from yanking the rug out from
+   * under unfinished per-char cycles or reveals.
+   */
+  isAnimating?: (message: AgentWidgetMessage) => boolean;
+};
+
+export type AgentWidgetStreamAnimationFeature = {
+  /** Reveal animation to apply while streaming. @default "none" */
+  type?: AgentWidgetStreamAnimationType;
+  /** Pre-first-token placeholder. @default "none" */
+  placeholder?: AgentWidgetStreamAnimationPlaceholder;
+  /**
+   * Per-unit animation duration (ms) for `typewriter`, `letter-rise`, `word-fade`,
+   * and per-unit plugin animations. Each arriving character/word animates from
+   * invisible to visible over this duration, independent of its position — the
+   * streaming cadence itself provides the visible stagger.
+   * @default 120
+   */
+  speed?: number;
+  /**
+   * Total duration of container-level animations (`pop-bubble` and custom
+   * plugin animations), in milliseconds.
+   * @default 1800
+   */
+  duration?: number;
+  /**
+   * Trim the accumulated streaming content to a word or line boundary before
+   * rendering. Hides in-progress units until they complete.
+   * @default "none"
+   */
+  buffer?: AgentWidgetStreamAnimationBuffer;
+  /**
+   * Extra animation plugins available to this widget instance. Keys are
+   * plugin names; the matching plugin activates when `type` is set to that
+   * name. Built-in types (`typewriter`, `pop-bubble`) are always registered.
+   */
+  plugins?: Record<string, StreamAnimationPlugin>;
+};
+
 export type AgentWidgetFeatureFlags = {
   showReasoning?: boolean;
   showToolCalls?: boolean;
@@ -694,6 +855,8 @@ export type AgentWidgetFeatureFlags = {
   eventStream?: EventStreamConfig;
   /** Optional artifact sidebar (split pane / mobile drawer) */
   artifacts?: AgentWidgetArtifactsFeature;
+  /** Reveal animation for streaming assistant text. */
+  streamAnimation?: AgentWidgetStreamAnimationFeature;
 };
 
 export type SSEEventRecord = {
@@ -996,6 +1159,10 @@ export type AgentWidgetSendButtonConfig = {
   backgroundColor?: string;
   textColor?: string;
   size?: string;
+  /** Lucide icon name shown while a response is streaming. Clicking the button in this state aborts the stream. Default: "square". */
+  stopIconName?: string;
+  /** Tooltip text shown while streaming. Default: "Stop generating". */
+  stopTooltipText?: string;
 };
 
 /** Optional composer UI state for custom `renderComposer` implementations. */
@@ -2608,11 +2775,21 @@ export type AgentWidgetConfig = {
     welcomeSubtitle?: string;
     inputPlaceholder?: string;
     sendButtonLabel?: string;
+    /** Button label shown in text mode while a response is streaming. Default: "Stop". */
+    stopButtonLabel?: string;
     /**
      * When false, the welcome / intro card is not shown above the message list.
      * @default true
      */
     showWelcomeCard?: boolean;
+    /**
+     * Per-stop-reason copy for the inline notice rendered on assistant
+     * bubbles when the runtime reports a non-natural stop (e.g. the agent
+     * loop hit `max_tool_calls` and was cut off mid-loop). Each key is
+     * optional — keys you omit fall back to the built-in defaults. Set a
+     * key to an empty string to suppress the notice for that reason.
+     */
+    stopReasonNotice?: Partial<Record<StopReasonKind, string>>;
   };
   /**
    * Semantic design tokens (`palette`, `semantic`, `components`).
@@ -3121,6 +3298,28 @@ export type AgentWidgetApproval = {
 
 export type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval";
 
+/**
+ * Per-turn / per-step stop reason emitted by the runtime on
+ * `agent_turn_complete` and `step_complete` SSE events. The vocabulary is
+ * owned by the upstream Runtype API — do not extend without coordination.
+ *
+ * - `end_turn` — natural completion (no affordance needed)
+ * - `max_tool_calls` — agent loop tripped the configured tool-call ceiling
+ * - `length` — provider hit max output tokens
+ * - `content_filter` — provider content filter intervened
+ * - `error` — provider/runtime error (prefer existing error rendering)
+ * - `unknown` — explicitly reported but uninformative
+ *
+ * Absent (`undefined`) means "not reported" — distinct from `'unknown'`.
+ */
+export type StopReasonKind =
+  | 'end_turn'
+  | 'max_tool_calls'
+  | 'length'
+  | 'content_filter'
+  | 'error'
+  | 'unknown';
+
 /**
  * Represents a message in the chat conversation.
  *
@@ -3207,6 +3406,17 @@ export type AgentWidgetMessage = {
    * Contains execution context like iteration number and turn ID.
    */
   agentMetadata?: AgentMessageMetadata;
+  /**
+   * Per-turn stop reason reported by the runtime on `agent_turn_complete`
+   * (agent-loop path) or the last `step_complete` for a prompt step
+   * (dispatch / flow path). Absent when the API did not report a value.
+   *
+   * When set to a non-natural value (`max_tool_calls`, `length`,
+   * `content_filter`, `error`), the widget renders an inline notice on
+   * the assistant bubble. See `config.copy.stopReasonNotice` to override
+   * the default copy.
+   */
+  stopReason?: StopReasonKind;
 };
 
 // ============================================================================

package/src/ui.stop-button.test.ts

@@ -0,0 +1,165 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+const flush = async (times = 4) => {
+  for (let i = 0; i < times; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.resolve();
+  }
+};
+
+describe("createAgentExperience stop-streaming submit button", () => {
+  const originalFetch = global.fetch;
+  let capturedSignals: AbortSignal[] = [];
+
+  beforeEach(() => {
+    capturedSignals = [];
+    vi.stubGlobal("requestAnimationFrame", (cb: (time: number) => void) => {
+      cb(0);
+      return 1;
+    });
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    window.scrollTo = vi.fn();
+
+    // Fetch hangs until the caller aborts the signal — models an in-flight
+    // SSE stream so the widget stays in the "streaming" state.
+    global.fetch = vi.fn().mockImplementation((_url: string, options: any) => {
+      const signal = options.signal as AbortSignal;
+      capturedSignals.push(signal);
+      return new Promise((_resolve, reject) => {
+        signal.addEventListener("abort", () => {
+          const err = new Error("aborted");
+          err.name = "AbortError";
+          reject(err);
+        });
+      });
+    }) as any;
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  it("keeps the submit button enabled while streaming and clicking it cancels the stream", async () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+    });
+
+    const submit = mount.querySelector<HTMLButtonElement>(
+      "[data-persona-composer-submit]"
+    );
+    expect(submit).not.toBeNull();
+
+    const textarea = mount.querySelector<HTMLTextAreaElement>(
+      "[data-persona-composer-input]"
+    )!;
+    textarea.value = "Hello";
+    submit!.click();
+
+    await flush();
+
+    // Streaming is active: the button must stay enabled so it can be clicked
+    // again to stop the response.
+    expect(controller.getState().streaming).toBe(true);
+    expect(submit!.disabled).toBe(false);
+    expect(capturedSignals).toHaveLength(1);
+    expect(capturedSignals[0].aborted).toBe(false);
+
+    // Second click — acts as "stop generating".
+    submit!.click();
+
+    await flush();
+
+    expect(controller.getState().streaming).toBe(false);
+    expect(capturedSignals[0].aborted).toBe(true);
+    // No new request should have been fired by the stop click.
+    expect(capturedSignals).toHaveLength(1);
+    // Typed text is preserved so the user can resend after stopping.
+    expect(textarea.value).toBe("");
+    // (The textarea was cleared on the *first* submit, not by the stop click —
+    // that's fine because after cancel the user can keep typing.)
+
+    controller.destroy();
+  });
+
+  it("swaps to the stop icon while streaming and back to the send icon after cancel (icon mode)", async () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      sendButton: { useIcon: true, iconName: "arrow-up" },
+    });
+
+    const submit = mount.querySelector<HTMLButtonElement>(
+      "[data-persona-composer-submit]"
+    )!;
+    const textarea = mount.querySelector<HTMLTextAreaElement>(
+      "[data-persona-composer-input]"
+    )!;
+
+    // Initial state: send icon (aria-label tracks tooltip default).
+    expect(submit.getAttribute("aria-label")).toBe("Send message");
+
+    textarea.value = "Hi";
+    submit.click();
+    await flush();
+
+    expect(controller.getState().streaming).toBe(true);
+    expect(submit.getAttribute("aria-label")).toBe("Stop generating");
+
+    submit.click();
+    await flush();
+
+    expect(controller.getState().streaming).toBe(false);
+    expect(submit.getAttribute("aria-label")).toBe("Send message");
+
+    controller.destroy();
+  });
+
+  it("swaps the text label in text mode", async () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      sendButton: { useIcon: false },
+      copy: { sendButtonLabel: "Send", stopButtonLabel: "Stop" },
+    });
+
+    const submit = mount.querySelector<HTMLButtonElement>(
+      "[data-persona-composer-submit]"
+    )!;
+    const textarea = mount.querySelector<HTMLTextAreaElement>(
+      "[data-persona-composer-input]"
+    )!;
+
+    expect(submit.textContent).toBe("Send");
+
+    textarea.value = "Hi";
+    submit.click();
+    await flush();
+
+    expect(controller.getState().streaming).toBe(true);
+    expect(submit.textContent).toBe("Stop");
+
+    submit.click();
+    await flush();
+
+    expect(controller.getState().streaming).toBe(false);
+    expect(submit.textContent).toBe("Send");
+
+    controller.destroy();
+  });
+});

package/src/ui.ts

@@ -41,6 +41,11 @@ import {
   resolveFollowStateFromWheel
 } from "./utils/auto-follow";
 import { statusCopy, DEFAULT_OVERLAY_Z_INDEX, PORTALED_OVERLAY_Z_INDEX } from "./utils/constants";
+import {
+  detachAllPlugins,
+  ensurePluginActive,
+  resolveStreamAnimationPlugin,
+} from "./utils/stream-animation";
 import { syncOverlayHostStacking } from "./utils/overlay-host-stacking";
 import { acquireScrollLock } from "./utils/scroll-lock";
 import { isDockedMountMode, resolveDockConfig } from "./utils/dock";
@@ -701,6 +706,7 @@ export const createAgentExperience = (
     leftActions,
     rightActions
   } = panelElements;
+  let setSendButtonMode = panelElements.setSendButtonMode;
 
   // Use mutable references for mic button so we can update them dynamically
   let micButton: HTMLButtonElement | null = panelElements.micButton;
@@ -1671,6 +1677,16 @@ export const createAgentExperience = (
     const panelShadow = resolvePanelChrome(panelPartial?.shadow, defaultPanelShadow);
     const panelBorderRadius = resolvePanelChrome(panelPartial?.borderRadius, defaultPanelBorderRadius);
 
+    // Clearing body.style.cssText below wipes the inline `flex: 1 1 0%` /
+    // `min-height: 0` / `overflow-y: auto` that make the messages area a
+    // scroll container. Between the reset and the mode-specific reapply,
+    // the body's clientHeight == scrollHeight momentarily, so the browser
+    // clamps scrollTop to 0 — and a synchronous restore at the end of this
+    // function runs before layout has reflowed, so the write is also
+    // clamped. Defer the restore to the next frame, once the reapplied
+    // styles have produced a scrollable container again.
+    const prevBodyScrollTop = body.scrollTop;
+
     // Reset all inline styles first to handle mode toggling
     // This ensures styles don't persist when switching between modes
     mount.style.cssText = '';
@@ -1679,6 +1695,18 @@ export const createAgentExperience = (
     container.style.cssText = '';
     body.style.cssText = '';
     footer.style.cssText = '';
+
+    const restoreBodyScrollTop = (): void => {
+      if (prevBodyScrollTop <= 0) return;
+      const ownerWindow = body.ownerDocument.defaultView ?? window;
+      ownerWindow.requestAnimationFrame(() => {
+        if (body.scrollTop === prevBodyScrollTop) return;
+        // If scrollHeight collapsed (content actually shrank), don't fight it
+        const maxScrollTop = body.scrollHeight - body.clientHeight;
+        if (maxScrollTop <= 0) return;
+        body.scrollTop = Math.min(prevBodyScrollTop, maxScrollTop);
+      });
+    };
     
     // Mobile fullscreen: fill entire viewport with no radius/shadow/margins
     if (shouldGoFullscreen) {
@@ -1742,6 +1770,7 @@ export const createAgentExperience = (
       footer.style.flexShrink = '0';
 
       wasMobileFullscreen = true;
+      restoreBodyScrollTop();
       return; // Skip remaining mode logic
     }
 
@@ -1926,6 +1955,8 @@ export const createAgentExperience = (
         : '';
       wrapper.style.cssText += maxHeightStyles + paddingStyles + zIndexStyles;
     }
+
+    restoreBodyScrollTop();
   };
   applyFullHeightStyles();
   // Apply theme variables after applyFullHeightStyles since it resets mount.style.cssText
@@ -2003,6 +2034,23 @@ export const createAgentExperience = (
     }
   });
 
+  // Activate the stream-animation plugin for this widget instance. Plugins
+  // with `styles` inject their CSS into the widget root once; plugins with
+  // `onAttach` (e.g., glyph-cycle's MutationObserver for real glyph tick
+  // loops) can register long-lived DOM listeners here. Detach callbacks are
+  // deferred to widget destroy.
+  const streamAnimationConfig = config.features?.streamAnimation;
+  if (streamAnimationConfig?.type && streamAnimationConfig.type !== "none") {
+    const plugin = resolveStreamAnimationPlugin(
+      streamAnimationConfig.type,
+      streamAnimationConfig.plugins
+    );
+    if (plugin) {
+      ensurePluginActive(plugin, mount);
+      destroyCallbacks.push(() => detachAllPlugins(mount));
+    }
+  }
+
   const suggestionsManager = createSuggestions(suggestions);
   let closeHandler: (() => void) | null = null;
   let session: AgentWidgetSession;
@@ -2921,9 +2969,10 @@ export const createAgentExperience = (
   };
 
   const setComposerDisabled = (disabled: boolean) => {
-    // Keep textarea always enabled so users can type while streaming
-    // Only disable submit controls to prevent sending during streaming
-    sendButton.disabled = disabled;
+    // The send button stays enabled while streaming — it doubles as a stop
+    // button. Ancillary controls (mic, suggestions, opt-in targets) still
+    // disable so the user can't race a send against an in-flight stream.
+    setSendButtonMode(disabled ? "stop" : "send");
     if (micButton) {
       micButton.disabled = disabled;
     }
@@ -2974,9 +3023,10 @@ export const createAgentExperience = (
       }
     }
 
-    // Only update send button text if NOT using icon mode
+    // Only update send button text if NOT using icon mode. Skip while
+    // streaming so we don't stomp on the "Stop" label.
     const useIcon = config.sendButton?.useIcon ?? false;
-    if (!useIcon) {
+    if (!useIcon && !session?.isStreaming()) {
       sendButton.textContent = config.copy?.sendButtonLabel ?? "Send";
     }
 
@@ -3178,6 +3228,15 @@ export const createAgentExperience = (
 
   const handleSubmit = (event: Event) => {
     event.preventDefault();
+
+    // While a response is streaming, the submit button acts as a stop button.
+    // Abort the in-flight stream and leave textarea contents / attachments
+    // intact so the user can edit and resend without retyping.
+    if (session.isStreaming()) {
+      session.cancel();
+      return;
+    }
+
     const value = textarea.value.trim();
     const hasAttachments = attachmentManager?.hasAttachments() ?? false;
 
@@ -3914,16 +3973,26 @@ export const createAgentExperience = (
   }
 
   lastScrollTop = body.scrollTop;
+  let lastScrollHeight = body.scrollHeight;
 
   const handleScroll = () => {
     const scrollTop = body.scrollTop;
+    // When content mutates (e.g. stream-animation plugins re-rendering text),
+    // scrollHeight can shrink and force the browser to clamp scrollTop downward.
+    // That emits a scroll event with a negative delta that would otherwise be
+    // misread as the user scrolling up, pausing auto-follow and flashing the
+    // scroll-to-bottom button. Treat those as non-user events.
+    const currentScrollHeight = body.scrollHeight;
+    const scrollHeightShrank = currentScrollHeight < lastScrollHeight;
+    lastScrollHeight = currentScrollHeight;
+
     const { action, nextLastScrollTop } = resolveFollowStateFromScroll({
       following: autoFollow.isFollowing(),
       currentScrollTop: scrollTop,
       lastScrollTop,
       nearBottom: isElementNearBottom(body, BOTTOM_THRESHOLD),
       userScrollThreshold: USER_SCROLL_THRESHOLD,
-      isAutoScrolling: isAutoScrolling || hasPendingAutoScroll,
+      isAutoScrolling: isAutoScrolling || hasPendingAutoScroll || scrollHeightShrank,
       pauseOnUpwardScroll: true,
       pauseWhenAwayFromBottom: false,
       resumeRequiresDownwardScroll: true

package/src/utils/message-fingerprint.ts

@@ -24,6 +24,7 @@ export type FingerprintableMessage = {
   };
   reasoning?: { chunks?: string[]; status?: string; [key: string]: unknown };
   contentParts?: unknown[];
+  stopReason?: string;
 };
 
 export type MessageCacheEntry = {
@@ -63,6 +64,7 @@ export function computeMessageFingerprint(
         : 0,
     message.reasoning?.chunks?.length ?? 0,
     message.contentParts?.length ?? 0,
+    message.stopReason ?? "",
     configVersion,
   ].join("\x00");
 }

package/src/utils/morph.ts

@@ -30,6 +30,13 @@ export const morphMessages = (
           if (oldNode.classList.contains("persona-animate-typing")) {
             return false;
           }
+          // Plugins actively mutating a node (e.g. glyph-cycle's tick loop)
+          // opt out of morph entirely via this attribute. Unlike
+          // `data-preserve-animation`, this is honored regardless of whether
+          // the new DOM carries the attribute — it's a runtime-only marker.
+          if (oldNode.hasAttribute("data-preserve-runtime")) {
+            return false;
+          }
           if (oldNode.hasAttribute("data-preserve-animation")) {
             // Allow morph when the new node drops the attribute (e.g. tool completed)
             if (newNode instanceof HTMLElement && !newNode.hasAttribute("data-preserve-animation")) {