@hyperframes/studio 0.5.0-alpha.8 → 0.5.0

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { formatTime } from "./time";
+import { formatFrameTime, frameToSeconds, secondsToFrame, stepFrameTime, formatTime } from "./time";
 
 describe("formatTime", () => {
   it("formats zero seconds", () => {
@@ -55,3 +55,31 @@ describe("formatTime", () => {
     expect(formatTime(Infinity)).toBe("0:00");
   });
 });
+
+describe("frame helpers", () => {
+  it("converts seconds to frames at the Studio preview rate", () => {
+    expect(secondsToFrame(0)).toBe(0);
+    expect(secondsToFrame(1)).toBe(30);
+    expect(secondsToFrame(1.5)).toBe(45);
+  });
+
+  it("converts frames to seconds at the Studio preview rate", () => {
+    expect(frameToSeconds(0)).toBe(0);
+    expect(frameToSeconds(30)).toBe(1);
+    expect(frameToSeconds(45)).toBe(1.5);
+  });
+
+  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

@@ -1,6 +1,32 @@
+export const STUDIO_PREVIEW_FPS = 30;
+
 export function formatTime(time: number): string {
   if (!Number.isFinite(time) || time < 0) return "0:00";
   const mins = Math.floor(time / 60);
   const secs = Math.floor(time % 60);
   return `${mins}:${secs.toString().padStart(2, "0")}`;
 }
+
+export function secondsToFrame(time: number, fps = STUDIO_PREVIEW_FPS): number {
+  if (!Number.isFinite(time) || time <= 0) return 0;
+  if (!Number.isFinite(fps) || fps <= 0) return 0;
+  return Math.round(time * fps);
+}
+
+export function frameToSeconds(frame: number, fps = STUDIO_PREVIEW_FPS): number {
+  if (!Number.isFinite(frame) || frame <= 0) return 0;
+  if (!Number.isFinite(fps) || fps <= 0) return 0;
+  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);
+  return `${currentFrame}f / ${totalFrames}f`;
+}

package/src/player/store/playerStore.test.ts

@@ -16,6 +16,7 @@ describe("usePlayerStore", () => {
       expect(state.elements).toEqual([]);
       expect(state.selectedElementId).toBeNull();
       expect(state.playbackRate).toBe(1);
+      expect(state.loopEnabled).toBe(false);
       expect(state.zoomMode).toBe("fit");
       expect(state.manualZoomPercent).toBe(100);
     });
@@ -61,6 +62,13 @@ describe("usePlayerStore", () => {
     });
   });
 
+  describe("setLoopEnabled", () => {
+    it("updates loopEnabled", () => {
+      usePlayerStore.getState().setLoopEnabled(true);
+      expect(usePlayerStore.getState().loopEnabled).toBe(true);
+    });
+  });
+
   describe("setTimelineReady", () => {
     it("updates timelineReady", () => {
       usePlayerStore.getState().setTimelineReady(true);
@@ -205,9 +213,10 @@ describe("usePlayerStore", () => {
       expect(state.selectedElementId).toBeNull();
     });
 
-    it("does not reset playbackRate, zoomMode, or manualZoomPercent", () => {
+    it("does not reset playbackRate, loopEnabled, zoomMode, or manualZoomPercent", () => {
       const store = usePlayerStore.getState();
       store.setPlaybackRate(2);
+      store.setLoopEnabled(true);
       store.setZoomMode("manual");
       store.setManualZoomPercent(200);
 
@@ -216,6 +225,7 @@ describe("usePlayerStore", () => {
       const state = usePlayerStore.getState();
       // reset() only resets the fields explicitly listed in the reset function
       expect(state.playbackRate).toBe(2);
+      expect(state.loopEnabled).toBe(true);
       expect(state.zoomMode).toBe("manual");
       expect(state.manualZoomPercent).toBe(200);
     });

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;
@@ -34,6 +35,7 @@ interface PlayerState {
   elements: TimelineElement[];
   selectedElementId: string | null;
   playbackRate: number;
+  loopEnabled: boolean;
   /** Timeline zoom: 'fit' auto-scales to viewport, 'manual' uses manualZoomPercent */
   zoomMode: ZoomMode;
   /** Timeline zoom percent relative to the fit width when in manual mode */
@@ -43,6 +45,7 @@ interface PlayerState {
   setCurrentTime: (time: number) => void;
   setDuration: (duration: number) => void;
   setPlaybackRate: (rate: number) => void;
+  setLoopEnabled: (enabled: boolean) => void;
   setTimelineReady: (ready: boolean) => void;
   setElements: (elements: TimelineElement[]) => void;
   setSelectedElementId: (id: string | null) => void;
@@ -76,11 +79,13 @@ export const usePlayerStore = create<PlayerState>((set) => ({
   elements: [],
   selectedElementId: null,
   playbackRate: 1,
+  loopEnabled: false,
   zoomMode: "fit",
   manualZoomPercent: 100,
 
   setIsPlaying: (playing) => set({ isPlaying: playing }),
   setPlaybackRate: (rate) => set({ playbackRate: rate }),
+  setLoopEnabled: (enabled) => set({ loopEnabled: enabled }),
   setZoomMode: (mode) => set({ zoomMode: mode }),
   setManualZoomPercent: (percent) =>
     set({ manualZoomPercent: Math.max(10, Math.min(2000, Math.round(percent))) }),
@@ -96,7 +101,7 @@ export const usePlayerStore = create<PlayerState>((set) => ({
       ),
     })),
   // Resets project-specific state when switching compositions.
-  // playbackRate, zoomMode, and manualZoomPercent are intentionally preserved
+  // playbackRate, loopEnabled, zoomMode, and manualZoomPercent are intentionally preserved
   // because they are user preferences that should survive project switches.
   reset: () =>
     set({

package/src/styles/studio.css

@@ -49,3 +49,115 @@ body {
 .cm-editor.cm-focused {
   outline: none;
 }
+
+/*
+ * HyperFrames brand loader. Shared by preview overlays that need a calm,
+ * branded loading state instead of a generic spinner.
+ */
+.hf-loader {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.75rem;
+  width: min(34rem, 100%);
+  padding: 1.5rem;
+  box-sizing: border-box;
+  text-align: center;
+  cursor: default;
+  user-select: none;
+  -webkit-user-select: none;
+  -webkit-user-drag: none;
+}
+
+.hf-frame {
+  display: grid;
+  place-items: center;
+  width: 100%;
+  height: 100%;
+  min-height: 12rem;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  background: rgba(0, 0, 0, 0.52);
+}
+
+.hf-loader-mark-frame {
+  display: grid;
+  place-items: center;
+  overflow: visible;
+  transform-origin: 50% 50%;
+  user-select: none;
+  -webkit-user-select: none;
+  -webkit-user-drag: none;
+}
+
+.hf-loader-mark {
+  display: block;
+  overflow: visible;
+  filter: drop-shadow(0 0 7px rgba(79, 219, 94, 0.2));
+  user-select: none;
+  -webkit-user-select: none;
+  -webkit-user-drag: none;
+}
+
+.hf-loader-title {
+  font-family:
+    Inter,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
+  font-size: 1rem;
+  font-weight: 600;
+  letter-spacing: 0;
+  color: var(--hf-heading, #f4f4f5);
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hf-loader-detail {
+  max-width: 32rem;
+  min-height: 2.5rem;
+  overflow: hidden;
+  color: var(--hf-text-secondary, rgba(244, 244, 245, 0.68));
+  font-family:
+    Inter,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
+  font-size: 0.82rem;
+  line-height: 1.6;
+}
+
+.hf-loader-mono {
+  width: min(36rem, 100%);
+  min-height: 1.5rem;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--hf-text-tertiary, rgba(244, 244, 245, 0.46));
+  font-family: "IBM Plex Mono", "SF Mono", "Fira Code", monospace;
+  font-size: 0.75rem;
+  letter-spacing: 0;
+  font-variant-numeric: tabular-nums;
+}
+
+.hf-loader-progress {
+  width: min(18rem, 72vw);
+  height: 0.375rem;
+  overflow: hidden;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.1);
+}
+
+.hf-loader-progress__fill {
+  width: 100%;
+  height: 100%;
+  transform: scaleX(0);
+  transform-origin: left center;
+  border-radius: inherit;
+  background: linear-gradient(90deg, #06e3fa, #4fdb5e);
+  transition: transform 160ms ease;
+}

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,40 @@
+import { buildProjectApiPath } from "./projectRouting";
+
+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(
+    buildProjectApiPath(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`;
+}

package/src/utils/mediaTypes.ts

@@ -1,7 +1,7 @@
 export const IMAGE_EXT = /\.(jpg|jpeg|png|gif|webp|svg|ico)$/i;
 export const VIDEO_EXT = /\.(mp4|webm|mov)$/i;
 export const AUDIO_EXT = /\.(mp3|wav|ogg|m4a|aac)$/i;
-export const FONT_EXT = /\.(woff|woff2|ttf|ttc|otf|eot)$/i;
+export const FONT_EXT = /\.(woff|woff2|ttf|otf|eot)$/i;
 export const MEDIA_EXT = /\.(mp4|webm|mov|mp3|wav|ogg|m4a|aac|jpg|jpeg|png|gif|webp|svg|ico)$/i;
 
 export function isMediaFile(path: string): boolean {

package/src/utils/projectRouting.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildFrameCaptureUrl } from "./frameCapture";
+import {
+  buildProjectApiPath,
+  buildProjectHash,
+  encodeProjectId,
+  parseProjectIdFromHash,
+} from "./projectRouting";
+
+describe("project routing utilities", () => {
+  it("decodes project ids from hash routes before building capture URLs", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-05-01T12:00:00Z"));
+
+    const projectId = parseProjectIdFromHash("#project/Notion%20Showcase");
+
+    expect(projectId).toBe("Notion Showcase");
+    expect(
+      buildFrameCaptureUrl({
+        projectId: projectId ?? "",
+        compositionPath: null,
+        currentTime: 1.809,
+        origin: "http://localhost:3002",
+      }),
+    ).toBe(
+      "http://localhost:3002/api/projects/Notion%20Showcase/thumbnail/index.html?t=1.809&format=png&v=1777636800000",
+    );
+
+    vi.useRealTimers();
+  });
+
+  it("accepts legacy raw-space hash routes", () => {
+    expect(parseProjectIdFromHash("#project/Notion Showcase")).toBe("Notion Showcase");
+  });
+
+  it("decodes reserved characters when the hash route is encoded", () => {
+    expect(parseProjectIdFromHash("#project/Launch%20%231%3F%20v2")).toBe("Launch #1? v2");
+  });
+
+  it("does not throw on malformed percent escapes in hash routes", () => {
+    expect(parseProjectIdFromHash("#project/Broken%ZZName")).toBe("Broken%ZZName");
+  });
+
+  it("ignores non-project hash routes", () => {
+    expect(parseProjectIdFromHash("")).toBeNull();
+    expect(parseProjectIdFromHash("#settings")).toBeNull();
+    expect(parseProjectIdFromHash("#project/")).toBeNull();
+    expect(parseProjectIdFromHash("#project/foo/bar")).toBeNull();
+  });
+
+  it("encodes project ids when writing hash routes", () => {
+    expect(buildProjectHash("Notion Showcase")).toBe("#project/Notion%20Showcase");
+    expect(buildProjectHash("Notion%20Showcase")).toBe("#project/Notion%2520Showcase");
+    expect(buildProjectHash("Launch #1? v2")).toBe("#project/Launch%20%231%3F%20v2");
+  });
+
+  it("round-trips unicode project ids through hash routes", () => {
+    const hash = buildProjectHash("Mañana demo");
+
+    expect(hash).toBe("#project/Ma%C3%B1ana%20demo");
+    expect(parseProjectIdFromHash(hash)).toBe("Mañana demo");
+  });
+
+  it("encodes project ids as one API path segment", () => {
+    expect(encodeProjectId("Notion Showcase")).toBe("Notion%20Showcase");
+    expect(encodeProjectId("Notion%20Showcase")).toBe("Notion%2520Showcase");
+    expect(encodeProjectId("Launch #1? v2")).toBe("Launch%20%231%3F%20v2");
+  });
+
+  it("builds API paths without double encoding decoded project ids", () => {
+    expect(buildProjectApiPath("Notion Showcase", "/thumbnail/index.html")).toBe(
+      "/api/projects/Notion%20Showcase/thumbnail/index.html",
+    );
+  });
+
+  it("keeps literal percent signs safe in API paths", () => {
+    expect(buildProjectApiPath("Percent%20Name", "/preview")).toBe(
+      "/api/projects/Percent%2520Name/preview",
+    );
+  });
+
+  it("keeps unicode project ids safe in API paths", () => {
+    expect(buildProjectApiPath("Mañana demo", "/preview")).toBe(
+      "/api/projects/Ma%C3%B1ana%20demo/preview",
+    );
+  });
+});

package/src/utils/projectRouting.ts

@@ -0,0 +1,27 @@
+const PROJECT_HASH_PREFIX = "#project/";
+
+export function encodeProjectId(projectId: string): string {
+  return encodeURIComponent(projectId);
+}
+
+export function buildProjectHash(projectId: string): string {
+  return `${PROJECT_HASH_PREFIX}${encodeProjectId(projectId)}`;
+}
+
+export function parseProjectIdFromHash(hash: string): string | null {
+  if (!hash.startsWith(PROJECT_HASH_PREFIX)) return null;
+
+  const encodedProjectId = hash.slice(PROJECT_HASH_PREFIX.length);
+  if (!encodedProjectId || encodedProjectId.includes("/")) return null;
+
+  try {
+    return decodeURIComponent(encodedProjectId);
+  } catch {
+    return encodedProjectId;
+  }
+}
+
+export function buildProjectApiPath(projectId: string, suffix = ""): string {
+  const normalizedSuffix = suffix && !suffix.startsWith("/") ? `/${suffix}` : suffix;
+  return `/api/projects/${encodeProjectId(projectId)}${normalizedSuffix}`;
+}

package/src/utils/sourcePatcher.test.ts

@@ -1,11 +1,5 @@
 import { describe, expect, it } from "vitest";
-import {
-  applyPatch,
-  applyPatchByTarget,
-  readAttributeByTarget,
-  readTagSnippetByTarget,
-  type PatchOperation,
-} from "./sourcePatcher";
+import { applyPatchByTarget, readAttributeByTarget, type PatchOperation } from "./sourcePatcher";
 
 describe("applyPatchByTarget", () => {
   it("updates a composition host by data-composition-id selector", () => {
@@ -35,64 +29,6 @@ describe("applyPatchByTarget", () => {
     );
   });
 
-  it("patches inline move styles by target", () => {
-    const html = `<div id="card" style="position: absolute; left: 108px; top: 112px"></div>`;
-
-    const withLeft = applyPatchByTarget(
-      html,
-      { id: "card" },
-      { type: "inline-style", property: "left", value: "160px" },
-    );
-    const withTop = applyPatchByTarget(
-      withLeft,
-      { id: "card" },
-      { type: "inline-style", property: "top", value: "140px" },
-    );
-
-    expect(withTop).toContain('style="position: absolute; left: 160px; top: 140px"');
-  });
-
-  it("patches inline resize styles by target", () => {
-    const html = `<div id="card" style="position: absolute; width: 380px; height: 196px"></div>`;
-
-    const withWidth = applyPatchByTarget(
-      html,
-      { id: "card" },
-      { type: "inline-style", property: "width", value: "420px" },
-    );
-    const withHeight = applyPatchByTarget(
-      withWidth,
-      { id: "card" },
-      { type: "inline-style", property: "height", value: "220px" },
-    );
-
-    expect(withHeight).toContain('style="position: absolute; width: 420px; height: 220px"');
-  });
-
-  it("escapes quoted CSS urls inside double-quoted style attributes", () => {
-    const html = `<div id="card" style="position: absolute; opacity: 1"></div>`;
-
-    const withBackground = applyPatchByTarget(
-      html,
-      { id: "card" },
-      {
-        type: "inline-style",
-        property: "background-image",
-        value: `url("../ChatGPT Image Apr 22, 2026.png")`,
-      },
-    );
-    const withRadius = applyPatchByTarget(
-      withBackground,
-      { id: "card" },
-      { type: "inline-style", property: "border-radius", value: "12px" },
-    );
-
-    expect(withRadius).toContain(
-      "background-image: url(&quot;../ChatGPT Image Apr 22, 2026.png&quot;)",
-    );
-    expect(withRadius).toContain("border-radius: 12px");
-  });
-
   it("updates media timing attributes by selector", () => {
     const html = `<video class="hero clip" data-start="0.2" data-duration="1.4" data-media-start="0.4"></video>`;
 
@@ -126,69 +62,6 @@ describe("applyPatchByTarget", () => {
     expect(readAttributeByTarget(html, { selector: ".hero" }, "duration")).toBe("1.4");
   });
 
-  it("reads the matched tag snippet by target", () => {
-    const html = `<section id="hero" class="card clip" style="left: 120px; top: 180px"></section>`;
-
-    expect(readTagSnippetByTarget(html, { id: "hero" })).toBe(
-      `<section id="hero" class="card clip" style="left: 120px; top: 180px"`,
-    );
-  });
-
-  it("patches and reads single-quoted attributes and styles", () => {
-    const html =
-      "<section id='hero' class='card clip' data-start='0.2' style='left: 120px; top: 180px'></section>";
-
-    const moved = applyPatchByTarget(
-      html,
-      { id: "hero" },
-      { type: "inline-style", property: "left", value: "160px" },
-    );
-    const updated = applyPatchByTarget(
-      moved,
-      { id: "hero" },
-      { type: "attribute", property: "start", value: "0.4" },
-    );
-
-    expect(updated).toContain(`style='left: 160px; top: 180px'`);
-    expect(updated).toContain(`data-start="0.4"`);
-    expect(readAttributeByTarget(updated, { id: "hero" }, "start")).toBe("0.4");
-  });
-
-  it("replaces the full text body of a nested element by id", () => {
-    const html =
-      '<div id="panel"><strong>Headline</strong><span>Supporting copy</span></div><p>Outside</p>';
-
-    const patched = applyPatch(html, "panel", {
-      type: "text-content",
-      property: "text",
-      value: "<strong>New headline</strong><span>New supporting copy</span>",
-    });
-
-    expect(patched).toContain(
-      '<div id="panel"><strong>New headline</strong><span>New supporting copy</span></div>',
-    );
-    expect(patched).toContain("<p>Outside</p>");
-  });
-
-  it("does not stop at the first child closing tag when patching nested text", () => {
-    const html =
-      '<section id="card"><div><strong>Headline</strong></div><div>Copy</div></section><p>Outside</p>';
-
-    const patched = applyPatchByTarget(
-      html,
-      { id: "card" },
-      {
-        type: "text-content",
-        property: "text",
-        value: "<strong>New headline</strong>",
-      },
-    );
-
-    expect(patched).toBe(
-      '<section id="card"><strong>New headline</strong></section><p>Outside</p>',
-    );
-  });
-
   it("patches the correct duplicate selector occurrence", () => {
     const html = [
       `<div class="headline clip" data-start="0"></div>`,