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 { isInsideSpan, sameInstant, spansShareTime } 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),
+      spansShareTime(start, end, candidate.start, candidate.end),
   );
 }
 
@@ -263,8 +264,9 @@ 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);
-  if (nextDuration <= 0) {
+  const nextDuration =
+    duration?.seconds ?? (end ? durationUntil(nextStart, end.seconds) : context.row.duration);
+  if (nextDuration <= 0 || sameInstant(nextStart, nextStart + nextDuration)) {
     return {
       ok: false,
       reason: "trim duration must be positive",
@@ -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,
+        isInsideSpan(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 {
@@ -257,6 +387,36 @@ describe("timeline edit command", () => {
     }
   });
 
+  it("refuses a trim that would leave a clip one float rounding step long", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-timeline-cli-"));
+    try {
+      const indexPath = join(dir, "index.html");
+      writeFileSync(indexPath, meeting("19.8", "6.4", "26.2"));
+      const result = run(dir, "trim", "#b", "--end", "26.200000000000003");
+      expect(result.status).toBe(2);
+      expect(result.stderr).toContain("trim duration must be positive");
+      expect(clip(readFileSync(indexPath, "utf8"), "b").duration).toBe("2");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("moves a clip over pending media, whose unknown length counts as zero", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-timeline-cli-"));
+    try {
+      const indexPath = join(dir, "index.html");
+      writeFileSync(
+        indexPath,
+        `<div data-composition-id="main" data-duration="12"><div id="a" data-hf-id="a" data-start="3" data-duration="1" data-track-index="0"></div><video id="pending" data-hf-id="pending" src="https://example.com/v.mp4" data-start="1" data-track-index="0"></video></div>`,
+      );
+      const result = run(dir, "move", "#a", "0.5");
+      expect(result.status, result.stderr).toBe(0);
+      expect(clip(readFileSync(indexPath, "utf8"), "a").start).toBe("0.5");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   it("refuses duplicate insertion inside a spanning clip", () => {
     const dir = project();
     try {

packages/core/src/clipFacts.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, it } from "vitest";
-import { byStart, formatClipLine, type ClipFact } from "./clipFacts.js";
+import {
+  byStart,
+  formatClipLine,
+  isInsideSpan,
+  sameInstant,
+  spansOverlap,
+  spansShareTime,
+  type ClipFact,
+} from "./clipFacts.js";
 
 const clip = (over: Partial<ClipFact> = {}): ClipFact => ({
   id: "a",
@@ -60,3 +68,53 @@ 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);
+  });
+
+  it("counts a zero-length clip inside another, so the timeline gives it a lane of its own", () => {
+    expect(spansOverlap(1, 1, 0.5, 1.5)).toBe(true);
+  });
+});
+
+describe("spansShareTime", () => {
+  it("never counts a zero-length span, such as pending media, as sharing time", () => {
+    expect(spansShareTime(1, 1, 0.5, 1.5)).toBe(false);
+    expect(spansShareTime(0.5, 1.5, 1, 1)).toBe(false);
+  });
+
+  it("agrees with spansOverlap on spans with length, float sums included", () => {
+    expect(spansShareTime(19.8, 19.8 + 6.4, 26.2, 29)).toBe(false);
+    expect(spansShareTime(0, 20 / 24 + 5e-7, 20 / 24, 20 / 24 + 0.25)).toBe(true);
+    expect(spansShareTime(1, 2, 0, 5)).toBe(true);
+  });
+});
+
+describe("isInsideSpan", () => {
+  it("counts a time strictly inside, and not one on either edge within float rounding", () => {
+    expect(isInsideSpan(3, 1, 5)).toBe(true);
+    expect(isInsideSpan(26.2, 19.8, 19.8 + 6.4)).toBe(false);
+    expect(isInsideSpan(1, 1, 5)).toBe(false);
+  });
+});
+
+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,33 @@ const roundTo3 = (n: number) => Math.round(n * 1000) / 1000;
 
 const num = (n: number) => String(roundTo3(n));
 
+export const instantTolerance = (time: number) => 4 * Number.EPSILON * Math.max(1, Math.abs(time));
+
+/** 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) <= instantTolerance(Math.max(Math.abs(a), Math.abs(b)));
+}
+
+const isBefore = (a: number, b: number) => a < b && !sameInstant(a, b);
+
+/** For timeline lanes: a zero-length clip inside another still counts, so it gets a lane of its own. */
+export function spansOverlap(aStart: number, aEnd: number, bStart: number, bEnd: number): boolean {
+  return isBefore(aStart, bEnd) && isBefore(bStart, aEnd);
+}
+
+export function spansShareTime(
+  aStart: number,
+  aEnd: number,
+  bStart: number,
+  bEnd: number,
+): boolean {
+  return isBefore(Math.max(aStart, bStart), Math.min(aEnd, bEnd));
+}
+
+export const isInsideSpan = (time: number, start: number, end: number) =>
+  isBefore(start, time) && isBefore(time, end);
+
 export function formatClipLine(clip: ClipFact): string {
   const parts = [
     `${clip.kind} "${clip.id}"`,

packages/core/src/index.ts

@@ -320,7 +320,7 @@ export {
 // (verify:packed-manifests catches exactly that).
 export { createRuntimeStartTimeResolver } from "./runtime/startResolver.js";
 // Also exposed via the ./runtime/clip-window subpath; re-exported here for the same dist-emit reason.
-export { isClipVisibleAt, isInClipWindow } from "./runtime/clipWindow.js";
+export { hasClipStarted, isClipVisibleAt, isInClipWindow } from "./runtime/clipWindow.js";
 export {
   normalizePlaybackRate,
   normalizeRateSpec,

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