@hyperframes/studio 0.4.37 → 0.4.39

package/src/player/lib/time.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { formatFrameTime, frameToSeconds, secondsToFrame, formatTime } from "./time";
+import { formatFrameTime, frameToSeconds, secondsToFrame, stepFrameTime, formatTime } from "./time";
 
 describe("formatTime", () => {
   it("formats zero seconds", () => {
@@ -72,4 +72,14 @@ describe("frame helpers", () => {
   it("formats current and total frame display", () => {
     expect(formatFrameTime(1, 5)).toBe("30f / 150f");
   });
+
+  it("steps from a truncated runtime time by integer frame index", () => {
+    expect(stepFrameTime(0.0333333, 1)).toBe(2 / 30);
+    expect(stepFrameTime(0.0666666, 1)).toBe(3 / 30);
+    expect(stepFrameTime(0.0666666, -1)).toBe(1 / 30);
+  });
+
+  it("clamps frame stepping at zero", () => {
+    expect(stepFrameTime(0, -1)).toBe(0);
+  });
 });

package/src/player/lib/time.ts

@@ -19,6 +19,12 @@ export function frameToSeconds(frame: number, fps = STUDIO_PREVIEW_FPS): number
   return frame / fps;
 }
 
+export function stepFrameTime(time: number, deltaFrames: number, fps = STUDIO_PREVIEW_FPS): number {
+  const currentFrame = secondsToFrame(time, fps);
+  const nextFrame = Math.max(0, currentFrame + deltaFrames);
+  return frameToSeconds(nextFrame, fps);
+}
+
 export function formatFrameTime(time: number, duration: number, fps = STUDIO_PREVIEW_FPS): string {
   const currentFrame = secondsToFrame(time, fps);
   const totalFrames = secondsToFrame(duration, fps);

package/src/player/store/playerStore.ts

@@ -2,6 +2,7 @@ import { create } from "zustand";
 
 export interface TimelineElement {
   id: string;
+  label?: string;
   key?: string;
   tag: string;
   start: number;

package/src/utils/frameCapture.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildFrameCaptureFilename, buildFrameCaptureUrl } from "./frameCapture";
+
+describe("frame capture utilities", () => {
+  it("builds a PNG capture URL for the master composition", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-04-29T12:00:00Z"));
+
+    expect(
+      buildFrameCaptureUrl({
+        projectId: "demo project",
+        compositionPath: null,
+        currentTime: 1.23456,
+        origin: "http://localhost:5194",
+      }),
+    ).toBe(
+      "http://localhost:5194/api/projects/demo%20project/thumbnail/index.html?t=1.235&format=png&v=1777464000000",
+    );
+
+    vi.useRealTimers();
+  });
+
+  it("builds a safe filename from a nested composition path", () => {
+    expect(buildFrameCaptureFilename("compositions/intro.html", 2.5)).toBe("intro-2-500s.png");
+  });
+});

package/src/utils/frameCapture.ts

@@ -0,0 +1,38 @@
+export interface FrameCaptureRequest {
+  projectId: string;
+  compositionPath: string | null;
+  currentTime: number;
+  origin?: string;
+}
+
+function normalizeCompositionPath(compositionPath: string | null): string {
+  return compositionPath && compositionPath !== "master" ? compositionPath : "index.html";
+}
+
+export function buildFrameCaptureUrl({
+  projectId,
+  compositionPath,
+  currentTime,
+  origin = window.location.origin,
+}: FrameCaptureRequest): string {
+  const compPath = normalizeCompositionPath(compositionPath);
+  const url = new URL(
+    `/api/projects/${encodeURIComponent(projectId)}/thumbnail/${encodeURIComponent(compPath)}`,
+    origin,
+  );
+  url.searchParams.set("t", Math.max(0, currentTime).toFixed(3));
+  url.searchParams.set("format", "png");
+  url.searchParams.set("v", String(Date.now()));
+  return url.toString();
+}
+
+export function buildFrameCaptureFilename(compositionPath: string | null, currentTime: number) {
+  const compPath = normalizeCompositionPath(compositionPath);
+  const base =
+    compPath
+      .split("/")
+      .pop()
+      ?.replace(/\.html$/i, "") || "frame";
+  const frameTime = Math.max(0, currentTime).toFixed(3).replace(".", "-");
+  return `${base}-${frameTime}s.png`;
+}