@hyperframes/studio 0.6.113 → 0.6.115

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/player/lib/timelineDOM.ts

@@ -123,7 +123,8 @@ export function createTimelineElementFromManifestClip(params: {
   if (clip.kind === "composition" && clip.compositionId) {
     let resolvedSrc = clip.compositionSrc;
     if (!resolvedSrc) {
-      hostEl = doc?.querySelector(`[data-composition-id="${clip.compositionId}"]`) ?? hostEl;
+      hostEl =
+        doc?.querySelector(`[data-composition-id="${CSS.escape(clip.compositionId)}"]`) ?? hostEl;
       resolvedSrc =
         hostEl?.getAttribute("data-composition-src") ??
         hostEl?.getAttribute("data-composition-file") ??

package/src/player/lib/timelineElementHelpers.ts

@@ -163,13 +163,13 @@ export function getImplicitTimelineLayerLabel(el: HTMLElement): string {
 // ---------------------------------------------------------------------------
 
 export function getTimelineElementSelector(el: Element): string | undefined {
-  if (isHtmlElement(el) && el.id) return `#${el.id}`;
+  if (isHtmlElement(el) && el.id) return `#${CSS.escape(el.id)}`;
   const compId = el.getAttribute("data-composition-id");
-  if (compId) return `[data-composition-id="${compId}"]`;
+  if (compId) return `[data-composition-id="${CSS.escape(compId)}"]`;
   if (isHtmlElement(el)) {
     const classes = el.className.split(/\s+/).filter(Boolean);
     const firstClass = classes.find((className) => className !== "clip") ?? classes[0];
-    if (firstClass) return `.${firstClass}`;
+    if (firstClass) return `.${CSS.escape(firstClass)}`;
   }
   return undefined;
 }
@@ -283,8 +283,8 @@ function nodeMatchesManifestClip(node: Element, clip: ClipManifestClip): boolean
 function findTimelineDomNode(doc: Document, id: string): Element | null {
   return (
     doc.getElementById(id) ??
-    doc.querySelector(`[data-composition-id="${id}"]`) ??
-    doc.querySelector(`.${id}`) ??
+    doc.querySelector(`[data-composition-id="${CSS.escape(id)}"]`) ??
+    doc.querySelector(`.${CSS.escape(id)}`) ??
     null
   );
 }

package/src/player/lib/timelineIframeHelpers.ts

@@ -295,7 +295,8 @@ export function buildMissingCompositionElements(
     let start = parseFloat(startAttr);
     if (isNaN(start)) {
       const ref =
-        doc.getElementById(startAttr) || doc.querySelector(`[data-composition-id="${startAttr}"]`);
+        doc.getElementById(startAttr) ||
+        doc.querySelector(`[data-composition-id="${CSS.escape(startAttr)}"]`);
       if (ref) {
         const refStartAttr = ref.getAttribute("data-start") ?? "0";
         let refStart = parseFloat(refStartAttr);
@@ -303,7 +304,7 @@ export function buildMissingCompositionElements(
         if (isNaN(refStart)) {
           const refRef =
             doc.getElementById(refStartAttr) ||
-            doc.querySelector(`[data-composition-id="${refStartAttr}"]`);
+            doc.querySelector(`[data-composition-id="${CSS.escape(refStartAttr)}"]`);
           const rrStart = parseFloat(refRef?.getAttribute("data-start") ?? "0") || 0;
           const rrCompId = refRef?.getAttribute("data-composition-id");
           const rrDur =
@@ -400,7 +401,7 @@ export function buildMissingCompositionElements(
     // Find the matching DOM host by element id or composition id
     const host =
       doc.getElementById(existing.id) ??
-      doc.querySelector(`[data-composition-id="${existing.id}"]`);
+      doc.querySelector(`[data-composition-id="${CSS.escape(existing.id)}"]`);
     if (!host) return existing;
     const compSrc =
       host.getAttribute("data-composition-src") || host.getAttribute("data-composition-file");

package/src/test-setup.ts

@@ -0,0 +1,6 @@
+if (typeof globalThis.CSS === "undefined") {
+  (globalThis as Record<string, unknown>).CSS = {};
+}
+if (typeof CSS.escape !== "function") {
+  CSS.escape = (value: string) => value.replace(/([^\w-])/g, "\\$1");
+}

package/src/utils/htmlAttrSafety.ts

@@ -0,0 +1,90 @@
+// keep-in-sync-with: packages/core/src/utils/htmlAttrSafety.ts
+const ALLOWED_HTML_ATTRS = new Set([
+  "id",
+  "class",
+  "style",
+  "title",
+  "name",
+  "for",
+  "type",
+  "lang",
+  "dir",
+  "translate",
+  "hidden",
+  "tabindex",
+  "draggable",
+  "contenteditable",
+  "role",
+  "slot",
+  "href",
+  "target",
+  "rel",
+  "src",
+  "srcset",
+  "sizes",
+  "alt",
+  "poster",
+  "loading",
+  "decoding",
+  "crossorigin",
+  "preload",
+  "autoplay",
+  "loop",
+  "muted",
+  "controls",
+  "playsinline",
+  "width",
+  "height",
+  "colspan",
+  "rowspan",
+  "scope",
+  "placeholder",
+  "value",
+  "min",
+  "max",
+  "step",
+  "pattern",
+  "required",
+  "disabled",
+  "readonly",
+  "checked",
+  "selected",
+  "multiple",
+  "accept",
+  "maxlength",
+  "minlength",
+  "rows",
+  "cols",
+  "wrap",
+]);
+
+const URI_BEARING_ATTRS = new Set([
+  "src",
+  "href",
+  "action",
+  "formaction",
+  "poster",
+  "srcset",
+  "xlink:href",
+]);
+
+const DANGEROUS_URI_SCHEMES = /^(?:javascript|vbscript):/i;
+const DANGEROUS_DATA_URI = /^data\s*:\s*text\/html/i;
+
+export function isAllowedHtmlAttribute(name: string): boolean {
+  const lower = name.toLowerCase();
+  if (lower.startsWith("on")) return false;
+  if (ALLOWED_HTML_ATTRS.has(lower)) return true;
+  if (lower.startsWith("data-")) return true;
+  if (lower.startsWith("aria-")) return true;
+  return false;
+}
+
+export function isSafeAttributeValue(name: string, value: string): boolean {
+  if (URI_BEARING_ATTRS.has(name.toLowerCase())) {
+    const trimmed = value.trim();
+    if (DANGEROUS_URI_SCHEMES.test(trimmed)) return false;
+    if (DANGEROUS_DATA_URI.test(trimmed)) return false;
+  }
+  return true;
+}

package/src/utils/sdkCutover.test.ts

@@ -98,6 +98,36 @@ describe("shouldUseSdkCutover", () => {
     expect(shouldUseSdkCutover(true, true, "hf-abc", [htmlAttrOp("DATA-START", "1")])).toBe(false);
   });
 
+  it("declines html-attribute ops with event handler names", () => {
+    expect(shouldUseSdkCutover(true, true, "hf-abc", [htmlAttrOp("onclick", "alert(1)")])).toBe(
+      false,
+    );
+    expect(shouldUseSdkCutover(true, true, "hf-abc", [htmlAttrOp("onload", "fetch()")])).toBe(
+      false,
+    );
+  });
+
+  it("declines html-attribute ops with disallowed attribute names", () => {
+    expect(shouldUseSdkCutover(true, true, "hf-abc", [htmlAttrOp("formaction", "/x")])).toBe(false);
+  });
+
+  it("declines html-attribute ops with dangerous URI schemes", () => {
+    expect(
+      shouldUseSdkCutover(true, true, "hf-abc", [htmlAttrOp("href", "javascript:alert(1)")]),
+    ).toBe(false);
+    expect(shouldUseSdkCutover(true, true, "hf-abc", [htmlAttrOp("src", "vbscript:run")])).toBe(
+      false,
+    );
+  });
+
+  it("declines html-attribute ops with dangerous data URIs", () => {
+    expect(
+      shouldUseSdkCutover(true, true, "hf-abc", [
+        htmlAttrOp("href", "data:text/html,<script>alert(1)</script>"),
+      ]),
+    ).toBe(false);
+  });
+
   it("returns true when ops mix all supported types", () => {
     expect(
       shouldUseSdkCutover(true, true, "hf-abc", [
@@ -205,6 +235,27 @@ describe("sdkCutoverPersist", () => {
     });
   });
 
+  it.each([
+    { name: "multi-child targets", children: [{ id: "a" }, { id: "b" }] },
+    { name: "single non-html children", children: [{ id: "a", tag: "svg" }] },
+  ])("declines text-content cutover for $name", async ({ children }) => {
+    const deps = makeDeps();
+    const session = makeSession(true);
+    (session!.getElement as ReturnType<typeof vi.fn>).mockReturnValue({ children });
+    const sel = { hfId: "hf-abc" } as never;
+    const result = await sdkCutoverPersist(
+      sel,
+      [textOp("Hello world")],
+      "before",
+      "/comp.html",
+      session,
+      deps,
+    );
+    expect(result).toBe(false);
+    expect(session!.dispatch).not.toHaveBeenCalled();
+    expect(deps.writeProjectFile).not.toHaveBeenCalled();
+  });
+
   it("dispatches setAttribute for attribute op with data- prefix", async () => {
     const deps = makeDeps();
     const session = makeSession(true);

package/src/utils/sdkCutover.ts

@@ -8,6 +8,7 @@ import { trackStudioEvent } from "./studioTelemetry";
 import { markSelfWrite } from "../hooks/sdkSelfWriteRegistry";
 import { patchOpsToSdkEditOps } from "./sdkOpMapping";
 import { recordResolverParity, recordAnimationResolverParity } from "./sdkResolverShadow";
+import { isAllowedHtmlAttribute, isSafeAttributeValue } from "./htmlAttrSafety";
 
 const CUTOVER_OP_TYPES = new Set<PatchOperation["type"]>([
   "inline-style",
@@ -52,6 +53,54 @@ function mapsToReservedAttr(op: PatchOperation): boolean {
   return name !== null && RESERVED_CUTOVER_ATTRS.has(name.toLowerCase());
 }
 
+// ─── html-attribute safety ───────────────────────────────────────────────────
+
+function hasUnsafeHtmlAttributeOp(ops: PatchOperation[]): boolean {
+  return ops.some(
+    (op) =>
+      op.type === "html-attribute" &&
+      (!isAllowedHtmlAttribute(op.property) ||
+        (op.value !== null && !isSafeAttributeValue(op.property, op.value))),
+  );
+}
+
+function hasTextContentOp(ops: PatchOperation[]): boolean {
+  return ops.some((op) => op.type === "text-content");
+}
+
+function targetChildren(target: unknown): unknown[] | null {
+  if (!target || typeof target !== "object" || !("children" in target)) return null;
+  const children = (target as { children?: unknown }).children;
+  return Array.isArray(children) ? children : null;
+}
+
+function elementTag(element: unknown): string | null {
+  if (!element || typeof element !== "object" || !("tag" in element)) return null;
+  const tag = (element as { tag?: unknown }).tag;
+  return typeof tag === "string" ? tag.toLowerCase() : null;
+}
+
+// Tags that are non-HTML namespace elements in a linkedom-parsed HTML body.
+// Mirrors the engine's `isHTMLElementTarget` (model.ts) which uses `instanceof
+// HTMLElement` — that runtime check catches the same set, but we can't use it
+// here because `target` is a plain SDK object, not a DOM Element. If linkedom
+// (or a future parser) surfaces additional foreign-content elements as
+// non-HTMLElement, add them here.
+const NON_HTML_CHILD_TAGS = new Set(["svg", "math"]);
+
+function shouldDeclineTextCutoverForTarget(target: unknown, ops: PatchOperation[]): boolean {
+  if (!hasTextContentOp(ops)) return false;
+  const children = targetChildren(target);
+  if (!children) return false;
+  // Legacy patch-element replaces the whole element for multi-child targets and
+  // for single non-HTML children. The SDK text patch stream stores a scalar
+  // inverse, so those shapes cannot be made both byte-identical and undo-safe
+  // here. Let the server path remain authoritative for them.
+  if (children.length > 1) return true;
+  const tag = elementTag(children[0]);
+  return tag !== null && NON_HTML_CHILD_TAGS.has(tag);
+}
+
 export function shouldUseSdkCutover(
   flagEnabled: boolean,
   hasSession: boolean,
@@ -64,7 +113,8 @@ export function shouldUseSdkCutover(
     !!hfId &&
     ops.length > 0 &&
     ops.every((o) => CUTOVER_OP_TYPES.has(o.type)) &&
-    !ops.some(mapsToReservedAttr)
+    !ops.some(mapsToReservedAttr) &&
+    !hasUnsafeHtmlAttributeOp(ops)
   );
 }
 
@@ -144,10 +194,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,
@@ -185,7 +236,9 @@ export async function sdkCutoverPersist(
   if (!sdkSession) return false;
   const hfId = selection.hfId;
   if (!hfId) return false;
-  if (!sdkSession.getElement(hfId)) return false;
+  const target = sdkSession.getElement(hfId);
+  if (!target) return false;
+  if (shouldDeclineTextCutoverForTarget(target, ops)) return false;
   if (wrongCompositionFile(deps, targetPath)) return false;
   try {
     const before = sdkSession.serialize();