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:
Miguel Angel Simon Sierra
2026-08-06 07:55:42 -07:00
parent b94441697c
commit 0ff6bfa053
2 changed files with 148 additions and 0 deletions
@@ -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" };
}