@hyperframes/studio 0.6.112 → 0.6.114

package/src/components/panels/slideshowPanelHelpers.ts

@@ -0,0 +1,232 @@
+/**
+ * Pure manifest-transform helpers for SlideshowPanel.
+ * No React, no side-effects — fully unit-testable.
+ */
+
+import type { SlideshowManifest, SlideRef, SlideHotspot } from "@hyperframes/core/slideshow";
+
+// ── Scene shape used by the panel UI ──────────────────────────────────────
+
+export interface SceneInfo {
+  id: string;
+  label: string;
+  start: number;
+  duration: number;
+}
+
+// ── Pure manifest transforms ───────────────────────────────────────────────
+
+/** Toggle a scene in the main-line slide list. */
+export function toggleMainLineSlide(
+  manifest: SlideshowManifest,
+  sceneId: string,
+): SlideshowManifest {
+  const exists = manifest.slides.some((s) => s.sceneId === sceneId);
+  const slides: SlideRef[] = exists
+    ? manifest.slides.filter((s) => s.sceneId !== sceneId)
+    : [...manifest.slides, { sceneId }];
+  return { ...manifest, slides };
+}
+
+// fallow-ignore-next-line complexity
+/** Move a main-line slide up or down by one position. */
+/** Swap the slide with `sceneId` one step up/down within a slide list. */
+function swapSlide(slides: SlideRef[], sceneId: string, direction: "up" | "down"): SlideRef[] {
+  const idx = slides.findIndex((s) => s.sceneId === sceneId);
+  if (idx === -1) return slides;
+  const next = direction === "up" ? idx - 1 : idx + 1;
+  if (next < 0 || next >= slides.length) return slides;
+  const out = [...slides];
+  const a = out[idx];
+  const b = out[next];
+  if (!a || !b) return slides;
+  out[idx] = b;
+  out[next] = a;
+  return out;
+}
+
+export function reorderMainLineSlide(
+  manifest: SlideshowManifest,
+  sceneId: string,
+  direction: "up" | "down",
+): SlideshowManifest {
+  return mapSlidesIn(manifest, undefined, (slides) => swapSlide(slides, sceneId, direction));
+}
+
+/** Reorder a slide within a branch sequence (parallel to reorderMainLineSlide). */
+export function reorderBranchSlide(
+  manifest: SlideshowManifest,
+  sequenceId: string,
+  sceneId: string,
+  direction: "up" | "down",
+): SlideshowManifest {
+  return mapSlidesIn(manifest, sequenceId, (slides) => swapSlide(slides, sceneId, direction));
+}
+
+/** Apply fn to a branch's slide list (sequenceId) or the main line (undefined). */
+function mapSlidesIn(
+  manifest: SlideshowManifest,
+  sequenceId: string | undefined,
+  fn: (slides: SlideRef[]) => SlideRef[],
+): SlideshowManifest {
+  if (sequenceId === undefined) {
+    return { ...manifest, slides: fn(manifest.slides) };
+  }
+  return {
+    ...manifest,
+    slideSequences: (manifest.slideSequences ?? []).map((seq) =>
+      seq.id === sequenceId ? { ...seq, slides: fn(seq.slides) } : seq,
+    ),
+  };
+}
+
+/** Update notes on a main-line slide (adds slide entry if absent). */
+export function setSlideNotes(
+  manifest: SlideshowManifest,
+  sceneId: string,
+  notes: string,
+  sequenceId?: string,
+): SlideshowManifest {
+  return mapSlidesIn(manifest, sequenceId, (slides) => {
+    const exists = slides.some((s) => s.sceneId === sceneId);
+    if (exists) return slides.map((s) => (s.sceneId === sceneId ? { ...s, notes } : s));
+    return sequenceId === undefined ? [...slides, { sceneId, notes }] : slides;
+  });
+}
+
+/** Push a fragment hold-point time onto a main-line slide. Deduplicates + sorts. */
+export function addFragment(
+  manifest: SlideshowManifest,
+  sceneId: string,
+  time: number,
+  sequenceId?: string,
+): SlideshowManifest {
+  return mapSlidesIn(manifest, sequenceId, (slides) => {
+    const exists = slides.some((s) => s.sceneId === sceneId);
+    if (exists)
+      return slides.map((s) => {
+        if (s.sceneId !== sceneId) return s;
+        const frags = [...new Set([...(s.fragments ?? []), time])].sort((a, b) => a - b);
+        return { ...s, fragments: frags };
+      });
+    return sequenceId === undefined ? [...slides, { sceneId, fragments: [time] }] : slides;
+  });
+}
+
+/** Remove a fragment hold-point by value from a main-line slide. */
+export function removeFragment(
+  manifest: SlideshowManifest,
+  sceneId: string,
+  time: number,
+  sequenceId?: string,
+): SlideshowManifest {
+  return mapSlidesIn(manifest, sequenceId, (slides) =>
+    slides.map((s) =>
+      s.sceneId === sceneId
+        ? { ...s, fragments: (s.fragments ?? []).filter((f) => f !== time) }
+        : s,
+    ),
+  );
+}
+
+/** Create a new branch sequence. Rejects duplicate ids. */
+export function createSequence(
+  manifest: SlideshowManifest,
+  id: string,
+  label: string,
+): SlideshowManifest {
+  const existing = manifest.slideSequences ?? [];
+  if (existing.some((seq) => seq.id === id)) return manifest;
+  return {
+    ...manifest,
+    slideSequences: [...existing, { id, label, slides: [] }],
+  };
+}
+
+/** Rename an existing branch sequence label. */
+export function renameSequence(
+  manifest: SlideshowManifest,
+  id: string,
+  label: string,
+): SlideshowManifest {
+  return {
+    ...manifest,
+    slideSequences: (manifest.slideSequences ?? []).map((seq) =>
+      seq.id === id ? { ...seq, label } : seq,
+    ),
+  };
+}
+
+function pruneHotspots(slides: SlideRef[], targetId: string): SlideRef[] {
+  return slides.map((s) => {
+    if (!s.hotspots) return s;
+    const hotspots = s.hotspots.filter((h) => h.target !== targetId);
+    return hotspots.length === s.hotspots.length ? s : { ...s, hotspots };
+  });
+}
+
+/** Delete a branch sequence by id, removing any hotspot targeting it. */
+export function deleteSequence(manifest: SlideshowManifest, id: string): SlideshowManifest {
+  const remainingSequences = (manifest.slideSequences ?? []).filter((seq) => seq.id !== id);
+  return {
+    ...manifest,
+    slides: pruneHotspots(manifest.slides, id),
+    slideSequences: remainingSequences.map((seq) => ({
+      ...seq,
+      slides: pruneHotspots(seq.slides, id),
+    })),
+  };
+}
+
+/** Add or remove a scene slide from a branch sequence. */
+export function assignToBranch(
+  manifest: SlideshowManifest,
+  sequenceId: string,
+  sceneId: string,
+  assign: boolean,
+): SlideshowManifest {
+  return {
+    ...manifest,
+    slideSequences: (manifest.slideSequences ?? []).map((seq) => {
+      if (seq.id !== sequenceId) return seq;
+      if (assign) {
+        if (seq.slides.some((s) => s.sceneId === sceneId)) return seq;
+        return { ...seq, slides: [...seq.slides, { sceneId }] };
+      }
+      return { ...seq, slides: seq.slides.filter((s) => s.sceneId !== sceneId) };
+    }),
+  };
+}
+
+/** Add a hotspot to a main-line slide. */
+export function addHotspot(
+  manifest: SlideshowManifest,
+  sceneId: string,
+  hotspot: SlideHotspot,
+  sequenceId?: string,
+): SlideshowManifest {
+  return mapSlidesIn(manifest, sequenceId, (slides) =>
+    slides.map((s) => {
+      if (s.sceneId !== sceneId) return s;
+      const existing = s.hotspots ?? [];
+      if (existing.some((h) => h.id === hotspot.id)) return s;
+      return { ...s, hotspots: [...existing, hotspot] };
+    }),
+  );
+}
+
+/** Remove a hotspot by id from a main-line slide. */
+export function removeHotspot(
+  manifest: SlideshowManifest,
+  sceneId: string,
+  hotspotId: string,
+  sequenceId?: string,
+): SlideshowManifest {
+  return mapSlidesIn(manifest, sequenceId, (slides) =>
+    slides.map((s) =>
+      s.sceneId === sceneId
+        ? { ...s, hotspots: (s.hotspots ?? []).filter((h) => h.id !== hotspotId) }
+        : s,
+    ),
+  );
+}

package/src/hooks/useGsapAnimationOps.ts

@@ -5,6 +5,8 @@ import { roundTo3 } from "../utils/rounding";
 import {
   sdkGsapTweenPersist,
   sdkGsapDeleteAllForSelectorPersist,
+  sdkAddWithKeyframesPersist,
+  sdkReplaceWithKeyframesPersist,
   type CutoverDeps,
 } from "../utils/sdkCutover";
 import {
@@ -181,10 +183,104 @@ export function useGsapAnimationOps({
     [activeCompPath, commitMutation, projectIdRef, showToast, sdkSession, sdkDeps],
   );
 
+  type KeyframeEntry = {
+    percentage: number;
+    properties: Record<string, number | string>;
+    ease?: string;
+    auto?: boolean;
+  };
+
+  const addWithKeyframes = useCallback(
+    async (
+      selection: DomEditSelection,
+      targetSelector: string,
+      position: number,
+      duration: number,
+      keyframes: KeyframeEntry[],
+      ease?: string,
+      label = "Add animation with keyframes",
+    ) => {
+      if (sdkSession && sdkDeps) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkAddWithKeyframesPersist(
+          targetPath,
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ease,
+          sdkSession,
+          sdkDeps,
+          { label },
+        );
+        if (handled) return;
+      }
+      void commitMutation(
+        selection,
+        {
+          type: "add-with-keyframes",
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ...(ease ? { ease } : {}),
+        },
+        { label, softReload: true },
+      );
+    },
+    [commitMutation, activeCompPath, sdkSession, sdkDeps],
+  );
+
+  const replaceWithKeyframes = useCallback(
+    async (
+      selection: DomEditSelection,
+      animationId: string,
+      targetSelector: string,
+      position: number,
+      duration: number,
+      keyframes: KeyframeEntry[],
+      ease?: string,
+      label = "Replace animation with keyframes",
+    ) => {
+      if (sdkSession && sdkDeps) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkReplaceWithKeyframesPersist(
+          targetPath,
+          animationId,
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ease,
+          sdkSession,
+          sdkDeps,
+          { label },
+        );
+        if (handled) return;
+      }
+      void commitMutation(
+        selection,
+        {
+          type: "replace-with-keyframes",
+          animationId,
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ...(ease ? { ease } : {}),
+        },
+        { label, softReload: true },
+      );
+    },
+    [commitMutation, activeCompPath, sdkSession, sdkDeps],
+  );
+
   return {
     updateGsapMeta,
     deleteGsapAnimation,
     deleteAllForSelector,
     addGsapAnimation,
+    addWithKeyframes,
+    replaceWithKeyframes,
   };
 }

package/src/hooks/useSlideshowPersist.ts

@@ -0,0 +1,68 @@
+import { useCallback, type MutableRefObject } from "react";
+import type { Composition } from "@hyperframes/sdk";
+import type { SlideshowManifest } from "@hyperframes/core/slideshow";
+import type { EditHistoryKind } from "../utils/editHistory";
+import { persistSlideshowManifest } from "../utils/setSlideshowManifest";
+
+export interface UseSlideshowPersistParams {
+  sdkSession: Composition | null;
+  activeCompPath: string | null;
+  readProjectFile: (path: string) => Promise<string>;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (entry: {
+    label: string;
+    kind: EditHistoryKind;
+    files: Record<string, { before: string; after: string }>;
+  }) => Promise<void>;
+  reloadPreview: () => void;
+  domEditSaveTimestampRef: MutableRefObject<number>;
+  /**
+   * When provided, rapid writes with the same key coalesce through the
+   * save-queue infra (via recordEdit's coalesceKey) so back-to-back persists
+   * collapse to a single undo entry rather than polluting history.
+   * Pass e.g. `"slideshow-notes:" + activeCompPath` for the notes path.
+   */
+  coalesceKey?: string;
+}
+
+export function useSlideshowPersist({
+  sdkSession,
+  activeCompPath,
+  readProjectFile,
+  writeProjectFile,
+  recordEdit,
+  reloadPreview,
+  domEditSaveTimestampRef,
+  coalesceKey,
+}: UseSlideshowPersistParams): (manifest: SlideshowManifest) => Promise<void> {
+  return useCallback(
+    async (manifest: SlideshowManifest) => {
+      if (!sdkSession) return;
+      const path = activeCompPath ?? "index.html";
+      const originalContent = await readProjectFile(path);
+      await persistSlideshowManifest({
+        manifest,
+        sdkSession,
+        originalContent,
+        targetPath: path,
+        deps: {
+          editHistory: { recordEdit },
+          writeProjectFile,
+          reloadPreview,
+          domEditSaveTimestampRef,
+        },
+        coalesceKey,
+      });
+    },
+    [
+      sdkSession,
+      activeCompPath,
+      readProjectFile,
+      writeProjectFile,
+      recordEdit,
+      reloadPreview,
+      domEditSaveTimestampRef,
+      coalesceKey,
+    ],
+  );
+}

package/src/utils/sdkCutover.ts

@@ -144,10 +144,11 @@ interface CutoverOptions {
   skipRefresh?: boolean;
 }
 
-// ponytail: internal; export only if a third caller appears.
+// ponytail: exported for setSlideshowManifest (third caller — island write bypasses
+// the SDK dispatch path since <script> nodes are not in the element tree).
 // `after` is serialized once by the caller (which also did the no-op check
 // against its pre-dispatch snapshot), so this never re-serializes.
-async function persistSdkSerialize(
+export async function persistSdkSerialize(
   after: string,
   targetPath: string,
   originalContent: string,
@@ -435,6 +436,86 @@ export function sdkGsapConvertToKeyframesPersist(
   );
 }
 
+type KeyframeSpec = {
+  percentage: number;
+  properties: Record<string, number | string>;
+  ease?: string;
+  auto?: boolean;
+};
+
+type KeyframesPayload = {
+  targetSelector: string;
+  position: number;
+  duration: number;
+  keyframes: KeyframeSpec[];
+  ease?: string;
+};
+
+/** Shared inner dispatch for addWithKeyframes / replaceWithKeyframes ops. */
+function dispatchWithKeyframes(
+  s: Composition,
+  payload: KeyframesPayload,
+  animationId?: string,
+): void {
+  if (animationId !== undefined) {
+    s.dispatch({ type: "replaceWithKeyframes", animationId, ...payload });
+  } else {
+    s.dispatch({ type: "addWithKeyframes", ...payload });
+  }
+}
+
+export function sdkAddWithKeyframesPersist(
+  targetPath: string,
+  targetSelector: string,
+  position: number,
+  duration: number,
+  keyframes: KeyframeSpec[],
+  ease: string | undefined,
+  sdkSession: Composition | null | undefined,
+  deps: CutoverDeps,
+  options?: CutoverOptions,
+): Promise<boolean> {
+  const payload: KeyframesPayload = {
+    targetSelector,
+    position,
+    duration,
+    keyframes,
+    ...(ease ? { ease } : {}),
+  };
+  return dispatchGsapOpAndPersist(targetPath, sdkSession, deps, options, (s) =>
+    dispatchWithKeyframes(s, payload),
+  );
+}
+
+export function sdkReplaceWithKeyframesPersist(
+  targetPath: string,
+  animationId: string,
+  targetSelector: string,
+  position: number,
+  duration: number,
+  keyframes: KeyframeSpec[],
+  ease: string | undefined,
+  sdkSession: Composition | null | undefined,
+  deps: CutoverDeps,
+  options?: CutoverOptions,
+): Promise<boolean> {
+  const payload: KeyframesPayload = {
+    targetSelector,
+    position,
+    duration,
+    keyframes,
+    ...(ease ? { ease } : {}),
+  };
+  return dispatchGsapOpAndPersist(
+    targetPath,
+    sdkSession,
+    deps,
+    options,
+    (s) => dispatchWithKeyframes(s, payload, animationId),
+    { animationId, opLabel: "replaceWithKeyframes" },
+  );
+}
+
 export async function sdkDeletePersist(
   hfId: string,
   originalContent: string,

package/src/utils/setSlideshowManifest.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildSlideshowIslandHtml } from "./setSlideshowManifest";
+import { parseSlideshowManifest } from "@hyperframes/core/slideshow";
+import type { CutoverDeps } from "./sdkCutover";
+
+// Fix 3: vi.mock must be at module top level so Vitest can hoist them.
+vi.mock("../components/editor/manualEditingAvailability", () => ({
+  STUDIO_SDK_CUTOVER_ENABLED: true,
+  STUDIO_SDK_RESOLVER_SHADOW_ENABLED: false,
+}));
+vi.mock("./studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+describe("buildSlideshowIslandHtml", () => {
+  it("serializes a manifest into a script island", () => {
+    const html = buildSlideshowIslandHtml({ slides: [{ sceneId: "a" }] });
+    expect(html).toContain('type="application/hyperframes-slideshow+json"');
+    expect(html).toContain('"sceneId": "a"');
+  });
+
+  it("stamps version 1, preserving an existing version", () => {
+    expect(buildSlideshowIslandHtml({ slides: [] })).toContain('"version": 1');
+    expect(buildSlideshowIslandHtml({ version: 2, slides: [] })).toContain('"version": 2');
+  });
+
+  it("round-trips through parseSlideshowManifest", () => {
+    const html = `<html><body>${buildSlideshowIslandHtml({ slides: [{ sceneId: "x" }] })}</body></html>`;
+    const parsed = parseSlideshowManifest(html);
+    expect(parsed?.slides[0]?.sceneId).toBe("x");
+  });
+
+  it("wraps the JSON in a script tag with no extra nesting", () => {
+    const html = buildSlideshowIslandHtml({ slides: [] });
+    expect(html.startsWith("<script")).toBe(true);
+    expect(html.trimEnd().endsWith("</script>")).toBe(true);
+  });
+
+  // Fix 1: </script> breakout test
+  it("does NOT embed a literal </script> inside the JSON body", () => {
+    const manifest = { slides: [{ sceneId: "s1", notes: "</script><b>x</b>" }] };
+    const html = buildSlideshowIslandHtml(manifest);
+    // The only closing </script> should be the real one at the very end.
+    // Strip that trailing tag and confirm no </script> remains.
+    const withoutClosingTag = html.slice(0, html.lastIndexOf("</script>"));
+    expect(withoutClosingTag).not.toContain("</script>");
+  });
+
+  it("round-trips a manifest containing </script> in notes via parseSlideshowManifest", () => {
+    const notes = "</script><b>x</b>";
+    const manifest = { slides: [{ sceneId: "s1", notes }] };
+    const html = `<html><body>${buildSlideshowIslandHtml(manifest)}</body></html>`;
+    const parsed = parseSlideshowManifest(html);
+    expect(parsed?.slides[0]).toMatchObject({ sceneId: "s1", notes });
+  });
+});
+
+describe("persistSlideshowManifest — op construction", () => {
+  function makeDeps(writeProjectFile: ReturnType<typeof vi.fn>): CutoverDeps {
+    return {
+      editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
+      writeProjectFile,
+      reloadPreview: vi.fn(),
+      domEditSaveTimestampRef: { current: 0 },
+    };
+  }
+
+  it("writes the serialized manifest when the island already exists", async () => {
+    const { persistSlideshowManifest } = await import("./setSlideshowManifest");
+
+    const manifest = { slides: [{ sceneId: "scene-1" }] };
+    const island = buildSlideshowIslandHtml(manifest);
+    const originalHtml = `<html><head></head><body>${island}</body></html>`;
+
+    const writeProjectFile = vi.fn().mockResolvedValue(undefined);
+    const deps = makeDeps(writeProjectFile);
+    const recordEdit = deps.editHistory.recordEdit as ReturnType<typeof vi.fn>;
+
+    const mockSession = { serialize: vi.fn().mockReturnValue(originalHtml) };
+
+    await persistSlideshowManifest({
+      manifest: { slides: [{ sceneId: "scene-2" }] },
+      sdkSession: mockSession as never,
+      originalContent: originalHtml,
+      targetPath: "/proj/comp.html",
+      deps,
+    });
+
+    expect(writeProjectFile).toHaveBeenCalledOnce();
+    const written: string = writeProjectFile.mock.calls[0]?.[1] as string;
+    expect(written).toContain('"sceneId": "scene-2"');
+    expect(recordEdit).toHaveBeenCalledWith(expect.objectContaining({ label: "Edit slideshow" }));
+  });
+
+  it("inserts the island when none exists in the serialized HTML", async () => {
+    const { persistSlideshowManifest } = await import("./setSlideshowManifest");
+
+    const baseHtml = "<html><head></head><body></body></html>";
+    const writeProjectFile = vi.fn().mockResolvedValue(undefined);
+    const deps = makeDeps(writeProjectFile);
+    const mockSession = { serialize: vi.fn().mockReturnValue(baseHtml) };
+
+    await persistSlideshowManifest({
+      manifest: { slides: [{ sceneId: "new-scene" }] },
+      sdkSession: mockSession as never,
+      originalContent: baseHtml,
+      targetPath: "/proj/comp.html",
+      deps,
+    });
+
+    expect(writeProjectFile).toHaveBeenCalledOnce();
+    const written: string = writeProjectFile.mock.calls[0]?.[1] as string;
+    expect(written).toContain('"sceneId": "new-scene"');
+    expect(written).toContain('type="application/hyperframes-slideshow+json"');
+  });
+
+  // Fix 2: two stale islands should collapse to exactly one after persist
+  it("collapses two stale islands into exactly one after persist", async () => {
+    const { persistSlideshowManifest } = await import("./setSlideshowManifest");
+
+    const staleIsland1 = buildSlideshowIslandHtml({ slides: [{ sceneId: "old-1" }] });
+    const staleIsland2 = buildSlideshowIslandHtml({ slides: [{ sceneId: "old-2" }] });
+    const twoIslandHtml = `<html><head></head><body>${staleIsland1}${staleIsland2}</body></html>`;
+
+    const writeProjectFile = vi.fn().mockResolvedValue(undefined);
+    const deps = makeDeps(writeProjectFile);
+    const mockSession = { serialize: vi.fn().mockReturnValue(twoIslandHtml) };
+
+    await persistSlideshowManifest({
+      manifest: { slides: [{ sceneId: "fresh" }] },
+      sdkSession: mockSession as never,
+      originalContent: twoIslandHtml,
+      targetPath: "/proj/comp.html",
+      deps,
+    });
+
+    expect(writeProjectFile).toHaveBeenCalledOnce();
+    const written: string = writeProjectFile.mock.calls[0]?.[1] as string;
+
+    // Count occurrences of the island script open tag
+    const islandCount = (written.match(/type="application\/hyperframes-slideshow\+json"/g) ?? [])
+      .length;
+    expect(islandCount).toBe(1);
+    expect(written).toContain('"sceneId": "fresh"');
+    expect(written).not.toContain('"sceneId": "old-1"');
+    expect(written).not.toContain('"sceneId": "old-2"');
+  });
+});