Skip to content

Commit 1e7799b

Browse files
vanceingallsclaude
andcommitted
fix(core): let a composition declare its caption colour states
Classification by colour equality has to guess: it takes the first colour tween's value as the dim baseline and calls everything else active. A composition whose two states share a colour therefore has every tween classified dim, and the caller's activeColor is silently dropped -- a real failure, now covered by a test that fails without this change. A tween may declare its state as data: { captionState: "dim" | "active" }. GSAP passes unknown vars through untouched, so declaring costs nothing at runtime, and resolution is per tween -- a composition can declare some and leave the rest to the fallback, which is unchanged for anything undeclared. This is the composition telling us what it built rather than us inferring it from what it happens to look like. The data-driven caption templates already author their state tweens from resolved values and never guess; this closes part of that capability gap. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent d9b00e5 commit 1e7799b

2 files changed

Lines changed: 87 additions & 6 deletions

File tree

‎packages/core/src/runtime/captionOverrides.test.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,19 @@ function installGsapMock() {
3434
return { setCalls };
3535
}
3636

37+
/** A gsap mock whose `getTweensOf` returns the supplied colour tweens, so classification is testable. */
38+
function installGsapMockWithTweens(tweens: Array<Record<string, unknown>>) {
39+
const gsap = {
40+
set() {},
41+
killTweensOf() {},
42+
getTweensOf() {
43+
return tweens.map((vars, i) => ({ vars, startTime: () => i }));
44+
},
45+
};
46+
Object.defineProperty(window, "gsap", { configurable: true, value: gsap });
47+
return tweens;
48+
}
49+
3750
async function flushCaptionOverrides() {
3851
for (let i = 0; i < 4; i++) {
3952
await Promise.resolve();
@@ -122,3 +135,52 @@ describe("applyCaptionOverrides", () => {
122135
expect(setCalls[0]?.vars).toEqual({ x: 16 });
123136
});
124137
});
138+
139+
describe("caption state declaration", () => {
140+
it("honours a declared state when dim and active colours are IDENTICAL", async () => {
141+
// The failure the declaration exists for. Classification by colour equality takes the first
142+
// tween's colour as the dim baseline, so a composition whose two states share a colour has
143+
// every tween classified dim — and `activeColor` is silently dropped.
144+
const tweens = installGsapMockWithTweens([
145+
{ color: "#888", data: { captionState: "dim" } },
146+
{ color: "#888", data: { captionState: "active" } },
147+
]);
148+
installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#111", activeColor: "#eee" }]);
149+
document.body.innerHTML = `<div class="caption-group"><span id="w0">Hi</span></div>`;
150+
151+
applyCaptionOverrides();
152+
await flushCaptionOverrides();
153+
154+
expect(tweens[0].color).toBe("#111");
155+
expect(tweens[1].color).toBe("#eee");
156+
});
157+
158+
it("falls back to colour classification when nothing is declared", async () => {
159+
// Undeclared compositions must keep working exactly as before — the declaration is additive.
160+
const tweens = installGsapMockWithTweens([{ color: "#222" }, { color: "#fff" }]);
161+
installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#111", activeColor: "#eee" }]);
162+
document.body.innerHTML = `<div class="caption-group"><span id="w0">Hi</span></div>`;
163+
164+
applyCaptionOverrides();
165+
await flushCaptionOverrides();
166+
167+
expect(tweens[0].color).toBe("#111");
168+
expect(tweens[1].color).toBe("#eee");
169+
});
170+
171+
it("prefers the declaration over the colour heuristic when they disagree", async () => {
172+
// Declared order is deliberately the reverse of what colour-equality would infer.
173+
const tweens = installGsapMockWithTweens([
174+
{ color: "#222", data: { captionState: "active" } },
175+
{ color: "#fff", data: { captionState: "dim" } },
176+
]);
177+
installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#111", activeColor: "#eee" }]);
178+
document.body.innerHTML = `<div class="caption-group"><span id="w0">Hi</span></div>`;
179+
180+
applyCaptionOverrides();
181+
await flushCaptionOverrides();
182+
183+
expect(tweens[0].color).toBe("#eee");
184+
expect(tweens[1].color).toBe("#111");
185+
});
186+
});

‎packages/core/src/runtime/captionOverrides.ts‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,23 @@ interface GsapStatic {
3838
getTweensOf: (target: Element) => GsapTween[];
3939
}
4040

41+
/**
42+
* The caption state a composition DECLARES for a colour tween, if any.
43+
*
44+
* Authored as `data: { captionState: "dim" | "active" }` in the tween's vars. GSAP passes unknown
45+
* vars through untouched, so this costs a declaring composition nothing at runtime.
46+
*
47+
* It exists because the fallback below has to GUESS. Classifying by colour equality breaks outright
48+
* when a composition's two states share a colour: every tween matches the dim baseline, and the
49+
* active override is silently dropped. A declaration is the composition telling us what it built,
50+
* rather than us inferring it from what it happens to look like.
51+
*/
52+
function declaredCaptionState(tween: GsapTween): "dim" | "active" | undefined {
53+
const data = tween.vars.data as { captionState?: unknown } | undefined;
54+
const state = data?.captionState;
55+
return state === "dim" || state === "active" ? state : undefined;
56+
}
57+
4158
function resolveCaptionWordElement(el: Element | null): HTMLElement | null {
4259
if (!(el instanceof HTMLElement)) return null;
4360
if (el.dataset.captionWrapper !== "true") return el;
@@ -138,13 +155,15 @@ export function applyCaptionOverrides(): void {
138155
const dimBaseline = colorTweens[0] ? String(colorTweens[0].vars.color) : "";
139156

140157
for (const tw of colorTweens) {
141-
const tweenColor = String(tw.vars.color);
142-
if (tweenColor === dimBaseline) {
143-
// This tween targets the dim/inactive color
158+
// A declaration wins over the colour guess, per tween, so a composition can declare
159+
// some tweens and leave others to the fallback.
160+
const state =
161+
declaredCaptionState(tw) ??
162+
(String(tw.vars.color) === dimBaseline ? "dim" : "active");
163+
if (state === "dim") {
144164
if (override.dimColor) tw.vars.color = override.dimColor;
145-
} else {
146-
// This tween targets the active/spoken color
147-
if (override.activeColor) tw.vars.color = override.activeColor;
165+
} else if (override.activeColor) {
166+
tw.vars.color = override.activeColor;
148167
}
149168
}
150169

0 commit comments

Comments
 (0)