@hyperframes/studio 0.7.90 → 0.7.93

package/src/components/renders/useRenderQueue.ts

@@ -2,6 +2,7 @@ import { useState, useEffect, useCallback, useRef, useMemo } from "react";
 import type { CanvasResolution } from "@hyperframes/parsers";
 import { trackStudioRenderStart } from "../../telemetry/events";
 import { getAnonymousId } from "../../telemetry/config";
+import { browserTelemetryAllowed } from "../../telemetry/policy";
 import { generateId } from "../../utils/generateId";
 
 export interface RenderJob {
@@ -157,16 +158,28 @@ export function useRenderQueue(projectId: string | null) {
         resolution?: string;
         composition?: string;
         variables?: Record<string, unknown>;
-        telemetryDistinctId: string;
+        telemetryDistinctId?: string;
+        telemetryOptOut?: boolean;
       } = {
         fps,
         quality,
         format,
+      };
+      // The id is MINTED by getAnonymousId(), so calling it unconditionally
+      // created a telemetry identity for a profile that had opted out — and
+      // then shipped it to the server. The server's own policy cannot see this
+      // browser's localStorage or DoNotTrack, so it has to be told: an
+      // explicit `telemetryOptOut` suppresses the render outcome, which
+      // omitting the id alone does NOT (an old client omits it too, and that
+      // falls back to the install id).
+      if (browserTelemetryAllowed()) {
         // So the server-emitted render_complete/render_error is attributed to
         // this browser user (same id studio_* events use), making the render
         // funnel joinable. Matches studio_render_start fired just above.
-        telemetryDistinctId: getAnonymousId(),
-      };
+        body.telemetryDistinctId = getAnonymousId();
+      } else {
+        body.telemetryOptOut = true;
+      }
       if (resolution && resolution !== "auto") body.resolution = resolution;
       if (composition) body.composition = composition;
       if (opts.variables && Object.keys(opts.variables).length > 0) {

package/src/components/renders/useRenderQueueTelemetry.test.tsx

@@ -0,0 +1,104 @@
+// @vitest-environment happy-dom
+
+// The render request body is the only place the browser can tell the CLI that
+// this profile opted out. The CLI's own policy cannot see localStorage or
+// DoNotTrack in someone else's browser, so if the body says nothing, the
+// server emits render_complete / render_error anyway — attributed to the
+// install id rather than the user's, which is worse than attributing it
+// correctly.
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const policyState = { allowed: true };
+const mintCalls = vi.fn(() => "browser-user-123");
+
+vi.mock("../../telemetry/policy", () => ({
+  browserTelemetryAllowed: () => policyState.allowed,
+}));
+vi.mock("../../telemetry/config", () => ({
+  getAnonymousId: () => mintCalls(),
+}));
+vi.mock("../../telemetry/events", () => ({
+  trackStudioRenderStart: vi.fn(),
+}));
+
+const { useRenderQueue } = await import("./useRenderQueue");
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let root: Root | null = null;
+
+/** Body of the POST the hook makes when a render is started. */
+async function startRenderBody(): Promise<Record<string, unknown>> {
+  const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) =>
+    Promise.resolve(
+      new Response(JSON.stringify({ jobId: "j1", status: "rendering" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    ),
+  );
+  vi.stubGlobal("fetch", fetchMock);
+  vi.stubGlobal(
+    "EventSource",
+    class {
+      close(): void {}
+      addEventListener(): void {}
+    },
+  );
+
+  let api: ReturnType<typeof useRenderQueue> | null = null;
+  function Harness(): null {
+    api = useRenderQueue("demo");
+    return null;
+  }
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() => {
+    root?.render(<Harness />);
+  });
+  await act(async () => {
+    await api?.startRender({ fps: 30, quality: "standard", format: "mp4" });
+  });
+
+  const post = fetchMock.mock.calls.find(([, init]) => init?.method === "POST");
+  const body = post?.[1]?.body;
+  if (body === undefined || body === null) throw new Error("hook made no POST with a body");
+  return JSON.parse(String(body)) as Record<string, unknown>;
+}
+
+beforeEach(() => {
+  policyState.allowed = true;
+  mintCalls.mockClear();
+});
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  root = null;
+  document.body.innerHTML = "";
+  vi.unstubAllGlobals();
+});
+
+describe("render request telemetry fields", () => {
+  it("sends the browser id when this profile allows telemetry", async () => {
+    const body = await startRenderBody();
+    expect(body["telemetryDistinctId"]).toBe("browser-user-123");
+    expect(body["telemetryOptOut"]).toBeUndefined();
+  });
+
+  it("mints no id and says so explicitly when the profile opted out", async () => {
+    policyState.allowed = false;
+    const body = await startRenderBody();
+    // Minting is itself the leak: getAnonymousId() CREATES and persists an
+    // identity, so calling it for an opted-out profile is wrong even if the
+    // value were never sent.
+    expect(mintCalls).not.toHaveBeenCalled();
+    expect(body["telemetryDistinctId"]).toBeUndefined();
+    // Omission alone would be read as an old client and fall back to the
+    // install id — the flag is what actually suppresses the server event.
+    expect(body["telemetryOptOut"]).toBe(true);
+  });
+});

package/src/components/sidebar/AssetCard.tsx

@@ -8,6 +8,7 @@ import { VIDEO_EXT, IMAGE_EXT } from "../../utils/mediaTypes";
 import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
 import { ContextMenu } from "./AssetContextMenu";
 import { usePlayerStore } from "../../player/store/playerStore";
+import { timelineClipFocusId } from "../../player/components/timelineNavigationIdentity";
 import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
 import { findClipForAsset, isPointerClick } from "../../utils/assetClickBehavior";
 import { basename, ext, truncateMiddle, formatDuration } from "./assetHelpers";
@@ -133,7 +134,7 @@ export function AssetCard({
   const pointerDownRef = useRef<{ x: number; y: number } | null>(null);
 
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
-  const requestClipReveal = usePlayerStore((s) => s.requestClipReveal);
+  const requestTimelineFocus = usePlayerStore((s) => s.requestTimelineFocus);
   const elements = usePlayerStore((s) => s.elements);
   const setPreviewAsset = useAssetPreviewStore((s) => s.setPreviewAsset);
   const clearPreviewAsset = useAssetPreviewStore((s) => s.clearPreviewAsset);
@@ -158,7 +159,7 @@ export function AssetCard({
           const clipKey = clip.key ?? clip.id;
           setSelectedElementId(clipKey);
           // Scroll the timeline so the selected clip is actually visible.
-          requestClipReveal(clipKey);
+          requestTimelineFocus(timelineClipFocusId(clipKey));
           return;
         }
       }
@@ -171,7 +172,7 @@ export function AssetCard({
       asset,
       projectId,
       setSelectedElementId,
-      requestClipReveal,
+      requestTimelineFocus,
       setPreviewAsset,
       clearPreviewAsset,
     ],

package/src/components/sidebar/AudioRow.tsx

@@ -6,6 +6,7 @@ import { usePlayerStore } from "../../player/store/playerStore";
 import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
 import { findClipForAsset, isPointerClick } from "../../utils/assetClickBehavior";
 import { resolveMediaPreviewUrl } from "../../player/components/thumbnailUtils";
+import { timelineClipFocusId } from "../../player/components/timelineNavigationIdentity";
 
 export function AudioRow({
   projectId,
@@ -43,7 +44,7 @@ export function AudioRow({
   // CapCut-style click behavior: drag-threshold gate.
   const pointerDownRef = useRef<{ x: number; y: number } | null>(null);
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
-  const requestClipReveal = usePlayerStore((s) => s.requestClipReveal);
+  const requestTimelineFocus = usePlayerStore((s) => s.requestTimelineFocus);
   const elements = usePlayerStore((s) => s.elements);
   const setPreviewAsset = useAssetPreviewStore((s) => s.setPreviewAsset);
   const clearPreviewAsset = useAssetPreviewStore((s) => s.clearPreviewAsset);
@@ -67,7 +68,7 @@ export function AudioRow({
           const clipKey = clip.key ?? clip.id;
           setSelectedElementId(clipKey);
           // Scroll the timeline so the selected clip is actually visible.
-          requestClipReveal(clipKey);
+          requestTimelineFocus(timelineClipFocusId(clipKey));
           return;
         }
       }
@@ -80,7 +81,7 @@ export function AudioRow({
       asset,
       projectId,
       setSelectedElementId,
-      requestClipReveal,
+      requestTimelineFocus,
       setPreviewAsset,
       clearPreviewAsset,
     ],

package/src/contexts/DomEditContext.tsx

@@ -200,8 +200,8 @@ export function DomEditProvider({
     commitMutation,
     applyMarqueeSelection,
     handleUpdateKeyframeEase,
-    handleSetAllKeyframeEases,
     handleUpdateSegmentEase,
+    handleSetAllKeyframeEases,
   },
   children,
 }: {

package/src/contexts/FileManagerContext.tsx

@@ -27,9 +27,13 @@ export function FileManagerProvider({
     editingPathRef,
     projectIdRef,
     saveRafRef,
+    flushPendingSourceSave,
+    discardPendingSourceSave,
+    getPendingSourceCandidate,
     importedFontAssetsRef,
     readProjectFile,
     writeProjectFile,
+    overwriteExternalConflict,
     readOptionalProjectFile,
     observeProjectFileVersion,
     updateEditingFileContent,
@@ -67,9 +71,13 @@ export function FileManagerProvider({
       editingPathRef,
       projectIdRef,
       saveRafRef,
+      flushPendingSourceSave,
+      discardPendingSourceSave,
+      getPendingSourceCandidate,
       importedFontAssetsRef,
       readProjectFile,
       writeProjectFile,
+      overwriteExternalConflict,
       readOptionalProjectFile,
       observeProjectFileVersion,
       updateEditingFileContent,
@@ -101,9 +109,13 @@ export function FileManagerProvider({
       editingPathRef,
       projectIdRef,
       saveRafRef,
+      flushPendingSourceSave,
+      discardPendingSourceSave,
+      getPendingSourceCandidate,
       importedFontAssetsRef,
       readProjectFile,
       writeProjectFile,
+      overwriteExternalConflict,
       readOptionalProjectFile,
       observeProjectFileVersion,
       updateEditingFileContent,

package/src/hooks/externalFileChangeOwnership.test.ts

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+describe("external file-change subscription ownership", () => {
+  it("has one subscriber instead of independent Preview and SDK listeners", () => {
+    const preview = readFileSync(new URL("./usePreviewPersistence.ts", import.meta.url), "utf8");
+    const sdk = readFileSync(new URL("./useSdkSession.ts", import.meta.url), "utf8");
+    const coordinator = readFileSync(
+      new URL("./useExternalFileChangeCoordinator.ts", import.meta.url),
+      "utf8",
+    );
+
+    expect(preview).not.toContain('hot.on("hf:file-change"');
+    expect(sdk).not.toContain('hot.on("hf:file-change"');
+    expect(coordinator.match(/hot\.on\("hf:file-change"/g)).toHaveLength(1);
+  });
+});

package/src/hooks/externalFileReloadBus.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from "vitest";
+import { addExternalFileReloadListener, notifyExternalFileReload } from "./externalFileReloadBus";
+
+describe("external file reload bus", () => {
+  it("lets the sole watcher reload every SDK owner of the changed path", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const removeFirst = addExternalFileReloadListener(first);
+    const removeSecond = addExternalFileReloadListener(second);
+
+    notifyExternalFileReload("scenes/card.html");
+    expect(first).toHaveBeenCalledWith("scenes/card.html");
+    expect(second).toHaveBeenCalledWith("scenes/card.html");
+
+    removeFirst();
+    removeSecond();
+  });
+
+  it("isolates a broken listener so later SDK owners still reload", () => {
+    const broken = vi.fn(() => {
+      throw new Error("stale owner");
+    });
+    const healthy = vi.fn();
+    const removeBroken = addExternalFileReloadListener(broken);
+    const removeHealthy = addExternalFileReloadListener(healthy);
+
+    expect(() => notifyExternalFileReload("scenes/card.html")).not.toThrow();
+    expect(broken).toHaveBeenCalledWith("scenes/card.html");
+    expect(healthy).toHaveBeenCalledWith("scenes/card.html");
+
+    removeBroken();
+    removeHealthy();
+  });
+});

package/src/hooks/externalFileReloadBus.ts

@@ -0,0 +1,18 @@
+type ExternalFileReloadListener = (path: string) => void;
+
+const listeners = new Set<ExternalFileReloadListener>();
+
+export function addExternalFileReloadListener(listener: ExternalFileReloadListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function notifyExternalFileReload(path: string): void {
+  for (const listener of listeners) {
+    try {
+      listener(path);
+    } catch {
+      // A stale SDK owner must not prevent sibling owners from reloading.
+    }
+  }
+}

package/src/hooks/gsapDragCommit.test.ts

@@ -1,6 +1,6 @@
 // @vitest-environment happy-dom
 
-import { describe, expect, it, beforeEach } from "vitest";
+import { describe, expect, it, beforeEach, vi } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { commitGsapPositionFromDrag } from "./gsapDragPositionCommit";
@@ -9,6 +9,7 @@ import {
   commitStaticGsapRotation,
   commitStaticGsapSize,
   findExistingPositionWrite,
+  materializeIfDynamic,
   parkPlayheadOnKeyframe,
   type GsapDragCommitCallbacks,
 } from "./gsapDragCommit";
@@ -27,6 +28,43 @@ const selection = (): DomEditSelection =>
     },
   }) as unknown as DomEditSelection;
 
+function selectorlessSelection(): DomEditSelection {
+  return {
+    selector: ".shared",
+    element: document.createElement("div"),
+  } as unknown as DomEditSelection;
+}
+
+describe("lower GSAP commit helpers fail closed", () => {
+  it("rejects instead of silently dropping a static position write without a stable selector", async () => {
+    const commitMutation = vi.fn();
+    await expect(
+      commitStaticGsapPosition(
+        selectorlessSelection(),
+        { x: 10, y: 20 },
+        { x: 0, y: 0 },
+        ".shared",
+        null,
+        { commitMutation },
+      ),
+    ).rejects.toMatchObject({ name: "GsapEditBlockedError", reason: "no-selector" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+
+  it("rejects runtime-dynamic materialization instead of rewriting source during a gesture", async () => {
+    const commitMutation = vi.fn();
+    await expect(
+      materializeIfDynamic(
+        { ...flatTween(), hasUnresolvedKeyframes: true },
+        null,
+        commitMutation,
+        selection(),
+      ),
+    ).rejects.toMatchObject({ name: "GsapEditBlockedError", reason: "source-uneditable" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+});
+
 const flatTween = (): GsapAnimation =>
   ({
     id: "#puck-a-to",

package/src/hooks/gsapDragCommit.ts

@@ -9,14 +9,14 @@ import {
   STUDIO_ORIGINAL_HEIGHT_ATTR,
 } from "../components/editor/manualEditsTypes";
 import { usePlayerStore } from "../player/store/playerStore";
-import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeKeyframes";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
 import { roundTo3 } from "../utils/rounding";
-import { computeElementPercentage, idSelector, writeTargetSelector } from "./gsapShared";
+import { computeElementPercentage, writeTargetSelector } from "./gsapShared";
 import { computeDraggedGsapPosition } from "./draggedGsapPosition";
 import type { RuntimeTweenChange } from "./gsapRuntimePatch";
 import { isGestureTransactionCommit, runGestureTransaction } from "./gestureTransaction";
 import { setPatchFromUpdateProperty } from "./gsapDragStaticSetHelpers";
+import { GsapEditBlockedError } from "./gsapEditOutcome";
 export {
   findExistingPositionWrite,
   findRotationSetAnimation,
@@ -87,7 +87,7 @@ async function replaceKeyframedPositionHold(
   commitMutation: GsapDragCommitCallbacks["commitMutation"],
 ): Promise<void> {
   const target = newTweenTarget(selection);
-  if (!target) return;
+  if (!target) throw new GsapEditBlockedError("no-selector");
   const persist = async (commit: GsapDragCommitCallbacks["commitMutation"]) => {
     await commit(
       selection,
@@ -130,40 +130,12 @@ export async function materializeIfDynamic(
   selection: DomEditSelection,
 ): Promise<string | void> {
   if (!anim.hasUnresolvedKeyframes && !anim.hasUnresolvedSelector) return;
-
-  if (anim.hasUnresolvedSelector) {
-    const allScanned = scanAllRuntimeKeyframes(iframe);
-    if (allScanned.size === 0) return;
-    const allElements = Array.from(allScanned.entries()).map(([id, data]) => ({
-      selector: idSelector(id),
-      keyframes: data.keyframes,
-      easeEach: data.easeEach,
-    }));
-    await commitMutation(
-      selection,
-      {
-        type: "materialize-keyframes",
-        animationId: anim.id,
-        keyframes: allScanned.get(selection.id ?? "")?.keyframes ?? [],
-        allElements,
-      },
-      { label: "Unroll dynamic animations", skipReload: true },
-    );
-    return `${anim.targetSelector}-to-0`;
-  }
-
-  const runtime = readRuntimeKeyframes(iframe, anim.targetSelector);
-  if (!runtime || runtime.keyframes.length === 0) return;
-  await commitMutation(
-    selection,
-    {
-      type: "materialize-keyframes",
-      animationId: anim.id,
-      keyframes: runtime.keyframes,
-      easeEach: runtime.easeEach,
-    },
-    { label: "Materialize dynamic keyframes", skipReload: true },
-  );
+  // Geometry commits must never rewrite runtime/computed source implicitly.
+  // The explicit Unroll action owns that source-destructive transition.
+  void iframe;
+  void commitMutation;
+  void selection;
+  throw new GsapEditBlockedError("source-uneditable");
 }
 
 // ── Drag → GSAP position math ──────────────────────────────────────────────
@@ -219,7 +191,7 @@ export async function commitStaticGsapPosition(
   // The patch reuses the WRITTEN target so the runtime moves exactly the element
   // the source write names.
   const target = newTweenTarget(selection);
-  if (!target) return;
+  if (!target) throw new GsapEditBlockedError("no-selector");
   await callbacks.commitMutation(
     selection,
     {
@@ -277,7 +249,7 @@ export async function commitStaticGsapRotation(
   }
   // New static hold → off-timeline `gsap.set` (no 0% keyframe marker) + instant patch.
   const target = newTweenTarget(selection);
-  if (!target) return;
+  if (!target) throw new GsapEditBlockedError("no-selector");
   await callbacks.commitMutation(
     selection,
     {
@@ -331,7 +303,7 @@ export async function commitStaticGsapSize(
     return;
   }
   const target = newTweenTarget(selection);
-  if (!target) return;
+  if (!target) throw new GsapEditBlockedError("no-selector");
   await callbacks.commitMutation(
     selection,
     {

package/src/hooks/gsapEditOutcome.ts

@@ -0,0 +1,72 @@
+import { editabilityForProvenance, type GsapAnimation } from "@hyperframes/core/gsap-parser";
+
+export type GsapEditBlockReason = "no-selector" | "unroll-required" | "source-uneditable";
+
+export type GsapEditOutcome =
+  | { status: "persisted" }
+  | { status: "blocked"; reason: GsapEditBlockReason };
+
+const COPY: Record<GsapEditBlockReason, string> = {
+  "no-selector": "This layer needs a stable selector before Studio can save the edit.",
+  "unroll-required":
+    "This motion comes from a helper or loop. Choose Unroll to edit it explicitly.",
+  "source-uneditable": "This animation is computed at runtime. Edit the animation in the Code tab.",
+};
+
+export class GsapEditBlockedError extends Error {
+  constructor(readonly reason: GsapEditBlockReason) {
+    super(COPY[reason]);
+    this.name = "GsapEditBlockedError";
+  }
+}
+
+export function assertGsapEditPersisted(outcome: GsapEditOutcome): void {
+  if (outcome.status === "blocked") throw new GsapEditBlockedError(outcome.reason);
+}
+
+function assertGsapAnimationDirectlyEditable(animation: GsapAnimation): void {
+  const editability = editabilityForProvenance(animation.provenance);
+  if (editability === "unroll") throw new GsapEditBlockedError("unroll-required");
+  if (
+    editability === "source" ||
+    animation.hasUnresolvedKeyframes ||
+    animation.hasUnresolvedSelector
+  ) {
+    throw new GsapEditBlockedError("source-uneditable");
+  }
+}
+
+export function isGsapEditBlockedError(error: unknown): error is GsapEditBlockedError {
+  return error instanceof GsapEditBlockedError;
+}
+
+export function animationWritesAnyProperty(
+  animation: GsapAnimation,
+  properties: ReadonlySet<string>,
+): boolean {
+  return (
+    Object.keys(animation.properties ?? {}).some((property) => properties.has(property)) ||
+    Object.keys(animation.fromProperties ?? {}).some((property) => properties.has(property)) ||
+    !!animation.keyframes?.keyframes.some((keyframe) =>
+      Object.keys(keyframe.properties).some((property) => properties.has(property)),
+    )
+  );
+}
+
+/** Fail-closed ownership check shared by drag, resize, rotate, and inspector edits. */
+export function directEditOutcomeForProperties(
+  animations: GsapAnimation[],
+  properties: ReadonlySet<string>,
+): GsapEditOutcome {
+  try {
+    for (const animation of animations) {
+      if (animationWritesAnyProperty(animation, properties)) {
+        assertGsapAnimationDirectlyEditable(animation);
+      }
+    }
+    return { status: "persisted" };
+  } catch (error) {
+    if (isGsapEditBlockedError(error)) return { status: "blocked", reason: error.reason };
+    throw error;
+  }
+}