mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
feat(studio): translate an authored track into the lane it draws on
An agent only ever knows data-track-index. Studio packs those onto contiguous display lanes, so on any composition with gaps the number the agent writes is not the row the user sees: authored 0, 4, 9 draws on lanes 0, 1, 2. This is the inverse of authoredTrackForLane and sits beside it so the two stay readable against each other, with a round-trip test holding them to agreeing. It is scoped by source file for the same reason the forward direction is: an expanded sub-composition's rows carry authored numbers from their own file, and matching one would draw on a row belonging to a different composition. A track with no clips yet reports provisional rather than snapping to the nearest lane. An agent adding a whole new track is the most interesting thing it can say, and it has to be drawable before the clips that would give it a lane exist. The result is a discriminated shape, not a number with a sentinel, because lane 0 is a real answer.
This commit is contained in:
@@ -0,0 +1,95 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { authoredTrackForLane, laneForAuthoredTrack } from "./timelineAuthoredTrack";
|
||||
import type { TimelineElement } from "../store/playerStore";
|
||||
|
||||
/**
|
||||
* A clip on a display lane, with the authored track it came from.
|
||||
*
|
||||
* The two differ on purpose in most of these: a composition whose authored
|
||||
* tracks are 0, 4 and 9 packs onto lanes 0, 1 and 2, and that gap is the whole
|
||||
* reason this translation exists.
|
||||
*/
|
||||
function clip(
|
||||
id: string,
|
||||
lane: number,
|
||||
authoredTrack: number,
|
||||
sourceFile = "index.html",
|
||||
): TimelineElement {
|
||||
return {
|
||||
id,
|
||||
tag: "div",
|
||||
start: 0,
|
||||
duration: 1,
|
||||
track: lane,
|
||||
authoredTrack,
|
||||
sourceFile,
|
||||
} as TimelineElement;
|
||||
}
|
||||
|
||||
/** Authored 0, 4, 9 packed onto lanes 0, 1, 2. */
|
||||
const SPARSE = [clip("a", 0, 0), clip("b", 1, 4), clip("c", 2, 9)];
|
||||
|
||||
describe("laneForAuthoredTrack", () => {
|
||||
it("puts a declared track on the lane its own clips occupy", () => {
|
||||
expect(laneForAuthoredTrack(4, SPARSE, "index.html")).toEqual({ kind: "lane", lane: 1 });
|
||||
expect(laneForAuthoredTrack(9, SPARSE, "index.html")).toEqual({ kind: "lane", lane: 2 });
|
||||
});
|
||||
|
||||
// The number the agent writes is not the row the user sees.
|
||||
it("does not mistake the authored number for the lane number", () => {
|
||||
expect(laneForAuthoredTrack(9, SPARSE, "index.html")).not.toEqual({ kind: "lane", lane: 9 });
|
||||
});
|
||||
|
||||
it("gives two declarations on one track the same lane", () => {
|
||||
expect(laneForAuthoredTrack(4, SPARSE, "index.html")).toEqual(
|
||||
laneForAuthoredTrack(4, SPARSE, "index.html"),
|
||||
);
|
||||
});
|
||||
|
||||
// A whole new track is the most interesting thing an agent can declare.
|
||||
it("reports a track with no clips anywhere as provisional", () => {
|
||||
expect(laneForAuthoredTrack(12, SPARSE, "index.html")).toEqual({ kind: "provisional" });
|
||||
});
|
||||
|
||||
it("reports every track as provisional on an empty timeline", () => {
|
||||
expect(laneForAuthoredTrack(0, [], "index.html")).toEqual({ kind: "provisional" });
|
||||
expect(laneForAuthoredTrack(7, [], "index.html")).toEqual({ kind: "provisional" });
|
||||
});
|
||||
|
||||
// An expanded sub-composition's rows carry authored numbers from their own
|
||||
// file; matching one would draw on a row belonging to another composition.
|
||||
it("ignores a clip that only matches in a different source file", () => {
|
||||
const elsewhere = [clip("x", 0, 0, "index.html"), clip("y", 1, 4, "scenes/intro.html")];
|
||||
expect(laneForAuthoredTrack(4, elsewhere, "index.html")).toEqual({ kind: "provisional" });
|
||||
expect(laneForAuthoredTrack(4, elsewhere, "scenes/intro.html")).toEqual({
|
||||
kind: "lane",
|
||||
lane: 1,
|
||||
});
|
||||
});
|
||||
|
||||
it("treats a declaration with no file as being about the unnamed file", () => {
|
||||
const unnamed = [{ ...clip("a", 0, 3), sourceFile: undefined } as TimelineElement];
|
||||
expect(laneForAuthoredTrack(3, unnamed, null)).toEqual({ kind: "lane", lane: 0 });
|
||||
expect(laneForAuthoredTrack(3, unnamed, "index.html")).toEqual({ kind: "provisional" });
|
||||
});
|
||||
|
||||
// Lane 0 is a real answer and must not read as "nowhere".
|
||||
it("distinguishes lane zero from having no lane", () => {
|
||||
expect(laneForAuthoredTrack(0, SPARSE, "index.html")).toEqual({ kind: "lane", lane: 0 });
|
||||
});
|
||||
});
|
||||
|
||||
describe("laneForAuthoredTrack and authoredTrackForLane", () => {
|
||||
// The two directions have to agree, or a skeleton lands somewhere a clip
|
||||
// dragged to the same row would not persist to.
|
||||
it("round-trips every authored track in a sparse file", () => {
|
||||
for (const element of SPARSE) {
|
||||
const authored = element.authoredTrack!;
|
||||
const lane = laneForAuthoredTrack(authored, SPARSE, "index.html");
|
||||
expect(lane).toEqual({ kind: "lane", lane: element.track });
|
||||
|
||||
const dragged = { ...element, id: "dragged", key: "dragged" } as TimelineElement;
|
||||
expect(authoredTrackForLane(element.track, SPARSE, dragged)).toBe(authored);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -27,3 +27,56 @@ export function authoredTrackForLane(
|
||||
// Synthetic expanded-child display rows can be fractional; authored tracks cannot.
|
||||
return Math.round((nearest.authoredTrack ?? nearest.track) + (lane - nearest.track));
|
||||
}
|
||||
|
||||
/**
|
||||
* Where a declared authored track should draw, or that it has nowhere yet.
|
||||
*
|
||||
* `provisional` is not an error: an agent adding a whole new track is the most
|
||||
* interesting thing it can say, and it must be drawable before the clips that
|
||||
* would give it a lane exist.
|
||||
*/
|
||||
export type AuthoredTrackLane = { kind: "lane"; lane: number } | { kind: "provisional" };
|
||||
|
||||
/**
|
||||
* Translate a source-file track index into the display lane it belongs on.
|
||||
*
|
||||
* The inverse of `authoredTrackForLane`, and kept beside it so the two stay
|
||||
* readable against each other. An agent only ever knows `data-track-index`;
|
||||
* Studio packs those onto contiguous lanes, so on any composition with gaps
|
||||
* the number the agent writes is not the row the user sees.
|
||||
*
|
||||
* `file` scopes the search the way `sameSourceFile` scopes the forward
|
||||
* direction: an expanded sub-composition's rows carry authored numbers from
|
||||
* their OWN file, and matching one of those would put the skeleton on a row
|
||||
* belonging to a different composition entirely.
|
||||
*/
|
||||
export function laneForAuthoredTrack(
|
||||
authoredTrack: number,
|
||||
elements: readonly TimelineElement[],
|
||||
file: string | null,
|
||||
): AuthoredTrackLane {
|
||||
const peers = elements.filter((element) => (element.sourceFile ?? null) === file);
|
||||
if (peers.length === 0) return { kind: "provisional" };
|
||||
|
||||
const occupant = peers.find((peer) => (peer.authoredTrack ?? peer.track) === authoredTrack);
|
||||
if (occupant) return { kind: "lane", lane: occupant.track };
|
||||
|
||||
// No clip on that track yet. The nearest peer gives an offset, the same
|
||||
// nearest-neighbour rule the forward direction uses, but the answer is only
|
||||
// trusted when it lands on a lane this file actually occupies: anything else
|
||||
// would draw the skeleton on top of an unrelated track and quietly lie.
|
||||
let nearest: TimelineElement | null = null;
|
||||
for (const peer of peers) {
|
||||
const peerTrack = peer.authoredTrack ?? peer.track;
|
||||
const nearestTrack = nearest ? (nearest.authoredTrack ?? nearest.track) : 0;
|
||||
if (!nearest || Math.abs(peerTrack - authoredTrack) < Math.abs(nearestTrack - authoredTrack)) {
|
||||
nearest = peer;
|
||||
}
|
||||
}
|
||||
if (!nearest) return { kind: "provisional" };
|
||||
|
||||
const lane = nearest.track + (authoredTrack - (nearest.authoredTrack ?? nearest.track));
|
||||
return peers.some((peer) => peer.track === lane)
|
||||
? { kind: "lane", lane }
|
||||
: { kind: "provisional" };
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user