@hyperframes/studio 0.7.39 → 0.7.41

package/src/player/components/timelineMotionStyles.test.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+const studioCss = readFileSync(new URL("../../styles/studio.css", import.meta.url), "utf8");
+const timelineClipSource = readFileSync(new URL("./TimelineClip.tsx", import.meta.url), "utf8");
+const playheadSource = readFileSync(new URL("./PlayheadIndicator.tsx", import.meta.url), "utf8");
+
+const allowedTimelineTransitionProperties = [
+  "background-color",
+  "border-color",
+  "box-shadow",
+  "color",
+  "opacity",
+];
+
+function expectRule(css: string, selector: string): string {
+  const selectorStart = css.indexOf(`${selector} {`);
+  expect(selectorStart).toBeGreaterThanOrEqual(0);
+
+  const bodyStart = css.indexOf("{", selectorStart);
+  const bodyEnd = css.indexOf("}", bodyStart);
+  expect(bodyStart).toBeGreaterThanOrEqual(0);
+  expect(bodyEnd).toBeGreaterThan(bodyStart);
+
+  return css.slice(bodyStart + 1, bodyEnd).trim();
+}
+
+function expectDeclaration(ruleBody: string, property: string): string {
+  const declarationMatch = new RegExp(`${property}:\\s*([^;]+);`).exec(ruleBody);
+  expect(declarationMatch?.[1]).toBeDefined();
+  return declarationMatch?.[1].trim() ?? "";
+}
+
+function transitionProperties(transitionDeclaration: string): string[] {
+  const items: string[] = [];
+  let depth = 0;
+  let item = "";
+
+  for (const char of transitionDeclaration) {
+    if (char === "(") depth += 1;
+    if (char === ")") depth -= 1;
+    if (char === "," && depth === 0) {
+      items.push(item.trim());
+      item = "";
+      continue;
+    }
+    item += char;
+  }
+
+  if (item.trim().length > 0) items.push(item.trim());
+
+  return items.map((transition) => transition.split(/\s+/)[0]);
+}
+
+describe("timeline motion styles", () => {
+  it("keeps clip motion reduced-motion gated and layout safe", () => {
+    const mediaStart = studioCss.indexOf("@media (prefers-reduced-motion: no-preference)");
+    expect(mediaStart).toBeGreaterThanOrEqual(0);
+
+    const beforeMotionMedia = studioCss.slice(0, mediaStart);
+    const baseTimelineClipRule = expectRule(beforeMotionMedia, ".timeline-clip");
+    expect(baseTimelineClipRule).not.toContain("transition");
+
+    const motionMediaCss = studioCss.slice(mediaStart);
+    const timelineClipMotionRule = expectRule(motionMediaCss, ".timeline-clip");
+    const clipTransition = expectDeclaration(timelineClipMotionRule, "transition");
+
+    expect(transitionProperties(clipTransition)).toEqual(allowedTimelineTransitionProperties);
+    expect(clipTransition).not.toMatch(/\b(?:all|left|width|top|bottom|transform)\b/);
+  });
+
+  it("layers the active mint bloom through opacity instead of a gradient background swap", () => {
+    const baseTimelineClipRule = expectRule(studioCss, ".timeline-clip");
+    const activeTimelineClipRule = expectRule(studioCss, ".timeline-clip[data-active]");
+    const bloomOverlayRule = expectRule(studioCss, ".timeline-clip::before");
+    const activeBloomOverlayRule = expectRule(studioCss, ".timeline-clip[data-active]::before");
+
+    expect(baseTimelineClipRule).toContain("background-color: rgba(255, 255, 255, 0.055)");
+    expect(activeTimelineClipRule).not.toContain("background: linear-gradient");
+    expect(activeTimelineClipRule).toContain("border-color: rgba(60, 230, 172, 0.55)");
+    expect(activeTimelineClipRule).not.toContain("box-shadow");
+    expect(bloomOverlayRule).toContain("background: rgba(60, 230, 172, 0.2)");
+    expect(bloomOverlayRule).not.toContain("linear-gradient");
+    expect(bloomOverlayRule).toContain("opacity: 0");
+    expect(activeBloomOverlayRule).toContain("opacity: 1");
+  });
+
+  it("targets trim handle bars without changing drag geometry", () => {
+    const handleClassMatches = timelineClipSource.match(/className="timeline-clip__handle-bar"/g);
+
+    expect(handleClassMatches).toHaveLength(2);
+    expect(timelineClipSource).toContain('transform: isDragging ? "translateY(-1px)" : undefined');
+    expect(timelineClipSource).not.toContain("scale(");
+  });
+
+  it("keeps the playhead polish static, without transition-driven positioning", () => {
+    expect(playheadSource).toContain("boxShadow");
+    expect(playheadSource).toContain("rotate(45deg)");
+    expect(playheadSource).not.toContain("transition");
+  });
+});

package/src/player/components/timelineTheme.test.ts

@@ -4,14 +4,31 @@ import {
   getRenderedTimelineElement,
   getTimelineTrackStyle,
 } from "./timelineTheme";
+import { getTrackStyle } from "./timelineIcons";
 
 describe("getTimelineTrackStyle", () => {
-  it("reuses heading styles for heading tags", () => {
-    expect(getTimelineTrackStyle("h2").accent).toBe(getTimelineTrackStyle("h1").accent);
+  it("uses one neutral clip style for every timeline tag", () => {
+    const expectedStyle = {
+      clip: "rgba(255,255,255,0.055)",
+      clipActive: "rgba(60,230,172,0.16)",
+      accent: "#3CE6AC",
+      label: "rgba(255,255,255,0.5)",
+    };
+
+    expect(getTimelineTrackStyle("video")).toEqual(expectedStyle);
+    expect(getTimelineTrackStyle("audio")).toEqual(expectedStyle);
+    expect(getTimelineTrackStyle("custom-tag")).toEqual(expectedStyle);
+    expect(getTimelineTrackStyle("video")).toEqual(getTimelineTrackStyle("audio"));
+    expect(getTimelineTrackStyle("video")).toEqual(getTimelineTrackStyle("custom-tag"));
   });
+});
 
-  it("falls back for unknown tags", () => {
-    expect(getTimelineTrackStyle("custom-tag").accent).toBe("#3CE6AC");
+describe("getTrackStyle", () => {
+  it("returns the timeline style only and preserves the empty tag fallback", () => {
+    const style = getTrackStyle("");
+    expect(style).toEqual(getTimelineTrackStyle("div"));
+    expect(Object.keys(style)).not.toContain("icon");
+    expect(Object.keys(style)).not.toContain("iconBackground");
   });
 });
 

package/src/player/components/timelineTheme.ts

@@ -4,7 +4,7 @@ export interface TimelineTrackStyle {
   clip: string;
   accent: string;
   label: string;
-  iconBackground: string;
+  clipActive?: string;
 }
 
 export interface TimelineTheme {
@@ -36,25 +36,25 @@ export interface TimelineTheme {
 }
 
 const TRACK_STYLE: TimelineTrackStyle = {
-  clip: "#1c2028",
+  clip: "rgba(255,255,255,0.055)",
+  clipActive: "rgba(60,230,172,0.16)",
   accent: "#3CE6AC",
-  label: "#dde1e8",
-  iconBackground: "rgba(255,255,255,0.06)",
+  label: "rgba(255,255,255,0.5)",
 };
 
 export const defaultTimelineTheme: TimelineTheme = {
   shellBackground: "#0A0A0B",
   shellBorder: "rgba(255,255,255,0.05)",
-  rulerBorder: "rgba(255,255,255,0.045)",
-  rowBackground: "#0A0A0B",
-  rowBorder: "rgba(255,255,255,0.05)",
-  gutterBackground: "#0A0A0B",
-  gutterBorder: "rgba(255,255,255,0.05)",
-  textPrimary: "#E8EDF5",
-  textSecondary: "#8391A8",
-  tickText: "rgba(131,145,168,0.92)",
-  tickMajor: "rgba(255,255,255,0.13)",
-  tickMinor: "rgba(255,255,255,0.08)",
+  rulerBorder: "rgba(255,255,255,0.16)",
+  rowBackground: "#0B0C0F",
+  rowBorder: "rgba(255,255,255,0.06)",
+  gutterBackground: "#0E0F12",
+  gutterBorder: "rgba(255,255,255,0.10)",
+  textPrimary: "rgba(255,255,255,0.92)",
+  textSecondary: "rgba(255,255,255,0.62)",
+  tickText: "rgba(255,255,255,0.34)",
+  tickMajor: "rgba(255,255,255,0.10)",
+  tickMinor: "rgba(255,255,255,0.06)",
   clipBackground: "#141922",
   clipBackgroundActive: "#181e28",
   clipBorder: "rgba(255,255,255,0.10)",
@@ -67,7 +67,7 @@ export const defaultTimelineTheme: TimelineTheme = {
   handleColor: "rgba(255,255,255,0.2)",
   panelResizeSeam: "rgba(255,255,255,0.12)",
   panelResizeActive: "rgba(255,255,255,0.24)",
-  clipRadius: "6px",
+  clipRadius: "8px",
 };
 
 export function getTimelineTrackStyle(_tag: string): TimelineTrackStyle {

package/src/player/components/useTimelineActiveClips.test.ts

@@ -0,0 +1,93 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it } from "vitest";
+import { updateTimelineActiveClipClasses } from "./useTimelineActiveClips";
+
+function appendClip(container: HTMLElement, id: string, start: string, end: string): HTMLElement {
+  const clip = document.createElement("div");
+  clip.dataset.clip = "true";
+  clip.dataset.elId = id;
+  clip.dataset.clipStart = start;
+  clip.dataset.clipEnd = end;
+  container.append(clip);
+  return clip;
+}
+
+describe("updateTimelineActiveClipClasses", () => {
+  it("toggles data-active only for clips containing the current time", () => {
+    const container = document.createElement("div");
+    const intro = appendClip(container, "intro", "0", "2");
+    const hero = appendClip(container, "hero", "2", "5");
+    const outro = appendClip(container, "outro", "5", "8");
+    const previous = new Set<string>();
+
+    updateTimelineActiveClipClasses(container, previous, 2.25);
+
+    expect(intro.hasAttribute("data-active")).toBe(false);
+    expect(hero.hasAttribute("data-active")).toBe(true);
+    expect(outro.hasAttribute("data-active")).toBe(false);
+    expect(previous).toEqual(new Set(["hero"]));
+  });
+
+  it("never marks hidden clips active inside their time window", () => {
+    const container = document.createElement("div");
+    const hidden = appendClip(container, "hidden", "0", "5");
+    const visible = appendClip(container, "visible", "0", "5");
+    hidden.dataset.clipHidden = "true";
+    const previous = new Set<string>();
+
+    updateTimelineActiveClipClasses(container, previous, 2);
+
+    expect(hidden.hasAttribute("data-active")).toBe(false);
+    expect(visible.hasAttribute("data-active")).toBe(true);
+    expect(previous).toEqual(new Set(["visible"]));
+  });
+
+  it("diffs against the previous active set", () => {
+    const container = document.createElement("div");
+    const intro = appendClip(container, "intro", "0", "2");
+    const hero = appendClip(container, "hero", "2", "5");
+    const previous = new Set(["intro"]);
+    intro.toggleAttribute("data-active", true);
+
+    updateTimelineActiveClipClasses(container, previous, 2);
+
+    expect(intro.hasAttribute("data-active")).toBe(true);
+    expect(hero.hasAttribute("data-active")).toBe(true);
+    expect(previous).toEqual(new Set(["intro", "hero"]));
+  });
+
+  it("keeps a clip active through its inclusive end boundary", () => {
+    const container = document.createElement("div");
+    const intro = appendClip(container, "intro", "0", "2");
+    const previous = new Set<string>();
+
+    updateTimelineActiveClipClasses(container, previous, 0);
+
+    expect(intro.hasAttribute("data-active")).toBe(true);
+    expect(previous).toEqual(new Set(["intro"]));
+
+    updateTimelineActiveClipClasses(container, previous, 2);
+
+    expect(intro.hasAttribute("data-active")).toBe(true);
+    expect(previous).toEqual(new Set(["intro"]));
+
+    updateTimelineActiveClipClasses(container, previous, 2.001);
+
+    expect(intro.hasAttribute("data-active")).toBe(false);
+    expect(previous).toEqual(new Set());
+  });
+
+  it("ignores clips with invalid timing data", () => {
+    const container = document.createElement("div");
+    const missingId = appendClip(container, "", "0", "2");
+    const missingTiming = appendClip(container, "bad", "", "2");
+    const previous = new Set<string>();
+
+    updateTimelineActiveClipClasses(container, previous, 1);
+
+    expect(missingId.hasAttribute("data-active")).toBe(false);
+    expect(missingTiming.hasAttribute("data-active")).toBe(false);
+    expect(previous).toEqual(new Set());
+  });
+});

package/src/player/components/useTimelineActiveClips.ts

@@ -0,0 +1,125 @@
+import { useCallback, useLayoutEffect, useRef } from "react";
+import { liveTime } from "../store/playerStore";
+import { useMountEffect } from "../../hooks/useMountEffect";
+
+interface ActiveClipRecord {
+  id: string;
+  start: number;
+  end: number;
+  hidden: boolean;
+  element: HTMLElement;
+}
+
+interface UseTimelineActiveClipsInput {
+  scrollRef: React.RefObject<HTMLDivElement | null>;
+  currentTime: number;
+  clipStateVersion: string;
+}
+
+function readFiniteNumber(value: string | undefined): number | null {
+  if (value === undefined || value.trim() === "") return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function readClipRecord(element: Element): ActiveClipRecord | null {
+  if (!(element instanceof HTMLElement)) return null;
+  const id = element.dataset.elId;
+  const start = readFiniteNumber(element.dataset.clipStart);
+  const end = readFiniteNumber(element.dataset.clipEnd);
+  const hidden = element.dataset.clipHidden === "true";
+  if (!id || start === null || end === null) return null;
+  return { id, start, end, hidden, element };
+}
+
+function collectTimelineClipRecords(container: HTMLElement): ActiveClipRecord[] {
+  const records: ActiveClipRecord[] = [];
+  for (const element of container.querySelectorAll('[data-clip="true"]')) {
+    const record = readClipRecord(element);
+    if (record) records.push(record);
+  }
+  return records;
+}
+
+function indexClipRecordsById(records: ActiveClipRecord[]): Map<string, ActiveClipRecord> {
+  const recordsById = new Map<string, ActiveClipRecord>();
+  for (const record of records) recordsById.set(record.id, record);
+  return recordsById;
+}
+
+function getActiveClipIds(records: ActiveClipRecord[], time: number): Set<string> {
+  const next = new Set<string>();
+  if (!Number.isFinite(time)) return next;
+  for (const record of records) {
+    if (record.hidden) continue;
+    if (time >= record.start && time <= record.end) next.add(record.id);
+  }
+  return next;
+}
+
+function setsMatch(left: Set<string>, right: Set<string>): boolean {
+  if (left.size !== right.size) return false;
+  for (const value of left) {
+    if (!right.has(value)) return false;
+  }
+  return true;
+}
+
+function applyActiveClipDiff(records: ActiveClipRecord[], previous: Set<string>, time: number) {
+  const next = getActiveClipIds(records, time);
+  const changed = !setsMatch(previous, next);
+  for (const record of records) {
+    const wasActive = previous.has(record.id);
+    const isActive = next.has(record.id);
+    if (wasActive === isActive) continue;
+    record.element.toggleAttribute("data-active", isActive);
+  }
+  previous.clear();
+  for (const id of next) previous.add(id);
+  return changed;
+}
+
+export function updateTimelineActiveClipClasses(
+  container: HTMLElement,
+  previous: Set<string>,
+  time: number,
+) {
+  applyActiveClipDiff(collectTimelineClipRecords(container), previous, time);
+}
+
+export function useTimelineActiveClips({
+  scrollRef,
+  currentTime,
+  clipStateVersion,
+}: UseTimelineActiveClipsInput) {
+  const recordsRef = useRef<ActiveClipRecord[]>([]);
+  const recordsByIdRef = useRef(new Map<string, ActiveClipRecord>());
+  const previousActiveIdsRef = useRef(new Set<string>());
+
+  const refreshRecords = useCallback(
+    (time: number) => {
+      const scroll = scrollRef.current;
+      if (!scroll) {
+        recordsRef.current = [];
+        recordsByIdRef.current.clear();
+        previousActiveIdsRef.current.clear();
+        return;
+      }
+      recordsRef.current = collectTimelineClipRecords(scroll);
+      recordsByIdRef.current = indexClipRecordsById(recordsRef.current);
+      applyActiveClipDiff(recordsRef.current, previousActiveIdsRef.current, time);
+    },
+    [scrollRef],
+  );
+
+  useLayoutEffect(() => {
+    refreshRecords(currentTime);
+  }, [currentTime, clipStateVersion, refreshRecords]);
+
+  useMountEffect(() => {
+    const unsub = liveTime.subscribe((time) => {
+      applyActiveClipDiff(recordsRef.current, previousActiveIdsRef.current, time);
+    });
+    return unsub;
+  });
+}

package/src/player/components/useTimelinePlayhead.ts

@@ -94,6 +94,12 @@ export function useTimelinePlayhead({
     syncPlayheadPosition(currentTime);
   }, [currentTime, pps, syncPlayheadPosition]);
 
+  useLayoutEffect(() => {
+    const scroll = scrollRef.current;
+    if (!scroll || zoomMode !== "fit") return;
+    scroll.scrollLeft = 0;
+  }, [zoomMode, pps, scrollRef]);
+
   useEffect(() => {
     const scroll = scrollRef.current;
     if (!scroll) {

package/src/player/hooks/useExpandedTimelineElements.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from "vitest";
-import { buildExpandedElements } from "./useExpandedTimelineElements";
+import {
+  buildExpandedElements,
+  resolveTimelineExpansionRawId,
+} from "./useExpandedTimelineElements";
 import { buildTimelineElementKey } from "../lib/timelineElementHelpers";
 import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "../lib/playbackTypes";
@@ -19,8 +22,14 @@ const clip = (over: Partial<ClipManifestClip>): ClipManifestClip => ({
   ...over,
 });
 
-const el = (over: Partial<TimelineElement>): TimelineElement =>
-  ({ id: "x", start: 0, duration: 1, track: 0, tag: "div", ...over }) as TimelineElement;
+const el = (over: Partial<TimelineElement>): TimelineElement => ({
+  id: "x",
+  start: 0,
+  duration: 1,
+  track: 0,
+  tag: "div",
+  ...over,
+});
 
 describe("buildExpandedElements", () => {
   it("rebases a 1-level child onto its sub-comp host (start + sourceFile)", () => {
@@ -42,6 +51,7 @@ describe("buildExpandedElements", () => {
     expect(child.sourceFile).toBe("stats.html");
   });
 
+  // fallow-ignore-next-line code-duplication
   it("rebases a 2-level child onto its NESTED host, not the top-level scene", () => {
     // top host A@10 (a.html) embeds host B@12 (b.html); child C lives in b.html.
     // Edits must rebase onto B (12 / b.html), not A (10 / a.html).
@@ -65,6 +75,7 @@ describe("buildExpandedElements", () => {
     expect(child.sourceFile).toBe("b.html"); // B's file, not a.html
   });
 
+  // fallow-ignore-next-line code-duplication
   it("rebases a 3-level child onto its deepest host, not intermediate or top", () => {
     // A@10 (a.html) → B@12 (b.html) → C@13 (c.html); leaf D lives in c.html.
     // Edits must rebase onto C (13 / c.html), not B (12 / b.html) or A (10 / a.html).
@@ -166,3 +177,99 @@ describe("buildExpandedElements", () => {
     expect(out.some((e) => e.domId === "scene-host")).toBe(false);
   });
 });
+
+describe("resolveTimelineExpansionRawId", () => {
+  it("returns null when paused inside a childless top-level clip", () => {
+    const manifest = [clip({ id: "title", start: 0, duration: 4 })];
+
+    expect(
+      resolveTimelineExpansionRawId({
+        selectedElementId: null,
+        isPlaying: false,
+        currentTime: 2,
+        manifest,
+        parentMap: new Map(),
+      }),
+    ).toBeNull();
+  });
+
+  it("auto-expands an active composition with children when paused and nothing is selected", () => {
+    const manifest = [
+      clip({ id: "scene", start: 1, duration: 5 }),
+      clip({ id: "headline", start: 1.5, duration: 2 }),
+    ];
+    const parentMap = new Map([["headline", "scene"]]);
+
+    expect(
+      resolveTimelineExpansionRawId({
+        selectedElementId: null,
+        isPlaying: false,
+        currentTime: 2,
+        manifest,
+        parentMap,
+      }),
+    ).toBe("scene");
+  });
+
+  it("auto-expands the innermost active nested composition when paused", () => {
+    const manifest = [
+      clip({ id: "outer", start: 0, duration: 10 }),
+      clip({ id: "inner", start: 2, duration: 5 }),
+      clip({ id: "leaf", start: 3, duration: 1 }),
+    ];
+    const parentMap = new Map([
+      ["inner", "outer"],
+      ["leaf", "inner"],
+    ]);
+
+    expect(
+      resolveTimelineExpansionRawId({
+        selectedElementId: null,
+        isPlaying: false,
+        currentTime: 3.5,
+        manifest,
+        parentMap,
+      }),
+    ).toBe("inner");
+  });
+
+  it("does not auto-expand an active composition while playing", () => {
+    const manifest = [
+      clip({ id: "scene", start: 0, duration: 5 }),
+      clip({ id: "headline", start: 1, duration: 2 }),
+    ];
+    const parentMap = new Map([["headline", "scene"]]);
+
+    expect(
+      resolveTimelineExpansionRawId({
+        selectedElementId: null,
+        isPlaying: true,
+        currentTime: 2,
+        manifest,
+        parentMap,
+      }),
+    ).toBeNull();
+  });
+
+  it("keeps selected elements ahead of paused active composition auto-expansion", () => {
+    const manifest = [
+      clip({ id: "scene", start: 0, duration: 6 }),
+      clip({ id: "headline", start: 1, duration: 2 }),
+      clip({ id: "caption", start: 4, duration: 1 }),
+    ];
+    const parentMap = new Map([
+      ["headline", "scene"],
+      ["caption", "scene"],
+    ]);
+
+    expect(
+      resolveTimelineExpansionRawId({
+        selectedElementId: "caption",
+        isPlaying: false,
+        currentTime: 1.5,
+        manifest,
+        parentMap,
+      }),
+    ).toBe("caption");
+  });
+});