@hyperframes/studio 0.8.19 → 0.8.21

package/src/player/hooks/useExpandedTimelineElements.ts

@@ -1,5 +1,10 @@
 import { useMemo } from "react";
-import { usePlayerStore, type TimelineElement, type DomClipChild } from "../store/playerStore";
+import {
+  usePlayerStore,
+  type TimelineElement,
+  type DomClipChild,
+  type SubCompositionHostState,
+} from "../store/playerStore";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 import { createTimelineElementFromManifestClip } from "../lib/timelineDOM";
 import { buildTimelineElementKey, splitTimelineElementKey } from "../lib/timelineElementHelpers";
@@ -131,18 +136,6 @@ interface DisplayBounds {
   track: number;
 }
 
-/**
- * State that lives on the live host element, not in the clip manifest:
- * `data-hidden`, `data-timeline-locked`, `data-timeline-role`. A child row is
- * built from a manifest clip with no hostEl to read, so
- * createTimelineElementFromManifestClip cannot see any of it. The flat store
- * element for the same child WAS built with one, so it is inherited from there.
- *
- * Without this the eye on an expanded child always reported the row visible, so
- * clicking it wrote data-hidden again instead of removing it, and a hidden child
- * could never be shown again (not even after a reload, since the attribute is in
- * the source).
- */
 /**
  * Audio-group membership for an expanded child, from whichever source has it.
  *
@@ -169,20 +162,34 @@ function childGroupState(
   };
 }
 
-function hostElementState(flat: TimelineElement | undefined): Partial<TimelineElement> {
-  if (!flat) return {};
-  return {
-    hidden: flat.hidden,
-    timelineLocked: flat.timelineLocked,
-    timelineRole: flat.timelineRole,
-    // Same reason as the three above: these are read off the host element, which
-    // an expanded child is built without. Missing them, an audio child inside a
-    // sub-composition reserved no automation height and drew no lanes, while the
-    // property panel — reading the live DOM selection rather than this row —
-    // still showed the chain and its toggles.
-    fxChain: flat.fxChain,
-    automation: flat.automation,
-  };
+/**
+ * State that lives on the live host element, not in the clip manifest:
+ * `data-hidden`, `data-timeline-locked`, `data-timeline-role`, `data-fx-chain`,
+ * `data-automation`. A child row is built from a manifest clip with no hostEl to
+ * read, so createTimelineElementFromManifestClip cannot see any of it.
+ *
+ * `live` is the reading taken off the element itself and is authoritative. For a
+ * child of a REAL sub-composition it is also the only source: such a clip is
+ * filtered out of the manifest before the flat store is built, so no twin exists
+ * to inherit from. The flat twin still covers the phantom-wrapper case, where
+ * the child does keep a store entry of its own.
+ *
+ * Without a reading of the element, the eye on an expanded child always reported
+ * the row visible, so clicking it wrote data-hidden again instead of removing
+ * it, and a hidden child could never be shown again (not even after a reload,
+ * since the attribute is in the source). Missing fxChain and automation, an
+ * audio child inside a sub-composition reserved no automation height and drew no
+ * lanes, while the property panel, which reads the live DOM selection rather
+ * than this row, still showed the chain and its toggles.
+ */
+function hostElementState(
+  flat: TimelineElement | undefined,
+  live: SubCompositionHostState | undefined,
+): Partial<TimelineElement> {
+  if (!flat) return { ...live };
+  const { hidden, timelineLocked, timelineRole, fxChain, automation } = flat;
+  // `live` last: it is the reading off the element, so it wins wherever it has one.
+  return { hidden, timelineLocked, timelineRole, fxChain, automation, ...live };
 }
 
 // `display` bounds come from the top-level scene clip (where the expanded row is
@@ -196,6 +203,7 @@ function buildChildElements(
   expandedHostKey: string,
   elements: readonly TimelineElement[],
   domChildrenById: ReadonlyMap<string, DomClipChild>,
+  hostStateById: ReadonlyMap<string, SubCompositionHostState>,
 ): TimelineElement[] {
   const result: TimelineElement[] = [];
   for (const child of siblings) {
@@ -223,7 +231,10 @@ function buildChildElements(
     });
     result.push({
       ...base,
-      ...hostElementState(elements.find((element) => element.key === key)),
+      ...hostElementState(
+        elements.find((element) => element.key === key),
+        domId ? hostStateById.get(domId) : undefined,
+      ),
       ...childGroupState(
         elements.find((element) => element.key === key),
         domId ? domChildrenById.get(domId) : undefined,
@@ -309,6 +320,7 @@ export function buildExpandedElements(
   topLevelId: string,
   siblingParentId: string,
   domClipChildren: DomClipChild[] = [],
+  subCompositionHostState: ReadonlyMap<string, SubCompositionHostState> = new Map(),
 ): TimelineElement[] {
   const topLevelElement = elements.find((el) => el.id === topLevelId || el.domId === topLevelId);
   if (!topLevelElement) return filterToTopLevel(elements, parentMap);
@@ -348,6 +360,7 @@ export function buildExpandedElements(
     parentKey,
     elements,
     domChildrenById,
+    subCompositionHostState,
   );
   if (expanded.length === 0) return filterToTopLevel(elements, parentMap);
 
@@ -391,6 +404,7 @@ export function useExpandedTimelineElements(): TimelineElement[] {
   const clipManifest = usePlayerStore((s) => s.clipManifest);
   const clipParentMap = usePlayerStore((s) => s.clipParentMap);
   const domClipChildren = usePlayerStore((s) => s.domClipChildren);
+  const subCompositionHostState = usePlayerStore((s) => s.subCompositionHostState);
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
   const currentTime = usePlayerStore((s) => s.currentTime);
 
@@ -432,6 +446,15 @@ export function useExpandedTimelineElements(): TimelineElement[] {
       topLevel,
       immediateParent,
       domClipChildren,
+      subCompositionHostState,
     );
-  }, [elements, clipManifest, clipParentMap, domClipChildren, rawId, selectedRawId]);
+  }, [
+    elements,
+    clipManifest,
+    clipParentMap,
+    domClipChildren,
+    subCompositionHostState,
+    rawId,
+    selectedRawId,
+  ]);
 }

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -19,6 +19,7 @@ import {
   buildTimelineElementsFromClips,
   clipTreeParentMap,
   collectSubCompositionDomChildren,
+  collectSubCompositionHostState,
   hydrateTimelineFromPreview,
   isPreviewReadinessMessage,
   safeContentDocument,
@@ -131,6 +132,9 @@ export function useTimelineSyncCallbacks({
         const domClipChildren = collectSubCompositionDomChildren(iframeDoc, data.clips, parentMap);
         usePlayerStore.getState().setClipParentMap(parentMap);
         usePlayerStore.getState().setDomClipChildren(domClipChildren);
+        usePlayerStore
+          .getState()
+          .setSubCompositionHostState(collectSubCompositionHostState(iframeDoc, data.clips));
       } catch {
         // cross-origin or __clipTree not available — maps stay empty
       }

package/src/player/store/playerStore.ts

@@ -23,9 +23,13 @@ import { createThumbnailSlice, type ThumbnailSlice } from "./thumbnailSlice";
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 export { liveTime } from "./liveTime";
 
-import type { TimelineElement, TimelineElementPatch } from "./timelineElement";
+import type {
+  TimelineElement,
+  TimelineElementPatch,
+  SubCompositionHostState,
+} from "./timelineElement";
 
-export type { TimelineElement };
+export type { TimelineElement, SubCompositionHostState };
 export type ZoomMode = "fit" | "manual";
 type TimelineTool = "select" | "razor";
 
@@ -212,6 +216,14 @@ interface PlayerState
    */
   domClipChildren: DomClipChild[];
   setDomClipChildren: (children: DomClipChild[]) => void;
+  /**
+   * Host-element state for every id'd element inside a sub-composition, keyed by
+   * dom id. Collected from the live preview because it is the only place that
+   * sees it: these elements are filtered out of `elements` before the flat store
+   * is built, and the clip manifest carries timing, not attributes.
+   */
+  subCompositionHostState: Map<string, SubCompositionHostState>;
+  setSubCompositionHostState: (state: Map<string, SubCompositionHostState>) => void;
 }
 
 /** A sub-comp DOM-only timeline child (no data-start) and its nesting context. */
@@ -284,6 +296,7 @@ export function createTimelineResetState() {
     clipManifest: null,
     clipParentMap: new Map<string, string>(),
     domClipChildren: [],
+    subCompositionHostState: new Map<string, SubCompositionHostState>(),
   };
 }
 
@@ -430,6 +443,8 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   setClipParentMap: (map) => set({ clipParentMap: map }),
   domClipChildren: [],
   setDomClipChildren: (children) => set({ domClipChildren: children }),
+  subCompositionHostState: new Map(),
+  setSubCompositionHostState: (state) => set({ subCompositionHostState: state }),
 
   setIsPlaying: (playing) => {
     if (get().isPlaying === playing) return;

package/src/player/store/timelineElement.ts

@@ -118,3 +118,24 @@ export type TimelineElementPatch = Partial<
     | "audioGroupAutomation"
   >
 >;
+
+/**
+ * The `data-*` state an expanded sub-composition child needs but cannot reach.
+ *
+ * A child row is synthesized from a manifest clip with no element to read, and
+ * for a real sub-composition it has no flat store twin either: such clips are
+ * dropped before the flat store is built. Read off the live preview instead
+ * (`collectSubCompositionHostState`) and carried on the store by dom id.
+ *
+ * Without it the eye reported every hidden child visible, so clicking it wrote
+ * `data-hidden` a second time instead of removing it, and the element could
+ * never be shown again, not even after a reload, since the attribute is in the
+ * source.
+ */
+export interface SubCompositionHostState {
+  hidden?: boolean;
+  timelineLocked?: boolean;
+  timelineRole?: string;
+  fxChain?: string;
+  automation?: string;
+}

package/src/utils/studioFileVersion.test.ts

@@ -1,12 +1,16 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   consumeStudioWriteToken,
+  createStudioWriteToken,
   markStudioWriteToken,
   resetStudioWriteTokens,
   studioExpectedFileVersion,
   studioFileContentVersion,
+  studioWriteHeaders,
 } from "./studioFileVersion";
 
+afterEach(() => vi.unstubAllGlobals());
+
 describe("studioFileContentVersion", () => {
   it("matches the strong SHA-256 ETag format used by studio-server", async () => {
     await expect(studioFileContentVersion("abc")).resolves.toBe(
@@ -42,6 +46,38 @@ describe("studioFileContentVersion", () => {
 });
 
 describe("studio write-token echo identity", () => {
+  it("prefers the platform randomUUID implementation", () => {
+    const randomUUID = vi.fn(() => "11111111-2222-4333-8444-555555555555");
+    vi.stubGlobal("crypto", { randomUUID });
+    resetStudioWriteTokens();
+
+    expect(studioWriteHeaders()).toEqual({
+      "X-Hyperframes-Write-Token": "11111111-2222-4333-8444-555555555555",
+    });
+    expect(randomUUID).toHaveBeenCalledOnce();
+    expect(consumeStudioWriteToken("11111111-2222-4333-8444-555555555555")).toBe(true);
+  });
+
+  it("creates an RFC 4122 UUID-v4 token from getRandomValues when randomUUID is unavailable", () => {
+    const source = Uint8Array.from({ length: 16 }, (_, index) => index);
+    vi.stubGlobal("crypto", {
+      getRandomValues: vi.fn((target: Uint8Array) => {
+        target.set(source);
+        return target;
+      }),
+    });
+
+    expect(createStudioWriteToken()).toBe("00010203-0405-4607-8809-0a0b0c0d0e0f");
+  });
+
+  it("fails explicitly when Web Crypto cannot provide secure random bytes", () => {
+    vi.stubGlobal("crypto", {});
+
+    expect(() => createStudioWriteToken()).toThrow(
+      "Web Crypto getRandomValues is required for Studio write identity",
+    );
+  });
+
   it("suppresses exactly one matching API write receipt without hiding path-only external writes", () => {
     resetStudioWriteTokens();
     markStudioWriteToken("studio-write-1");

package/src/utils/studioFileVersion.ts

@@ -48,8 +48,18 @@ export async function studioExpectedFileVersion(
   return versions.get(path);
 }
 
-function createStudioWriteToken(): string {
-  return globalThis.crypto.randomUUID();
+export function createStudioWriteToken(): string {
+  const webCrypto = globalThis.crypto;
+  if (typeof webCrypto?.randomUUID === "function") return webCrypto.randomUUID();
+  if (typeof webCrypto?.getRandomValues !== "function") {
+    throw new Error("Web Crypto getRandomValues is required for Studio write identity");
+  }
+
+  const bytes = webCrypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
 
 /**

package/src/utils/studioSaveDiagnostics.test.ts

@@ -1,4 +1,8 @@
 import { describe, expect, it, vi } from "vitest";
+
+const trackStudioEvent = vi.hoisted(() => vi.fn());
+vi.mock("./studioTelemetry", () => ({ trackStudioEvent }));
+
 import {
   StudioFileConflictError,
   StudioSaveHttpError,
@@ -6,6 +10,7 @@ import {
   buildStudioSaveFailureProperties,
   getStudioSaveStatusCode,
   retryStudioSave,
+  trackStudioEditBlocked,
 } from "./studioSaveDiagnostics";
 
 describe("studio save diagnostics", () => {
@@ -51,6 +56,30 @@ describe("studio save diagnostics", () => {
     });
   });
 
+  it("emits expected direct-edit refusals on edit_blocked", () => {
+    const error = new Error("This animation is computed at runtime");
+
+    trackStudioEditBlocked({
+      source: "gsap_commit",
+      error,
+      filePath: "index.html",
+      mutationType: "drag",
+    });
+
+    expect(trackStudioEvent).toHaveBeenCalledWith("edit_blocked", {
+      source: "gsap_commit",
+      error_message: error.message,
+      status_code: null,
+      file_path: "index.html",
+      mutation_type: "drag",
+      attempt: undefined,
+      label: undefined,
+      target_id: undefined,
+      target_selector: undefined,
+      target_source_file: undefined,
+    });
+  });
+
   it("reads nested status codes from error causes", () => {
     const cause = new StudioSaveHttpError("Too many requests", 429);
     const error = new Error("retry wrapper") as Error & { cause?: unknown };

package/src/utils/studioSaveDiagnostics.ts

@@ -172,6 +172,10 @@ export function trackStudioSaveFailure(input: StudioSaveFailureInput): void {
   trackStudioEvent("save_failure", buildStudioSaveFailureProperties(input));
 }
 
+export function trackStudioEditBlocked(input: StudioSaveFailureInput): void {
+  trackStudioEvent("edit_blocked", buildStudioSaveFailureProperties(input));
+}
+
 export async function createStudioSaveHttpError(
   response: Response,
   fallbackMessage: string,

package/src/webmcp/StudioAgentTools.tsx

@@ -1,8 +1,8 @@
-import { useCallback } from "react";
-import { useDomEditSelectionContext } from "../contexts/DomEditContext";
+import { useCallback, useMemo } from "react";
+import { useDomEditActionsContext, useDomEditSelectionContext } from "../contexts/DomEditContext";
 import { useStudioShellContext } from "../contexts/StudioContext";
 import { usePlayerStore } from "../player";
-import { useStudioAgentTools } from "./useStudioAgentTools";
+import { useStudioAgentTools, type StudioAgentToolsDeps } from "./useStudioAgentTools";
 import type { StudioLookSnapshot } from "./tools/lookTools";
 
 /**
@@ -12,14 +12,32 @@ import type { StudioLookSnapshot } from "./tools/lookTools";
  * contexts are only readable below `DomEditProvider`, which `App` renders, and
  * `App.tsx` sits three lines under the 600-line cap.
  *
- * The player store is read IMPERATIVELY through `getState()` inside the
- * snapshot callback rather than subscribed to. Subscribing to `currentTime`
- * would re-render this component on every animation frame during playback for
- * a value nothing here displays.
+ * The player store is read IMPERATIVELY through `getState()` rather than
+ * subscribed to. Subscribing to `currentTime` would re-render this component on
+ * every animation frame during playback for a value nothing here displays.
  */
 export function StudioAgentTools() {
-  const { projectId, activeCompPath, editHistory } = useStudioShellContext();
-  const { domEditSelection, selectedGsapAnimations } = useDomEditSelectionContext();
+  const { projectId, activeCompPath, editHistory, writeBlockedReason } = useStudioShellContext();
+  const {
+    domEditSelection,
+    selectedGsapAnimations,
+    gsapMultipleTimelines,
+    gsapUnsupportedTimelinePattern,
+  } = useDomEditSelectionContext();
+  const {
+    previewIframeRef,
+    buildDomSelectionFromTarget,
+    applyDomSelection,
+    handleDomTextCommit,
+    handleDomStyleCommit,
+    handleDomPathOffsetCommit,
+    handleDomBoxSizeCommit,
+    handleDomRotationCommit,
+    handleGsapAddAnimation,
+    handleGsapUpdateMeta,
+    handleGsapAddKeyframeBatch,
+    handleGsapDeleteAnimation,
+  } = useDomEditActionsContext();
 
   const getSnapshot = useCallback((): StudioLookSnapshot => {
     const player = usePlayerStore.getState();
@@ -41,6 +59,83 @@ export function StudioAgentTools() {
     };
   }, [projectId, activeCompPath, domEditSelection, selectedGsapAnimations, editHistory]);
 
-  useStudioAgentTools({ getSnapshot });
+  const deps = useMemo<StudioAgentToolsDeps>(
+    () => ({
+      getSnapshot,
+      getPreviewDocument: () => previewIframeRef.current?.contentDocument ?? null,
+      buildSelection: (element) => buildDomSelectionFromTarget(element),
+      applySelection: (selection) => applyDomSelection(selection, { revealPanel: true }),
+      requestSeek: (time) => usePlayerStore.getState().requestSeek(time),
+      readPlayhead: () => {
+        const player = usePlayerStore.getState();
+        return {
+          currentTime: player.currentTime,
+          duration: player.duration,
+          isPlaying: player.isPlaying,
+        };
+      },
+      getProjectId: () => projectId,
+      getCompositionPath: () => activeCompPath,
+      // HEAD, not GET: the tool only needs to know the frame renders. Pulling
+      // the PNG here would download it once for nothing, since the agent
+      // fetches the URL itself.
+      probeFrame: async (url) => {
+        try {
+          const response = await fetch(url, { method: "HEAD" });
+          return { ok: response.ok, status: response.status };
+        } catch {
+          return { ok: false, status: 0 };
+        }
+      },
+      wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+      getCurrentSelection: () => domEditSelection,
+      getWriteBlockedReason: () => writeBlockedReason,
+      setText: (value, fieldKey) => handleDomTextCommit(value, fieldKey),
+      setStyle: (property, value) => handleDomStyleCommit(property, value),
+      // Measured, not authored: the tool compares this before and after to
+      // tell a real change from a handler that did nothing and resolved.
+      readBox: (selection) => {
+        const rect = selection.element.getBoundingClientRect();
+        return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+      },
+      moveTo: (selection, next) => handleDomPathOffsetCommit(selection, next),
+      resizeTo: (selection, next) => handleDomBoxSizeCommit(selection, next),
+      rotateTo: (selection, next) => handleDomRotationCommit(selection, next),
+      addAnimation: (method) => handleGsapAddAnimation(method),
+      updateAnimation: (animationId, updates) => handleGsapUpdateMeta(animationId, updates),
+      addKeyframe: (animationId, percent, properties) =>
+        handleGsapAddKeyframeBatch(animationId, percent, properties),
+      deleteAnimation: (animationId) => handleGsapDeleteAnimation(animationId),
+      getGsapDiagnostics: () => ({
+        animations: selectedGsapAnimations,
+        multipleTimelines: gsapMultipleTimelines,
+        unsupportedTimelinePattern: gsapUnsupportedTimelinePattern,
+      }),
+    }),
+    [
+      getSnapshot,
+      previewIframeRef,
+      buildDomSelectionFromTarget,
+      applyDomSelection,
+      projectId,
+      activeCompPath,
+      writeBlockedReason,
+      handleDomTextCommit,
+      handleDomStyleCommit,
+      handleDomPathOffsetCommit,
+      handleDomBoxSizeCommit,
+      handleDomRotationCommit,
+      handleGsapAddAnimation,
+      handleGsapUpdateMeta,
+      handleGsapAddKeyframeBatch,
+      handleGsapDeleteAnimation,
+      domEditSelection,
+      selectedGsapAnimations,
+      gsapMultipleTimelines,
+      gsapUnsupportedTimelinePattern,
+    ],
+  );
+
+  useStudioAgentTools(deps);
   return null;
 }

package/src/webmcp/toolResult.ts

@@ -36,7 +36,7 @@ export function toolOk<T extends object>(value: T): { ok: true } & T {
   return { ok: true, ...value };
 }
 
-function toolFailure(kind: ToolFailureKind, reason: string, hint?: string): ToolFailure {
+export function toolFailure(kind: ToolFailureKind, reason: string, hint?: string): ToolFailure {
   return hint ? { ok: false, kind, reason, hint } : { ok: false, kind, reason };
 }