@hyperframes/studio 0.7.86 → 0.7.87

package/src/player/lib/timelineClipIndex.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineElementIdentity } from "./timelineElementHelpers";
+import { createTimelineClipIndex, queryTimelineClipIndex } from "./timelineClipIndex";
+
+function clip(
+  id: string,
+  start: number,
+  duration: number,
+  track = 1,
+  hidden = false,
+): TimelineElement {
+  return { id, tag: "div", start, duration, track, hidden };
+}
+
+function ids(elements: readonly TimelineElement[]): string[] {
+  return elements.map(getTimelineElementIdentity);
+}
+
+function createDeterministicRandom(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (Math.imul(state, 1_664_525) + 1_013_904_223) >>> 0;
+    return state / 0x1_0000_0000;
+  };
+}
+
+function linearOracle(
+  elements: readonly TimelineElement[],
+  range: { start: number; end: number },
+  pinned: ReadonlySet<string>,
+): readonly TimelineElement[] {
+  return elements.filter((element) => {
+    if (!Number.isFinite(element.start) || !Number.isFinite(element.duration)) return false;
+    if (pinned.has(getTimelineElementIdentity(element))) return true;
+    if (range.end <= range.start) return false;
+    const end = element.start + Math.max(0, element.duration);
+    if (end <= element.start) return element.start >= range.start && element.start < range.end;
+    return element.start < range.end && end > range.start;
+  });
+}
+
+describe("timelineClipIndex", () => {
+  it("finds a long predecessor spanning the window", () => {
+    const index = createTimelineClipIndex([[1, [clip("long", 0, 100), clip("late", 80, 1)]]]);
+    expect(ids(queryTimelineClipIndex(index, 1, { start: 50, end: 51 }))).toEqual(["long"]);
+  });
+
+  it("prunes 50k ended clips around one long interval in a late window", () => {
+    const elements = [
+      clip("long", 0, 50_000),
+      ...Array.from({ length: 49_999 }, (_, index) => clip(`short-${index}`, index, 0.25)),
+    ];
+    const index = createTimelineClipIndex([[1, elements]]);
+    expect(ids(queryTimelineClipIndex(index, 1, { start: 49_999, end: 49_999.5 }))).toEqual([
+      "long",
+    ]);
+  });
+
+  it("queries a shifted multi-drag window on a 50k-clip row without a row scan", () => {
+    const elements = Array.from({ length: 50_000 }, (_, index) =>
+      clip(`clip-${index}`, index, 0.25),
+    );
+    const index = createTimelineClipIndex([[1, elements]]);
+    const selected = new Set(["clip-10", "clip-49"]);
+
+    expect(
+      ids(
+        queryTimelineClipIndex(index, 1, { start: 60_000, end: 60_001 }, new Set(), [
+          { range: { start: 10, end: 11 }, identities: selected },
+        ]),
+      ),
+    ).toEqual(["clip-10"]);
+  });
+
+  it("uses half-open render boundaries and retains zero-duration points", () => {
+    const index = createTimelineClipIndex([
+      [
+        1,
+        [
+          clip("left", 0, 2),
+          clip("right", 2, 2),
+          clip("point", 3, 0),
+          clip("negative", 3.5, -2),
+          clip("micro", 4, 1e-9),
+        ],
+      ],
+    ]);
+    expect(ids(queryTimelineClipIndex(index, 1, { start: 2, end: 4 }))).toEqual([
+      "right",
+      "point",
+      "negative",
+    ]);
+    expect(ids(queryTimelineClipIndex(index, 1, { start: 4, end: 5 }))).toEqual(["micro"]);
+  });
+
+  it("preserves projection order after overlap and pin union", () => {
+    const index = createTimelineClipIndex([
+      [1, [clip("pinned", 10, 1), clip("visible-b", 2, 1), clip("visible-a", 1, 3)]],
+    ]);
+    expect(
+      ids(queryTimelineClipIndex(index, 1, { start: 1.5, end: 2.5 }, new Set(["pinned"]))),
+    ).toEqual(["pinned", "visible-b", "visible-a"]);
+  });
+
+  it("keeps duplicate identities deterministic and ignores stale pins", () => {
+    const index = createTimelineClipIndex([
+      [1, [clip("duplicate", 10, 1), clip("duplicate", 20, 1), clip("hidden", 30, 1, 1, true)]],
+      [2, [clip("duplicate", 40, 1, 2)]],
+    ]);
+    expect(
+      ids(queryTimelineClipIndex(index, 1, { start: 0, end: 1 }, new Set(["duplicate", "stale"]))),
+    ).toEqual(["duplicate", "duplicate"]);
+    expect(
+      ids(queryTimelineClipIndex(index, 2, { start: 0, end: 1 }, new Set(["duplicate"]))),
+    ).toEqual(["duplicate"]);
+  });
+
+  it("keeps an immutable interval snapshot when the source projection array changes", () => {
+    const source = [clip("first", 0, 2), clip("second", 5, 2)];
+    const index = createTimelineClipIndex([[1, source]]);
+    source.splice(0, source.length, clip("replacement", 0, 20));
+    expect(ids(queryTimelineClipIndex(index, 1, { start: 0, end: 1 }))).toEqual(["first"]);
+  });
+
+  it("excludes clips with non-finite timing", () => {
+    const index = createTimelineClipIndex([
+      [1, [clip("bad-start", Number.NaN, 1), clip("bad-duration", 0, Number.POSITIVE_INFINITY)]],
+    ]);
+    expect(ids(queryTimelineClipIndex(index, 1, { start: 0, end: 1 }))).toEqual([]);
+  });
+
+  it("indexes synthetic fractional display rows independently", () => {
+    const index = createTimelineClipIndex([
+      [1, [clip("host", 0, 1)]],
+      [1.5, [clip("child", 10, 1, 1.5)]],
+    ]);
+    expect(ids(queryTimelineClipIndex(index, 1.5, { start: 10, end: 11 }))).toEqual(["child"]);
+    expect(ids(queryTimelineClipIndex(index, 1, { start: 10, end: 11 }))).toEqual([]);
+  });
+
+  it("matches a linear oracle across deterministic randomized windows and pins", () => {
+    const random = createDeterministicRandom(0x2698);
+    for (let scenario = 0; scenario < 50; scenario += 1) {
+      const elements = Array.from({ length: 60 }, (_, index) => {
+        const element = clip(
+          `clip-${scenario}-${index}`,
+          Math.floor(random() * 120) - 10,
+          random() < 0.15 ? -Math.floor(random() * 5) : Math.floor(random() * 30),
+        );
+        if (index % 4 === 0) element.key = `index.html#${element.id}`;
+        return element;
+      });
+      const index = createTimelineClipIndex([[1, elements]]);
+      for (let query = 0; query < 12; query += 1) {
+        const start = Math.floor(random() * 120) - 10;
+        const range = { start, end: start + Math.floor(random() * 35) };
+        const pinned = new Set(
+          elements
+            .filter(() => random() < 0.05)
+            .map((element) => getTimelineElementIdentity(element)),
+        );
+        expect(queryTimelineClipIndex(index, 1, range, pinned)).toEqual(
+          linearOracle(elements, range, pinned),
+        );
+      }
+    }
+  });
+});

package/src/player/lib/timelineClipIndex.ts

@@ -0,0 +1,208 @@
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineElementIdentity } from "./timelineElementHelpers";
+
+export interface TimelineTimeRange {
+  readonly start: number;
+  readonly end: number;
+}
+
+export interface TimelineClipQueryWindow {
+  readonly range: TimelineTimeRange;
+  readonly identities: ReadonlySet<string>;
+}
+
+interface TimelineClipInterval {
+  readonly element: TimelineElement;
+  readonly identity: string;
+  readonly ordinal: number;
+  readonly start: number;
+  readonly end: number;
+}
+
+interface TimelineClipRowIndex {
+  readonly byStart: readonly TimelineClipInterval[];
+  readonly treeLeafCount: number;
+  readonly maxPositiveEndTree: readonly number[];
+  readonly maxPointStartTree: readonly number[];
+  readonly byIdentity: ReadonlyMap<string, readonly TimelineClipInterval[]>;
+}
+
+export interface TimelineClipIndex {
+  readonly rows: ReadonlyMap<number, TimelineClipRowIndex>;
+}
+
+function clipInterval(element: TimelineElement, ordinal: number): TimelineClipInterval | null {
+  if (!Number.isFinite(element.start) || !Number.isFinite(element.duration)) return null;
+  const duration = Math.max(0, element.duration);
+  return Object.freeze({
+    element,
+    identity: getTimelineElementIdentity(element),
+    ordinal,
+    start: element.start,
+    end: element.start + duration,
+  });
+}
+
+function timelineClipTreeLeafCount(intervalCount: number): number {
+  let leafCount = 1;
+  while (leafCount < intervalCount) leafCount *= 2;
+  return leafCount;
+}
+
+function createTimelineClipMaxTrees(intervals: readonly TimelineClipInterval[]) {
+  const treeLeafCount = timelineClipTreeLeafCount(intervals.length);
+  const maxPositiveEndTree = Array<number>(treeLeafCount * 2).fill(Number.NEGATIVE_INFINITY);
+  const maxPointStartTree = Array<number>(treeLeafCount * 2).fill(Number.NEGATIVE_INFINITY);
+  for (let index = 0; index < intervals.length; index += 1) {
+    const interval = intervals[index];
+    if (!interval) continue;
+    const leaf = treeLeafCount + index;
+    if (interval.end > interval.start) maxPositiveEndTree[leaf] = interval.end;
+    else maxPointStartTree[leaf] = interval.start;
+  }
+  for (let node = treeLeafCount - 1; node > 0; node -= 1) {
+    maxPositiveEndTree[node] = Math.max(
+      maxPositiveEndTree[node * 2] ?? Number.NEGATIVE_INFINITY,
+      maxPositiveEndTree[node * 2 + 1] ?? Number.NEGATIVE_INFINITY,
+    );
+    maxPointStartTree[node] = Math.max(
+      maxPointStartTree[node * 2] ?? Number.NEGATIVE_INFINITY,
+      maxPointStartTree[node * 2 + 1] ?? Number.NEGATIVE_INFINITY,
+    );
+  }
+  return {
+    treeLeafCount,
+    maxPositiveEndTree: Object.freeze(maxPositiveEndTree),
+    maxPointStartTree: Object.freeze(maxPointStartTree),
+  };
+}
+
+/**
+ * Build an immutable snapshot for one exact display-track projection.
+ * Rebuild only when that projection's array identity changes. Construction is
+ * O(n log n) overall because each row is sorted once.
+ */
+export function createTimelineClipIndex(
+  tracks: readonly (readonly [number, readonly TimelineElement[]])[],
+): TimelineClipIndex {
+  const rows = new Map<number, TimelineClipRowIndex>();
+  for (const [rowKey, elements] of tracks) {
+    const intervals = elements
+      .map(clipInterval)
+      .filter((interval): interval is TimelineClipInterval => interval !== null);
+    const byStart = Object.freeze(
+      [...intervals].sort(
+        (left, right) => left.start - right.start || left.ordinal - right.ordinal,
+      ),
+    );
+    const maxTrees = createTimelineClipMaxTrees(byStart);
+    const mutableByIdentity = new Map<string, TimelineClipInterval[]>();
+    for (const interval of intervals) {
+      const matches = mutableByIdentity.get(interval.identity) ?? [];
+      matches.push(interval);
+      mutableByIdentity.set(interval.identity, matches);
+    }
+    const byIdentity = new Map(
+      [...mutableByIdentity].map(([identity, matches]) => [identity, Object.freeze(matches)]),
+    );
+    rows.set(rowKey, Object.freeze({ byStart, ...maxTrees, byIdentity }));
+  }
+  return Object.freeze({ rows });
+}
+
+function upperBoundStart(intervals: readonly TimelineClipInterval[], end: number): number {
+  let low = 0;
+  let high = intervals.length;
+  while (low < high) {
+    const mid = Math.floor((low + high) / 2);
+    if ((intervals[mid]?.start ?? Number.POSITIVE_INFINITY) < end) low = mid + 1;
+    else high = mid;
+  }
+  return low;
+}
+
+function overlaps(interval: TimelineClipInterval, range: TimelineTimeRange): boolean {
+  if (interval.end <= interval.start)
+    return interval.start >= range.start && interval.start < range.end;
+  return interval.start < range.end && interval.end > range.start;
+}
+
+function collectTimelineClipOverlaps(
+  row: TimelineClipRowIndex,
+  candidateCount: number,
+  range: TimelineTimeRange,
+  selected: Set<TimelineClipInterval>,
+  identities?: ReadonlySet<string>,
+): void {
+  const visit = (node: number, left: number, right: number) => {
+    if (
+      left >= candidateCount ||
+      ((row.maxPositiveEndTree[node] ?? Number.NEGATIVE_INFINITY) <= range.start &&
+        (row.maxPointStartTree[node] ?? Number.NEGATIVE_INFINITY) < range.start)
+    ) {
+      return;
+    }
+    if (right - left === 1) {
+      const interval = row.byStart[left];
+      if (interval) selectTimelineClipOverlap(interval, range, selected, identities);
+      return;
+    }
+    const middle = Math.floor((left + right) / 2);
+    visit(node * 2, left, middle);
+    visit(node * 2 + 1, middle, right);
+  };
+  visit(1, 0, row.treeLeafCount);
+}
+
+function selectTimelineClipOverlap(
+  interval: TimelineClipInterval,
+  range: TimelineTimeRange,
+  selected: Set<TimelineClipInterval>,
+  identities: ReadonlySet<string> | undefined,
+): void {
+  if (!overlaps(interval, range)) return;
+  if (identities !== undefined && !identities.has(interval.identity)) return;
+  selected.add(interval);
+}
+
+/**
+ * Query one display row. The overlap set and explicit actor pins are returned
+ * in the row's original projection order, so windowing never changes z/DOM order.
+ * The start lookup is O(log n). Balanced max trees prune both children whose
+ * positive intervals and point clips cannot reach the window. The overlap walk
+ * is O((k + 1) log n) for k candidates across the primary and actor windows;
+ * pin lookup is O(p), followed by the projection-order sort of the unique
+ * result set.
+ */
+export function queryTimelineClipIndex(
+  index: TimelineClipIndex,
+  rowKey: number,
+  range: TimelineTimeRange,
+  pinnedIdentities: ReadonlySet<string> = new Set(),
+  actorWindows: readonly TimelineClipQueryWindow[] = [],
+): readonly TimelineElement[] {
+  const row = index.rows.get(rowKey);
+  if (!row) return Object.freeze([]);
+  const selected = new Set<TimelineClipInterval>();
+  if (range.end > range.start) {
+    collectTimelineClipOverlaps(row, upperBoundStart(row.byStart, range.end), range, selected);
+  }
+  for (const actorWindow of actorWindows) {
+    if (actorWindow.range.end <= actorWindow.range.start) continue;
+    collectTimelineClipOverlaps(
+      row,
+      upperBoundStart(row.byStart, actorWindow.range.end),
+      actorWindow.range,
+      selected,
+      actorWindow.identities,
+    );
+  }
+  for (const identity of pinnedIdentities) {
+    for (const interval of row.byIdentity.get(identity) ?? []) selected.add(interval);
+  }
+  return Object.freeze(
+    [...selected]
+      .sort((left, right) => left.ordinal - right.ordinal)
+      .map((interval) => interval.element),
+  );
+}

package/src/player/lib/timelineElementIndexes.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineElementIndexes } from "./timelineElementIndexes";
+
+describe("getTimelineElementIndexes", () => {
+  const elements: TimelineElement[] = [
+    { id: "hero", tag: "img", src: "hero.png", start: 0, duration: 2, track: 0 },
+    {
+      id: "bgm",
+      tag: "audio",
+      src: "music.wav",
+      start: 0,
+      duration: 10,
+      track: 3,
+      timelineRole: "music",
+    },
+  ];
+
+  it("indexes media and music identities", () => {
+    const indexes = getTimelineElementIndexes(elements);
+    expect(indexes.byKey.get("hero")).toBe(elements[0]);
+    expect(indexes.musicElement).toBe(elements[1]);
+    expect(indexes.mediaElements).toEqual(elements);
+    expect(indexes.audioTracks).toEqual(new Set([3]));
+  });
+
+  it("reuses one index for the same immutable array snapshot", () => {
+    expect(getTimelineElementIndexes(elements)).toBe(getTimelineElementIndexes(elements));
+    expect(getTimelineElementIndexes([...elements])).not.toBe(getTimelineElementIndexes(elements));
+  });
+});

package/src/player/lib/timelineElementIndexes.ts

@@ -0,0 +1,44 @@
+import { isAudioTimelineElement, isMusicTrack } from "../../utils/timelineInspector";
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineElementIdentity } from "./timelineElementHelpers";
+
+export interface TimelineElementIndexes {
+  readonly byKey: ReadonlyMap<string, TimelineElement>;
+  readonly musicElement: TimelineElement | null;
+  readonly mediaElements: readonly TimelineElement[];
+  readonly audioTracks: ReadonlySet<number>;
+}
+
+const indexCache = new WeakMap<readonly TimelineElement[], TimelineElementIndexes>();
+
+/**
+ * Index a store element snapshot once. Playback-only Zustand updates keep the
+ * same array identity, so selectors can reuse this object without rescanning a
+ * large timeline or triggering a component render.
+ */
+export function getTimelineElementIndexes(
+  elements: readonly TimelineElement[],
+): TimelineElementIndexes {
+  const cached = indexCache.get(elements);
+  if (cached) return cached;
+
+  const byKey = new Map<string, TimelineElement>();
+  const mediaElements: TimelineElement[] = [];
+  const audioTracks = new Set<number>();
+  let musicElement: TimelineElement | null = null;
+  for (const element of elements) {
+    byKey.set(getTimelineElementIdentity(element), element);
+    if (element.src) mediaElements.push(element);
+    if (isAudioTimelineElement(element)) audioTracks.add(element.track);
+    if (!musicElement && isMusicTrack(element)) musicElement = element;
+  }
+
+  const indexes = Object.freeze({
+    byKey,
+    musicElement,
+    mediaElements: Object.freeze(mediaElements),
+    audioTracks,
+  });
+  indexCache.set(elements, indexes);
+  return indexes;
+}

package/src/player/lib/timelinePerformanceDiagnostics.test.ts

@@ -0,0 +1,100 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  getTimelineResourceBudgetStatus,
+  readTimelinePerformanceDiagnostics,
+  resolveTimelineScrollStrategy,
+} from "./timelinePerformanceDiagnostics";
+import { resolveTimelineViewportBudgets } from "./timelineViewportBudgets";
+
+describe("timeline performance diagnostics", () => {
+  afterEach(() => {
+    document.body.replaceChildren();
+  });
+
+  it("reads mounted resources without mutating the timeline", () => {
+    document.body.innerHTML = `
+      <div aria-label="Timeline" data-timeline-scheduler-queued="3"
+           data-timeline-scheduler-active="2" data-timeline-cache-bytes="4096">
+        <div data-timeline-row><div data-clip="true"></div><div data-clip="true"></div></div>
+        <div data-timeline-row><div data-clip="true"></div></div>
+        <div data-clip="true"></div>
+        <div data-timeline-grid-cell></div><div data-timeline-grid-cell></div>
+        <div data-timeline-poster-state="ready"></div>
+        <div data-timeline-poster-state="error"></div>
+        <div data-timeline-poster-state="constructor"></div>
+      </div>`;
+    const before = document.body.innerHTML;
+
+    expect(readTimelinePerformanceDiagnostics()).toMatchObject({
+      timelineRoots: 1,
+      mountedRows: 2,
+      mountedClipRoots: 4,
+      maxMountedClipRootsInOneRow: 2,
+      mountedTimeGridCells: 2,
+      schedulerQueued: 3,
+      schedulerActive: 2,
+      cacheBytes: 4096,
+      posterStates: { idle: 0, loading: 0, ready: 1, fallback: 0, error: 1 },
+    });
+    expect(document.body.innerHTML).toBe(before);
+  });
+
+  it("returns the zero baseline after unmount or reset removes the DOM", () => {
+    document.body.innerHTML = '<div aria-label="Timeline"><div data-clip="true"></div></div>';
+    expect(readTimelinePerformanceDiagnostics().mountedClipRoots).toBe(1);
+
+    document.body.replaceChildren();
+
+    expect(readTimelinePerformanceDiagnostics()).toEqual({
+      timelineRoots: 0,
+      mountedRows: 0,
+      mountedClipRoots: 0,
+      maxMountedClipRootsInOneRow: 0,
+      mountedTimeGridCells: 0,
+      mountedTimelineDescendants: 0,
+      schedulerQueued: 0,
+      schedulerActive: 0,
+      cacheBytes: 0,
+      posterStates: { idle: 0, loading: 0, ready: 0, fallback: 0, error: 0 },
+    });
+  });
+
+  it("treats every DOM ceiling as inclusive", () => {
+    const budgets = resolveTimelineViewportBudgets({
+      maxMountedClipRoots: 2,
+      maxMountedClipRootsPerRow: 1,
+      maxMountedRows: 2,
+      maxMountedTimelineDescendants: 4,
+    });
+    expect(
+      getTimelineResourceBudgetStatus(
+        {
+          ...readTimelinePerformanceDiagnostics(),
+          mountedClipRoots: 2,
+          maxMountedClipRootsInOneRow: 2,
+          mountedTimelineDescendants: 4,
+        },
+        budgets,
+      ),
+    ).toEqual({
+      timelineRoot: false,
+      rows: true,
+      clipRoots: true,
+      clipRootsPerRow: false,
+      descendants: true,
+    });
+  });
+
+  it("fails the resource status when the timeline is absent", () => {
+    expect(getTimelineResourceBudgetStatus(readTimelinePerformanceDiagnostics())).toMatchObject({
+      timelineRoot: false,
+    });
+  });
+
+  it("selects direct scrolling only through the configured safety envelope", () => {
+    expect(resolveTimelineScrollStrategy(8_000_000)).toBe("direct");
+    expect(resolveTimelineScrollStrategy(8_000_001)).toBe("segmented");
+    expect(() => resolveTimelineScrollStrategy(Number.NaN)).toThrow("content width");
+  });
+});

package/src/player/lib/timelinePerformanceDiagnostics.ts

@@ -0,0 +1,120 @@
+import { TIMELINE_VIEWPORT_BUDGETS, type TimelineViewportBudgets } from "./timelineViewportBudgets";
+
+export type TimelinePosterState = "idle" | "loading" | "ready" | "fallback" | "error";
+
+export interface TimelinePerformanceDiagnostics {
+  timelineRoots: number;
+  mountedRows: number;
+  mountedClipRoots: number;
+  maxMountedClipRootsInOneRow: number;
+  mountedTimeGridCells: number;
+  mountedTimelineDescendants: number;
+  schedulerQueued: number;
+  schedulerActive: number;
+  cacheBytes: number;
+  posterStates: Readonly<Record<TimelinePosterState, number>>;
+}
+
+export interface TimelineResourceBudgetStatus {
+  timelineRoot: boolean;
+  rows: boolean;
+  clipRoots: boolean;
+  clipRootsPerRow: boolean;
+  descendants: boolean;
+}
+
+function readNonNegativeNumber(value: string | undefined): number {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : 0;
+}
+
+function countPosters(root: ParentNode): Readonly<Record<TimelinePosterState, number>> {
+  const counts: Record<TimelinePosterState, number> = {
+    idle: 0,
+    loading: 0,
+    ready: 0,
+    fallback: 0,
+    error: 0,
+  };
+  for (const node of root.querySelectorAll<HTMLElement>("[data-timeline-poster-state]")) {
+    const state = node.dataset.timelinePosterState;
+    if (state && Object.hasOwn(counts, state)) counts[state as TimelinePosterState] += 1;
+  }
+  return Object.freeze(counts);
+}
+
+function maxClipsInOneRow(root: ParentNode): number {
+  const byRow = new Map<Element, number>();
+  for (const clip of root.querySelectorAll<HTMLElement>('[data-clip="true"]')) {
+    const row = clip.closest("[data-timeline-row]");
+    if (!row) continue;
+    byRow.set(row, (byRow.get(row) ?? 0) + 1);
+  }
+  return Math.max(0, ...byRow.values());
+}
+
+function sumDataAttribute(root: ParentNode, selector: string, dataKey: string): number {
+  let total = 0;
+  for (const node of root.querySelectorAll<HTMLElement>(selector)) {
+    total += readNonNegativeNumber(node.dataset[dataKey]);
+  }
+  return total;
+}
+
+/**
+ * Read current timeline costs directly from the mounted DOM. No counters are
+ * retained, so an unmount or project reset is reflected as a zero baseline on
+ * the next read rather than depending on cleanup ordering.
+ */
+export function readTimelinePerformanceDiagnostics(
+  root: ParentNode = document,
+): Readonly<TimelinePerformanceDiagnostics> {
+  const timelineRoots = root.querySelectorAll<HTMLElement>('[aria-label="Timeline"]');
+  let mountedTimelineDescendants = 0;
+  for (const timelineRoot of timelineRoots) {
+    mountedTimelineDescendants += timelineRoot.querySelectorAll("*").length;
+  }
+  return Object.freeze({
+    timelineRoots: timelineRoots.length,
+    mountedRows: root.querySelectorAll("[data-timeline-row]").length,
+    mountedClipRoots: root.querySelectorAll('[data-clip="true"]').length,
+    maxMountedClipRootsInOneRow: maxClipsInOneRow(root),
+    mountedTimeGridCells: root.querySelectorAll("[data-timeline-grid-cell]").length,
+    mountedTimelineDescendants,
+    schedulerQueued: sumDataAttribute(
+      root,
+      "[data-timeline-scheduler-queued]",
+      "timelineSchedulerQueued",
+    ),
+    schedulerActive: sumDataAttribute(
+      root,
+      "[data-timeline-scheduler-active]",
+      "timelineSchedulerActive",
+    ),
+    cacheBytes: sumDataAttribute(root, "[data-timeline-cache-bytes]", "timelineCacheBytes"),
+    posterStates: countPosters(root),
+  });
+}
+
+export function getTimelineResourceBudgetStatus(
+  diagnostics: TimelinePerformanceDiagnostics,
+  budgets: Readonly<TimelineViewportBudgets> = TIMELINE_VIEWPORT_BUDGETS,
+): Readonly<TimelineResourceBudgetStatus> {
+  return Object.freeze({
+    timelineRoot: diagnostics.timelineRoots === 1,
+    rows: diagnostics.mountedRows <= budgets.maxMountedRows,
+    clipRoots: diagnostics.mountedClipRoots <= budgets.maxMountedClipRoots,
+    clipRootsPerRow: diagnostics.maxMountedClipRootsInOneRow <= budgets.maxMountedClipRootsPerRow,
+    descendants: diagnostics.mountedTimelineDescendants <= budgets.maxMountedTimelineDescendants,
+  });
+}
+
+export function resolveTimelineScrollStrategy(
+  contentWidthPx: number,
+  budgets: Readonly<TimelineViewportBudgets> = TIMELINE_VIEWPORT_BUDGETS,
+): "direct" | "segmented" {
+  if (!Number.isFinite(contentWidthPx) || contentWidthPx < 0) {
+    throw new RangeError("Timeline content width must be a finite non-negative number");
+  }
+  return contentWidthPx <= budgets.directScrollSafetyPx ? "direct" : "segmented";
+}