fix(core): clips that meet within float rounding count as meeting in edits and playback

Author: miguel-heygen

packages/cli/src/timeline/a2Shared.ts

@@ -6,6 +6,7 @@ import {
 } from "@hyperframes/studio-server";
 import type { AppliedFileMutation, PatchOperation } from "@hyperframes/studio-server";
 import { fpsToNumber, parseFpsWithDefault } from "@hyperframes/core";
+import { spansOverlap } from "@hyperframes/core/clip-facts";
 import { readCompositionFps } from "../utils/compositionFps.js";
 import { readFileSync } from "node:fs";
 import type { ProjectTimeline, TimelineRow } from "./describeProject.js";
@@ -147,7 +148,7 @@ function overlap(
       candidate !== row &&
       candidate.file === row.file &&
       candidate.trackIndex === row.trackIndex &&
-      Math.max(start, candidate.start) < Math.min(end, candidate.end),
+      spansOverlap(start, end, candidate.start, candidate.end),
   );
 }
 
@@ -263,7 +264,8 @@ function finishTrim(
 ): MutationDecision | { ok: true; nextStart: number; nextDuration: number } {
   if (end && !end.ok) return end;
   if (duration && !duration.ok) return duration;
-  const nextDuration = duration?.seconds ?? (end ? end.seconds - nextStart : context.row.duration);
+  const nextDuration =
+    duration?.seconds ?? (end ? durationUntil(nextStart, end.seconds) : context.row.duration);
   if (nextDuration <= 0) {
     return {
       ok: false,
@@ -279,6 +281,19 @@ function trimStart(context: MutationContext, expression: string | undefined) {
   return parseMutationTime(context, expression, "pass a valid time expression");
 }
 
+function durationUntil(start: number, end: number): number {
+  let duration = end - start;
+  while (duration > 0 && start + duration > end) duration = nextSmaller(duration);
+  return duration;
+}
+
+const float = new DataView(new ArrayBuffer(8));
+function nextSmaller(positive: number): number {
+  float.setFloat64(0, positive);
+  float.setBigUint64(0, float.getBigUint64(0) - 1n);
+  return float.getFloat64(0);
+}
+
 function trimEnd(context: MutationContext, expression: string | undefined) {
   if (!expression) return undefined;
   return parseMutationTime(context, expression, "pass a valid time expression");
@@ -413,8 +428,7 @@ export function mutationConflict(
       (candidate) =>
         candidate.file === row.file &&
         candidate.trackIndex === row.trackIndex &&
-        candidate.start < nextStart &&
-        nextStart < candidate.end,
+        spansOverlap(nextStart, nextStart, candidate.start, candidate.end),
     );
     if (!conflict) return null;
     return {

packages/cli/src/timeline/timeline.e2e.test.ts

@@ -3,6 +3,7 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isClipVisibleAt } from "@hyperframes/core";
 import { describe, expect, it } from "vitest";
 
 const cliEntry = resolve(fileURLToPath(import.meta.url), "..", "..", "cli.ts");
@@ -102,6 +103,135 @@ describe("timeline edit command", () => {
     }
   });
 
+  const meeting = (aStart: string, aDuration: string, bStart: string, fps = "") =>
+    `<div data-composition-id="main"${fps} data-duration="40"><div id="a" data-hf-id="a" data-start="${aStart}" data-duration="${aDuration}" data-track-index="0"></div><div id="b" data-hf-id="b" data-start="${bStart}" data-duration="2" data-track-index="0"></div></div>`;
+  const clip = (html: string, id: string) => {
+    const tag = new RegExp(`<div[^>]*\\sid="${id}"[^>]*>`).exec(html)?.[0] ?? "";
+    const attr = (name: string) => new RegExp(`${name}="([^"]+)"`).exec(tag)?.[1];
+    return { start: attr("data-start"), duration: attr("data-duration") };
+  };
+  const endOf = (html: string, id: string) =>
+    Number(clip(html, id).start) + Number(clip(html, id).duration);
+  const visibleAt = (html: string, time: number, ids: string[]) =>
+    ids.filter((id) => isClipVisibleAt(time, Number(clip(html, id).start), endOf(html, id), 40));
+
+  const composition = (fps: string, ...clips: [string, string, string][]) =>
+    `<div data-composition-id="main"${fps} data-duration="40">${clips
+      .map(
+        ([id, start, duration]) =>
+          `<div id="${id}" data-hf-id="${id}" data-start="${start}" data-duration="${duration}" data-track-index="0"></div>`,
+      )
+      .join("")}</div>`;
+
+  it.each([
+    [
+      "move",
+      ["#b", "20f"],
+      composition(' data-fps="24"', ["a", "0", String(20 / 24 + 5e-7)], ["b", "2", "0.25"]),
+    ],
+    ["duplicate", ["#c", "--at", "1"], composition("", ["a", "0", "1.0000005"], ["c", "3", "1"])],
+  ])("refuses a %s that lands half a microsecond inside another clip", (verb, args, html) => {
+    const dir = project();
+    try {
+      writeFileSync(join(dir, "index.html"), html);
+      expect(run(dir, verb, ...args).status).not.toBe(0);
+      expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(html);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it.each([
+    [
+      "a clip wholly before the insertion point",
+      ["#x", "--at", "5"],
+      composition("", ["x", "0", "1"], ["t", "4.9999995", "0.0000002"]),
+      4.9999995,
+    ],
+    [
+      "a clip half a microsecond after it",
+      ["#a"],
+      composition("", ["a", "0", "1"], ["t", "1.0000005", "1"]),
+      1.0000005 + 1,
+    ],
+  ])("duplicates without snapping %s to the copy", (_, args, html, tStart) => {
+    const dir = project();
+    try {
+      writeFileSync(join(dir, "index.html"), html);
+      expect(run(dir, "duplicate", ...args).status).toBe(0);
+      expect(Number(clip(readFileSync(join(dir, "index.html"), "utf8"), "t").start)).toBe(tStart);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("trims a clip that only meets the one before it, ending where asked", () => {
+    const dir = project();
+    try {
+      writeFileSync(join(dir, "index.html"), meeting("19.8", "6.4", "26.2"));
+      expect(run(dir, "trim", "#b", "--end", "29").status).toBe(0);
+      const html = readFileSync(join(dir, "index.html"), "utf8");
+      expect(clip(html, "b")).toEqual({ start: "26.2", duration: "2.8000000000000007" });
+      expect(endOf(html, "b")).toBe(29);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("trims up to the next clip's start without ending past it, where no duration lands exactly", () => {
+    const dir = project();
+    try {
+      writeFileSync(join(dir, "index.html"), meeting("4.74", "10", "25.74"));
+      expect(run(dir, "trim", "#a", "--end", "25.74").status).toBe(0);
+      const html = readFileSync(join(dir, "index.html"), "utf8");
+      expect(endOf(html, "a")).toBeLessThanOrEqual(25.74);
+      expect(visibleAt(html, 25.74, ["a", "b"])).toEqual(["b"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("trims to frame 20 at 30 fps so that frame shows the next clip and not this one", () => {
+    const dir = project();
+    try {
+      writeFileSync(join(dir, "index.html"), meeting("0", "2", "2", ' data-fps="30"'));
+      expect(run(dir, "trim", "#a", "--end", "20f").status).toBe(0);
+      expect(run(dir, "trim", "#b", "--start", "20f").status).toBe(0);
+      const html = readFileSync(join(dir, "index.html"), "utf8");
+      expect([clip(html, "a").duration, clip(html, "b").start]).toEqual([
+        "0.6666666666666666",
+        "0.6666666666666666",
+      ]);
+      expect(visibleAt(html, 19 / 30, ["a", "b"])).toEqual(["a"]);
+      expect(visibleAt(html, 20 / 30, ["a", "b"])).toEqual(["b"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it.each([
+    ["19.8", "6.4", "26.2"],
+    ["0", "0.6666666666666666", "0.6666666666666666"],
+    ["0.1", "1.1", "1.2"],
+  ])(
+    "duplicates a clip at %s lasting %s up against the clip at %s, each boundary exact",
+    (aStart, aDuration, bStart) => {
+      const dir = project();
+      try {
+        writeFileSync(join(dir, "index.html"), meeting(aStart, aDuration, bStart));
+        expect(run(dir, "duplicate", "#a").status).toBe(0);
+        const html = readFileSync(join(dir, "index.html"), "utf8");
+        const ids = ["a", "a-copy", "b"];
+        expect(Number(clip(html, "a-copy").start)).toBe(endOf(html, "a"));
+        expect(Number(clip(html, "b").start)).toBe(endOf(html, "a-copy"));
+        expect(visibleAt(html, endOf(html, "a"), ids)).toEqual(["a-copy"]);
+        expect(visibleAt(html, endOf(html, "a-copy"), ids)).toEqual(["b"]);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+  );
+
   it("refuses an ambiguous reference", () => {
     const dir = project();
     try {

packages/core/src/clipFacts.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { byStart, formatClipLine, type ClipFact } from "./clipFacts.js";
+import { byStart, formatClipLine, sameInstant, spansOverlap, type ClipFact } from "./clipFacts.js";
 
 const clip = (over: Partial<ClipFact> = {}): ClipFact => ({
   id: "a",
@@ -60,3 +60,28 @@ describe("byStart", () => {
     expect(rows.sort(byStart).map((r) => r.id)).toEqual(["a", "b", "c"]);
   });
 });
+
+describe("spansOverlap", () => {
+  it("counts clips that only meet as apart, though the float sum of the first overshoots", () => {
+    expect(19.8 + 6.4).toBeGreaterThan(26.2);
+    expect(spansOverlap(19.8, 19.8 + 6.4, 26.2, 29)).toBe(false);
+    expect(spansOverlap(26.2, 29, 19.8, 19.8 + 6.4)).toBe(false);
+  });
+
+  it("counts clips that share time as overlapping, down to half a microsecond", () => {
+    expect(spansOverlap(0, 2, 1.9, 3)).toBe(true);
+    expect(spansOverlap(1, 2, 0, 5)).toBe(true);
+    expect(spansOverlap(0, 20 / 24 + 5e-7, 20 / 24, 20 / 24 + 0.25)).toBe(true);
+  });
+});
+
+describe("sameInstant", () => {
+  it("joins times a float rounding step apart, and nothing wider", () => {
+    expect(sameInstant(19.8 + 6.4, 26.2)).toBe(true);
+    expect(sameInstant(0.1 + 1.1, 1.2)).toBe(true);
+    expect(sameInstant(3600.1 + 0.2, 3600.3)).toBe(true);
+    expect(sameInstant(20 / 24 + 5e-7, 20 / 24)).toBe(false);
+    expect(sameInstant(1.0000005, 1)).toBe(false);
+    expect([sameInstant(5, Infinity), sameInstant(Infinity, Infinity)]).toEqual([false, true]);
+  });
+});

packages/core/src/clipFacts.ts

@@ -34,6 +34,18 @@ const roundTo3 = (n: number) => Math.round(n * 1000) / 1000;
 
 const num = (n: number) => String(roundTo3(n));
 
+/** Float sums like 19.8 + 6.4 miss 26.2 by a rounding step; a few steps, scaled to the time, are one instant. */
+export function sameInstant(a: number, b: number): boolean {
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return a === b;
+  return Math.abs(a - b) <= 4 * Number.EPSILON * Math.max(1, Math.abs(a), Math.abs(b));
+}
+
+const isBefore = (a: number, b: number) => a < b && !sameInstant(a, b);
+
+export function spansOverlap(aStart: number, aEnd: number, bStart: number, bEnd: number): boolean {
+  return isBefore(aStart, bEnd) && isBefore(bStart, aEnd);
+}
+
 export function formatClipLine(clip: ClipFact): string {
   const parts = [
     `${clip.kind} "${clip.id}"`,

packages/core/src/runtime/clipWindow.test.ts

@@ -5,6 +5,18 @@ describe("isInClipWindow", () => {
   it("includes the start and excludes the end", () => {
     expect([1, 1.5, 2].map((t) => isInClipWindow(t, 1, 2))).toEqual([true, true, false]);
   });
+
+  it("hands the instant a float sum misses by a rounding step to the next clip only", () => {
+    expect([isInClipWindow(26.2, 19.8, 19.8 + 6.4), isInClipWindow(26.2, 26.2, 28.2)]).toEqual([
+      false,
+      true,
+    ]);
+    expect(isInClipWindow(20 / 24, 0, 20 / 24 + 5e-7)).toBe(true);
+  });
+
+  it("keeps a clip with no known end in its window", () => {
+    expect(isInClipWindow(5, 0, Number.POSITIVE_INFINITY)).toBe(true);
+  });
 });
 
 describe("isClipVisibleAt", () => {

packages/core/src/runtime/clipWindow.ts

@@ -1,6 +1,10 @@
-/** Half-open: two back-to-back clips never both hold the shared boundary instant. */
+import { sameInstant } from "../clipFacts";
+
+const hasStarted = (time: number, start: number) => time >= start || sameInstant(time, start);
+
+/** Half-open: two back-to-back clips never both hold the shared boundary instant, float sums included. */
 export const isInClipWindow = (time: number, start: number, end: number): boolean =>
-  time >= start && time < end;
+  hasStarted(time, start) && time < end && !sameInstant(time, end);
 
 const TERMINAL_EPSILON_SECONDS = 1e-6;
 
@@ -15,6 +19,6 @@ export const isClipVisibleAt = (
   compositionDuration: number,
 ): boolean =>
   isInClipWindow(time, start, end) ||
-  (time >= start &&
+  (hasStarted(time, start) &&
     compositionDuration > 0 &&
     end >= compositionDuration - TERMINAL_EPSILON_SECONDS);

packages/core/src/runtime/media.test.ts

@@ -376,6 +376,14 @@ describe("syncRuntimeMedia", () => {
     document.body.innerHTML = "";
   });
 
+  it("seeks a clip whose start is a float sum to its first frame, never before it", () => {
+    const clip = createMockClip({ start: 19.8 + 0.1, end: 25 });
+    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
+    clip.el.currentTime = 3;
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 19.9, playing: false, playbackRate: 1 });
+    expect(clip.el.currentTime).toBe(0);
+  });
+
   describe("speed ramp", () => {
     it("seeks to the integrated source time and plays at the instantaneous rate", () => {
       const rate = {

packages/core/src/runtime/media.ts

@@ -327,7 +327,8 @@ export function syncRuntimeMedia(params: {
       params.timeSeconds >= clip.end &&
       isClipVisibleAt(params.timeSeconds, clip.start, clip.end, params.getCompositionDuration());
     let relTime =
-      sourceTimeAt(clipRate, Math.min(params.timeSeconds, clip.end) - clip.start) + clip.mediaStart;
+      sourceTimeAt(clipRate, Math.max(0, Math.min(params.timeSeconds, clip.end) - clip.start)) +
+      clip.mediaStart;
     const isHeldVideoTail =
       isTerminalVideo ||
       (isNonLoopVideo && clip.sourceDuration != null && relTime >= clip.sourceDuration && inWindow);

packages/studio-server/src/helpers/duplicateElement.ts

@@ -1,3 +1,4 @@
+import { sameInstant } from "@hyperframes/core/clip-facts";
 import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
 import {
   findTargetElement,
@@ -59,9 +60,10 @@ function rippleElements(
       continue;
     }
     const start = numericAttribute(candidate, "data-start");
-    if (start !== null && start >= at) {
-      candidate.setAttribute("data-start", String(start + duration));
-    }
+    if (start === null) continue;
+    const metInsertionPoint = sameInstant(start, at);
+    if (start < at && !metInsertionPoint) continue;
+    candidate.setAttribute("data-start", String((metInsertionPoint ? at : start) + duration));
   }
 }
 

packages/studio/src/player/components/timelineStackingSync.ts

@@ -17,6 +17,8 @@
  * style) and apply the returned `StackingPatch[]` however they persist styles.
  */
 
+import { spansOverlap } from "@hyperframes/core/clip-facts";
+
 /** Minimal element view this module reasons over. */
 export interface StackingElement {
   /** Stable identity (TimelineElement.key ?? id). */
@@ -69,8 +71,6 @@ export interface StackingPatch {
   zIndex: number;
 }
 
-const EPS = 1e-6;
-
 /**
  * Canonical paint-scope key: leaf z-indexes are comparable only within the same
  * source document and CSS stacking context. The ONLY place this normalization
@@ -90,17 +90,17 @@ export function samePaintScope(
 /**
  * Two clips overlap in time when their half-open [start, end) intervals intersect.
  *
- * NOTE the `- EPS`: this DELIBERATELY diverges from `timeRangesOverlap`'s exact
+ * NOTE the float slack: this DELIBERATELY diverges from `timeRangesOverlap`'s exact
  * strict-`<` (timelineCollision.ts). A boolean collision decision is idempotent, so
  * exact `<` is fine there; here the result drives a VISIBLE stacking re-lane, so the
- * epsilon guards against float fuzz (e.g. 5.0000001 vs 5) spuriously overlapping two
+ * epsilon guards against float fuzz (e.g. 19.8 + 6.4 vs 26.2) spuriously overlapping two
  * abutting clips and shuffling lanes. The two are intended to differ, not align.
  */
 function overlapsInTime(
   a: Pick<StackingElement, "start" | "duration">,
   b: Pick<StackingElement, "start" | "duration">,
 ): boolean {
-  return a.start < b.start + b.duration - EPS && b.start < a.start + a.duration - EPS;
+  return spansOverlap(a.start, a.start + a.duration, b.start, b.start + b.duration);
 }
 
 /**