@hyperframes/studio 0.6.113 → 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/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,

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"');
+  });
+});

package/src/utils/setSlideshowManifest.ts

@@ -0,0 +1,102 @@
+/**
+ * setSlideshowManifest — Studio persist helper for the slideshow JSON island.
+ *
+ * The island is a `<script type="application/hyperframes-slideshow+json">` node
+ * embedded in the composition HTML.  Because <script> nodes are not tracked by
+ * the SDK element tree (they have no hf-id), we cannot use a `setText` dispatch
+ * op.  Instead we:
+ *   1. Call `sdkSession.serialize()` to get the current HTML.
+ *   2. Replace or insert the island with the new manifest JSON.
+ *   3. Write via `persistSdkSerialize` — the same low-level writer used by the
+ *      other SDK-cutover paths (sdkDeletePersist, sdkTimingPersist, etc.).
+ *
+ * Inserting when absent: if no island exists in the serialized HTML we insert
+ * one before `</body>` (or, if no </body>, append to the end of the document).
+ * This means callers do NOT need to pre-scaffold the island; Task 11 / the panel
+ * can call persistSlideshowManifest on a fresh composition.
+ */
+
+import type { SlideshowManifest } from "@hyperframes/core/slideshow";
+import {
+  SLIDESHOW_ISLAND_TYPE,
+  SLIDESHOW_MANIFEST_VERSION,
+  parseSlideshowManifest,
+  slideshowIslandRegex,
+} from "@hyperframes/core/slideshow";
+import type { Composition } from "@hyperframes/sdk";
+import type { CutoverDeps } from "./sdkCutover";
+import { persistSdkSerialize } from "./sdkCutover";
+
+// Matches ALL <script type="application/hyperframes-slideshow+json"> ... </script>
+// blocks (global + case-insensitive) so we can strip every stale island in one pass.
+const ISLAND_RE = slideshowIslandRegex("gi");
+
+export function buildSlideshowIslandHtml(manifest: SlideshowManifest): string {
+  // Stamp the schema version (preserve an existing one) so future schema
+  // changes can detect and migrate older islands.
+  const versioned: SlideshowManifest = {
+    version: manifest.version ?? SLIDESHOW_MANIFEST_VERSION,
+    ...manifest,
+  };
+  // Escape `<` and `>` so that a manifest field containing `</script>` cannot
+  // break out of the script tag. JSON.parse round-trips </> unchanged.
+  const json = JSON.stringify(versioned, null, 2).replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+  return `<script type="${SLIDESHOW_ISLAND_TYPE}">\n${json}\n</script>`;
+}
+
+export interface PersistSlideshowArgs {
+  manifest: SlideshowManifest;
+  /** Live SDK Composition session — used only to read the current serialized HTML. */
+  sdkSession: Pick<Composition, "serialize">;
+  /** Exact on-disk bytes for the undo-history `before` baseline. */
+  originalContent: string;
+  targetPath: string;
+  deps: CutoverDeps;
+  /** Optional label override (default: "Edit slideshow"). */
+  label?: string;
+  /**
+   * When provided, threads a coalesceKey into recordEdit so rapid writes
+   * (e.g. per-keystroke notes changes) collapse to a single undo entry.
+   */
+  coalesceKey?: string;
+}
+
+export async function persistSlideshowManifest(args: PersistSlideshowArgs): Promise<void> {
+  const { manifest, sdkSession, originalContent, targetPath, deps, label, coalesceKey } = args;
+
+  const islandHtml = buildSlideshowIslandHtml(manifest);
+
+  // Write-time validation: confirm the island we just built round-trips to a
+  // valid manifest before touching disk, so a malformed edit can't corrupt the
+  // composition. parseSlideshowManifest throws on a structurally-invalid island.
+  try {
+    if (!parseSlideshowManifest(islandHtml)) {
+      throw new Error("built island did not parse back to a manifest");
+    }
+  } catch (err) {
+    throw new Error(`refusing to persist invalid slideshow manifest: ${(err as Error).message}`);
+  }
+
+  const current = sdkSession.serialize();
+
+  // Strip ALL existing islands (handles the case where two stale islands
+  // accumulated) then insert exactly one fresh island.
+  const stripped = current.replace(ISLAND_RE, "");
+
+  let after: string;
+  const bodyClose = stripped.lastIndexOf("</body>");
+  if (bodyClose !== -1) {
+    after = stripped.slice(0, bodyClose) + islandHtml + "\n" + stripped.slice(bodyClose);
+  } else {
+    after = stripped + "\n" + islandHtml;
+  }
+
+  // No-op gate: if the rewritten HTML is byte-identical to the current serialized
+  // HTML, skip the write — avoids a spurious disk write and a no-op undo entry.
+  if (after === current) return;
+
+  await persistSdkSerialize(after, targetPath, originalContent, deps, {
+    label: label ?? "Edit slideshow",
+    ...(coalesceKey ? { coalesceKey } : {}),
+  });
+}

package/src/utils/studioHelpers.ts

@@ -13,7 +13,7 @@ export interface AppToast {
   tone: "error" | "info";
 }
 
-export type RightPanelTab = "layers" | "design" | "renders" | "block-params";
+export type RightPanelTab = "layers" | "design" | "renders" | "block-params" | "slideshow";
 export type RightInspectorPane = "layers" | "design";
 
 export interface RightInspectorPanes {
@@ -204,6 +204,7 @@ export function clampNumber(value: number, min: number, max: number): number {
   return Math.min(Math.max(value, min), max);
 }
 
+// fallow-ignore-next-line unused-export
 export { COMPOSITION_ROOT_OPEN_TAG_RE } from "./compositionPatterns";
 
 export function collectHtmlIds(source: string): string[] {