Function createStateTimeline

packages/core/src/debug/stateTimeline.ts:84–155

(maxChanges: number = DEFAULT_MAX_CHANGES)

 * @param maxChanges - Maximum number of changes to retain (default: 10000)
 */
export function createStateTimeline(maxChanges: number = DEFAULT_MAX_CHANGES): StateTimeline {
  const changes: StateChange[] = [];
  let head = 0;

  const cap = normalizeMaxChanges(maxChanges);

  function recordChange(
    frameId: bigint,
    timestamp: number,
    field: string,
    before: unknown,
    after: unknown,
  ): void {
    const change: StateChange = {
      frameId,
      timestamp,
      field,
      before,
      after,
    };

    changes.push(change);

    // Evict oldest changes if over capacity
    while (changes.length - head > cap) {
      head++;
    }

    // Avoid unbounded growth from a moving head index.
    if (head > 0 && head * 2 >= changes.length) {
      changes.splice(0, head);
      head = 0;
    }
  }

  function getChanges(since?: bigint): readonly StateChange[] {
    if (since === undefined) {
      return changes.slice(head);
    }

    const result: StateChange[] = [];
    for (let i = head; i < changes.length; i++) {
      const c = changes[i];
      if (c !== undefined && c.frameId > since) result.push(c);
    }
    return result;
  }

  function getFrameChanges(frameId: bigint): readonly StateChange[] {
    const result: StateChange[] = [];
    for (let i = head; i < changes.length; i++) {
      const c = changes[i];
      if (c !== undefined && c.frameId === frameId) result.push(c);
    }
    return result;
  }

  function clear(): void {