npm - @hyperframes/studio - Versions diffs - 0.6.100 → 0.6.102 - Mend

@hyperframes/studio 0.6.100 → 0.6.102

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (44) hide show

package/dist/assets/index-BITwbxi-.css +1 -0
package/dist/assets/{index-CKWBqyRd.js → index-BZKngETE.js} +1 -1
package/dist/assets/index-BzjItfjX.js +296 -0
package/dist/assets/{index-gpSohHUn.js → index-C0vMHtMH.js} +1 -1
package/dist/index.html +2 -2
package/package.json +5 -5
package/src/App.tsx +2 -1
package/src/components/editor/PropertyPanel.tsx +24 -16
package/src/components/editor/manualEditingAvailability.ts +5 -3
package/src/components/nle/NLELayout.tsx +89 -1
package/src/hooks/gsapKeyframeCacheHelpers.test.ts +121 -0
package/src/hooks/gsapKeyframeCacheHelpers.ts +48 -2
package/src/hooks/gsapScriptCommitHelpers.ts +8 -5
package/src/hooks/gsapScriptCommitTypes.ts +6 -0
package/src/hooks/gsapTargetCache.ts +65 -0
package/src/hooks/useAppHotkeys.ts +10 -0
package/src/hooks/useDomEditCommits.ts +6 -5
package/src/hooks/useDomEditSession.ts +6 -1
package/src/hooks/useDomGeometryCommits.ts +1 -36
package/src/hooks/useElementLifecycleOps.ts +5 -0
package/src/hooks/useGsapAnimationOps.ts +46 -9
package/src/hooks/useGsapScriptCommits.ts +22 -3
package/src/hooks/useGsapTweenCache.ts +10 -12
package/src/hooks/useRazorSplit.ts +3 -0
package/src/hooks/useSafeGsapCommitMutation.ts +1 -14
package/src/hooks/useSdkSession.ts +15 -12
package/src/hooks/useTimelineEditing.ts +23 -3
package/src/player/components/Timeline.tsx +31 -18
package/src/player/components/TimelineClip.tsx +3 -3
package/src/player/components/useResolvedTimelineEditCallbacks.ts +30 -0
package/src/player/hooks/useExpandedTimelineElements.test.ts +91 -0
package/src/player/hooks/useExpandedTimelineElements.ts +153 -0
package/src/player/hooks/useTimelineSyncCallbacks.ts +22 -0
package/src/player/store/playerStore.ts +22 -8
package/src/telemetry/events.test.ts +16 -1
package/src/telemetry/events.ts +15 -0
package/src/utils/blockCategories.ts +2 -2
package/src/utils/sdkShadow.test.ts +232 -2
package/src/utils/sdkShadow.ts +230 -2
package/src/utils/sdkShadowGsapFidelity.ts +208 -0
package/src/utils/studioHelpers.test.ts +25 -1
package/src/utils/studioHelpers.ts +54 -28
package/dist/assets/index-B62bDCQv.css +0 -1
package/dist/assets/index-BkT9VKwz.js +0 -296

package/src/utils/sdkShadow.test.ts CHANGED Viewed

@@ -1,8 +1,30 @@
-import { describe, expect, it } from "vitest";
-import { patchOpsToSdkEditOps, SdkShadowMismatch } from "./sdkShadow";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import {
+  patchOpsToSdkEditOps,
+  runShadowDelete,
+  runShadowTiming,
+  runShadowGsapTween,
+  runShadowGsapFidelity,
+  gsapFidelityMismatches,
+  resolveGsapFidelityArgs,
+  SdkShadowMismatch,
+} from "./sdkShadow";
+import type { ShadowGsapOp } from "./sdkShadow";
 import type { PatchOperation } from "./sourcePatcher";
 import { openComposition } from "@hyperframes/sdk";
+// Capture sdk_shadow_dispatch telemetry for the non-PatchOperation runners.
+const trackedEvents: Array<{ event: string; props: Record<string, unknown> }> = [];
+vi.mock("./studioTelemetry", () => ({
+  trackStudioEvent: (event: string, props: Record<string, unknown>) =>
+    trackedEvents.push({ event, props }),
+}));
+beforeEach(() => {
+  trackedEvents.length = 0;
+});
+const lastShadow = () =>
+  trackedEvents.filter((e) => e.event === "sdk_shadow_dispatch").at(-1)?.props;
 const BASE_HTML = /* html */ `<!DOCTYPE html>
 <html><body>
   <div data-hf-id="hf-box" style="color: red; width: 100px;" data-name="box">Hello</div>
@@ -144,3 +166,211 @@ describe("sdkShadowDispatch (integration)", () => {
     });
   });
 });
+const TIMING_HTML = /* html */ `<!DOCTYPE html>
+<html><body>
+  <div data-hf-id="hf-clip" data-start="0" data-duration="1" data-track="0">clip</div>
+</body></html>`;
+const GSAP_HTML = `<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px">
+  <div data-hf-id="hf-box" style="opacity:0"></div>
+  <script>var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { opacity: 1, duration: 0.5 }, 0.2);
+window.__timelines["t"] = tl;</script>
+</div>`;
+const NO_TIMELINE_HTML = `<div data-hf-id="hf-stage" data-hf-root>
+  <div data-hf-id="hf-box"></div>
+  <script>gsap.defaults({ ease: "power1.out" });
+window.__timelines = {};</script>
+</div>`;
+describe("runShadowDelete", () => {
+  it("removes the element from the SDK session and reports parity", async () => {
+    const session = await openComposition(BASE_HTML);
+    runShadowDelete(session, "hf-box");
+    expect(session.getElement("hf-box")).toBeNull();
+    expect(lastShadow()).toMatchObject({ op: "delete", dispatched: true, mismatchCount: 0 });
+  });
+  it("reports no_hf_id when selection has no hf-id", async () => {
+    const session = await openComposition(BASE_HTML);
+    runShadowDelete(session, null);
+    expect(lastShadow()).toMatchObject({ op: "delete", dispatched: false, reason: "no_hf_id" });
+  });
+  it("reports cannot_dispatch when the element is not addressable", async () => {
+    const session = await openComposition(BASE_HTML);
+    runShadowDelete(session, "hf-missing");
+    expect(lastShadow()).toMatchObject({
+      op: "delete",
+      dispatched: false,
+      reason: "cannot_dispatch",
+    });
+  });
+});
+describe("runShadowTiming", () => {
+  it("applies timing and reports parity against the snapshot", async () => {
+    const session = await openComposition(TIMING_HTML);
+    runShadowTiming(session, "hf-clip", { start: 2, duration: 3, trackIndex: 1 });
+    const el = session.getElement("hf-clip");
+    expect(el?.start).toBe(2);
+    expect(el?.duration).toBe(3);
+    expect(el?.trackIndex).toBe(1);
+    expect(lastShadow()).toMatchObject({ op: "timing", dispatched: true, mismatchCount: 0 });
+  });
+});
+describe("runShadowGsapTween", () => {
+  it("add reports success and the new tween lands on the target's animationIds", async () => {
+    const session = await openComposition(GSAP_HTML);
+    const before = session.getElement("hf-box")?.animationIds.length ?? 0;
+    runShadowGsapTween(session, {
+      kind: "add",
+      target: "hf-box",
+      tween: { method: "to", properties: { x: 100 }, duration: 0.5 },
+    });
+    expect(session.getElement("hf-box")!.animationIds.length).toBe(before + 1);
+    expect(lastShadow()).toMatchObject({ op: "gsap", dispatched: true, mismatchCount: 0 });
+  });
+  it("remove drops the tween from animationIds and reports parity", async () => {
+    const session = await openComposition(GSAP_HTML);
+    const animationId = session.getElement("hf-box")?.animationIds[0];
+    expect(animationId).toBeDefined();
+    runShadowGsapTween(session, { kind: "remove", animationId: animationId! });
+    expect(session.getElement("hf-box")?.animationIds ?? []).not.toContain(animationId);
+    expect(lastShadow()).toMatchObject({ op: "gsap", dispatched: true, mismatchCount: 0 });
+  });
+  it("reports cannot_dispatch (E_NO_GSAP_TIMELINE) when the script has no timeline", async () => {
+    const session = await openComposition(NO_TIMELINE_HTML);
+    runShadowGsapTween(session, {
+      kind: "add",
+      target: "hf-box",
+      tween: { method: "to", properties: { x: 100 } },
+    });
+    expect(lastShadow()).toMatchObject({
+      op: "gsap",
+      dispatched: false,
+      reason: "cannot_dispatch",
+      code: "E_NO_GSAP_TIMELINE",
+    });
+  });
+});
+const SCRIPT_A = `var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { opacity: 1, duration: 0.5 }, 0.2);
+window.__timelines["t"] = tl;`;
+describe("gsapFidelityMismatches", () => {
+  it("returns no mismatches for identical scripts", () => {
+    expect(gsapFidelityMismatches(SCRIPT_A, SCRIPT_A)).toEqual([]);
+  });
+  it("flags a per-field value drift (duration)", () => {
+    const drifted = SCRIPT_A.replace("duration: 0.5", "duration: 0.9");
+    const mismatches = gsapFidelityMismatches(drifted, SCRIPT_A);
+    expect(mismatches.some((m) => m.property === "duration")).toBe(true);
+  });
+  it("flags a tween present in one script but not the other", () => {
+    const empty = `var tl = gsap.timeline({ paused: true });
+window.__timelines["t"] = tl;`;
+    const mismatches = gsapFidelityMismatches(empty, SCRIPT_A);
+    expect(mismatches.some((m) => m.property === "tween")).toBe(true);
+  });
+  it("does NOT flag property key-order differences (canonical compare)", () => {
+    const ab = `var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { x: 10, y: 20, duration: 0.5 }, 0);
+window.__timelines["t"] = tl;`;
+    const ba = `var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { y: 20, x: 10, duration: 0.5 }, 0);
+window.__timelines["t"] = tl;`;
+    expect(gsapFidelityMismatches(ab, ba)).toEqual([]);
+  });
+  it("does NOT flag number-vs-string-equivalent property values", () => {
+    const numeric = `var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { opacity: 1, duration: 0.5 }, 0);
+window.__timelines["t"] = tl;`;
+    const stringy = `var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { opacity: "1", duration: 0.5 }, 0);
+window.__timelines["t"] = tl;`;
+    expect(gsapFidelityMismatches(numeric, stringy)).toEqual([]);
+  });
+});
+describe("runShadowGsapFidelity", () => {
+  const BEFORE_HTML = `<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px">
+  <div data-hf-id="hf-box" style="opacity:0"></div>
+  <script>var tl = gsap.timeline({ paused: true });
+window.__timelines["t"] = tl;</script>
+</div>`;
+  it("reports zero mismatches when the SDK output matches the server script", async () => {
+    // Produce the "server" script by applying the same op via the SDK, so a
+    // faithful SDK writer must reproduce it exactly.
+    const ref = await openComposition(BEFORE_HTML);
+    const op = {
+      kind: "add",
+      target: "hf-box",
+      tween: { method: "to", properties: { x: 100 }, duration: 0.5 },
+    } as const;
+    ref.addGsapTween(op.target, op.tween);
+    const serverScript =
+      ref.serialize().match(/<script\b[^>]*>([\s\S]*?)<\/script[^>]*>/i)?.[1] ?? "";
+    await runShadowGsapFidelity(BEFORE_HTML, op, serverScript);
+    expect(lastShadow()).toMatchObject({ op: "gsap_fidelity", dispatched: true, mismatchCount: 0 });
+  });
+  it("reports mismatches when the server script diverges", async () => {
+    const op = {
+      kind: "add",
+      target: "hf-box",
+      tween: { method: "to", properties: { x: 100 }, duration: 0.5 },
+    } as const;
+    const ref = await openComposition(BEFORE_HTML);
+    ref.addGsapTween(op.target, op.tween);
+    const serverScript = (
+      ref.serialize().match(/<script\b[^>]*>([\s\S]*?)<\/script[^>]*>/i)?.[1] ?? ""
+    ).replace("100", "999");
+    await runShadowGsapFidelity(BEFORE_HTML, op, serverScript);
+    const ev = lastShadow();
+    expect(ev).toMatchObject({ op: "gsap_fidelity", dispatched: true });
+    expect(ev?.mismatchCount as number).toBeGreaterThan(0);
+  });
+});
+describe("resolveGsapFidelityArgs (chokepoint wiring)", () => {
+  const op: ShadowGsapOp = { kind: "remove", animationId: "a-1" };
+  const session = {} as object;
+  it("returns narrowed args when session, op, before, and serverScript are all present", () => {
+    expect(resolveGsapFidelityArgs(session, op, "<html>before</html>", "tl.to(...)")).toEqual({
+      before: "<html>before</html>",
+      op,
+      serverScript: "tl.to(...)",
+    });
+  });
+  it("returns null when no session (shadow not wired)", () => {
+    expect(resolveGsapFidelityArgs(null, op, "before", "script")).toBeNull();
+  });
+  it("returns null when no shadowGsapOp (non-meta edit, e.g. property/keyframe)", () => {
+    expect(resolveGsapFidelityArgs(session, undefined, "before", "script")).toBeNull();
+  });
+  it("returns null when serverScript is null (composition has no GSAP script)", () => {
+    expect(resolveGsapFidelityArgs(session, op, "before", null)).toBeNull();
+  });
+  it("returns null when before is null", () => {
+    expect(resolveGsapFidelityArgs(session, op, null, "script")).toBeNull();
+  });
+});

package/src/utils/sdkShadow.ts CHANGED Viewed

@@ -9,7 +9,7 @@
  */
 import type { Composition } from "@hyperframes/sdk";
-import type { EditOp } from "@hyperframes/sdk";
+import type { EditOp, GsapTweenSpec } from "@hyperframes/sdk";
 import { STUDIO_SDK_SHADOW_ENABLED } from "../components/editor/manualEditingAvailability";
 import { trackStudioEvent } from "./studioTelemetry";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
@@ -182,6 +182,26 @@ export function sdkShadowDispatch(
  * Despite the telemetry focus, this function does mutate the SDK session — it
  * is not read-only. No-op when STUDIO_SDK_SHADOW_ENABLED is false.
  */
+// Property-path mismatches carry user content (inline-style values, edited
+// text) in expected/actual. Scrub before telemetry: fully redact text-content
+// values, length-cap the rest. The in-memory parity result keeps raw values.
+function redactValueForTelemetry(
+  property: string | undefined,
+  value: string | null | undefined,
+): string | null | undefined {
+  if (value == null) return value;
+  if (property === "text") return `[redacted len=${value.length}]`;
+  return value.length > 64 ? `${value.slice(0, 64)}…` : value;
+}
+function redactMismatchesForTelemetry(mismatches: SdkShadowMismatch[]): SdkShadowMismatch[] {
+  return mismatches.map((m) => ({
+    ...m,
+    expected: redactValueForTelemetry(m.property, m.expected),
+    actual: redactValueForTelemetry(m.property, m.actual),
+  }));
+}
 export function runShadowDispatch(
   session: Composition,
   selection: DomEditSelection,
@@ -191,6 +211,7 @@ export function runShadowDispatch(
   const hfId = selection.hfId;
   if (!hfId) {
     trackStudioEvent("sdk_shadow_dispatch", {
+      op: "property",
       dispatched: false,
       reason: "no_hf_id",
       mismatchCount: 0,
@@ -199,8 +220,215 @@ export function runShadowDispatch(
   }
   const result = sdkShadowDispatch(session, hfId, ops);
   trackStudioEvent("sdk_shadow_dispatch", {
+    op: "property",
     dispatched: result.dispatched,
     mismatchCount: result.mismatches.length,
-    mismatches: JSON.stringify(result.mismatches),
+    mismatches: JSON.stringify(redactMismatchesForTelemetry(result.mismatches)),
+  });
+}
+// ─── Shadow for non-PatchOperation ops (delete / timing / GSAP) ───────────────
+//
+// These ops never flow through persistDomEditOperations, so the property-path
+// shadow above never sees them. Each runner keeps the server authoritative and
+// only observes the SDK: can() pre-checks addressing/validity (pure, no
+// mutation — works even for GSAP, which has no element-snapshot value), then a
+// dispatch into the live session with a snapshot-based parity check.
+//
+// Parity coverage by op:
+//   delete  → getElement(id) === null               (full)
+//   timing  → snapshot.start/duration/trackIndex     (full)
+//   gsap    → tween id present/absent in animationIds (existence only — the
+//             tween's property values are script-level, not in the snapshot)
+/**
+ * can()-gated shadow dispatch. Emits sdk_shadow_dispatch tagged with `opLabel`.
+ * Mutates the SDK session (not read-only); server stays authoritative.
+ * No-op when STUDIO_SDK_SHADOW_ENABLED is false.
+ */
+function runShadowEditOp(
+  session: Composition,
+  op: EditOp,
+  opLabel: string,
+  dispatchAndCheck: () => SdkShadowMismatch[],
+): void {
+  const verdict = session.can(op);
+  if (!verdict.ok) {
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: opLabel,
+      dispatched: false,
+      reason: "cannot_dispatch",
+      code: verdict.code,
+      mismatchCount: 0,
+    });
+    return;
+  }
+  let mismatches: SdkShadowMismatch[];
+  try {
+    mismatches = dispatchAndCheck();
+  } catch (err) {
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: opLabel,
+      dispatched: false,
+      reason: "dispatch_error",
+      error: String(err),
+      mismatchCount: 0,
+    });
+    return;
+  }
+  trackStudioEvent("sdk_shadow_dispatch", {
+    op: opLabel,
+    dispatched: true,
+    mismatchCount: mismatches.length,
+    mismatches: JSON.stringify(mismatches),
+  });
+}
+/** Shadow an element delete. Parity: the element is gone from the SDK session. */
+export function runShadowDelete(session: Composition, hfId: string | null | undefined): void {
+  if (!STUDIO_SDK_SHADOW_ENABLED) return;
+  if (!hfId) {
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: "delete",
+      dispatched: false,
+      reason: "no_hf_id",
+      mismatchCount: 0,
+    });
+    return;
+  }
+  const op: EditOp = { type: "removeElement", target: hfId };
+  runShadowEditOp(session, op, "delete", () => {
+    session.batch(() => session.dispatch(op));
+    return session.getElement(hfId)
+      ? [
+          {
+            kind: "value_mismatch",
+            hfId,
+            property: "exists",
+            expected: "removed",
+            actual: "present",
+          },
+        ]
+      : [];
+  });
+}
+export interface ShadowTiming {
+  start?: number;
+  duration?: number;
+  trackIndex?: number;
+}
+/** Shadow a timing edit. Parity: snapshot start/duration/trackIndex match. */
+export function runShadowTiming(
+  session: Composition,
+  hfId: string | null | undefined,
+  timing: ShadowTiming,
+): void {
+  if (!STUDIO_SDK_SHADOW_ENABLED) return;
+  if (!hfId) {
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: "timing",
+      dispatched: false,
+      reason: "no_hf_id",
+      mismatchCount: 0,
+    });
+    return;
+  }
+  const op: EditOp = { type: "setTiming", target: hfId, ...timing };
+  runShadowEditOp(session, op, "timing", () => {
+    session.batch(() => session.dispatch(op));
+    const el = session.getElement(hfId);
+    const mismatches: SdkShadowMismatch[] = [];
+    const fields: Array<[keyof ShadowTiming, number | null | undefined]> = [
+      ["start", el?.start],
+      ["duration", el?.duration],
+      ["trackIndex", el?.trackIndex],
+    ];
+    for (const [key, actual] of fields) {
+      const expected = timing[key];
+      if (expected !== undefined && actual !== expected) {
+        mismatches.push({
+          kind: "value_mismatch",
+          hfId,
+          property: key,
+          expected: String(expected),
+          actual: actual == null ? null : String(actual),
+        });
+      }
+    }
+    return mismatches;
   });
 }
+export type ShadowGsapOp =
+  | { kind: "add"; target: string; tween: GsapTweenSpec }
+  | { kind: "set"; animationId: string; properties: Partial<GsapTweenSpec> }
+  | { kind: "remove"; animationId: string };
+/**
+ * Shadow a GSAP tween mutation (add / set / remove). The server's animationId
+ * shares the SDK's id-space (both derive `targetSelector-method-position` from
+ * the same acorn parser — see sdk assignStableIds), so it is dispatchable as-is.
+ *
+ * Parity via the now-populated ElementSnapshot.animationIds:
+ *   add    → the returned tween id is present on the target element
+ *   remove → the id is gone from every element
+ *   set    → existence only (the SDK exposes no per-tween property reader; value
+ *            fidelity would need serialize()-script round-trip diffing).
+ */
+export function runShadowGsapTween(session: Composition, gsapOp: ShadowGsapOp): void {
+  if (!STUDIO_SDK_SHADOW_ENABLED) return;
+  const op: EditOp =
+    gsapOp.kind === "add"
+      ? { type: "addGsapTween", target: gsapOp.target, tween: gsapOp.tween }
+      : gsapOp.kind === "set"
+        ? { type: "setGsapTween", animationId: gsapOp.animationId, properties: gsapOp.properties }
+        : { type: "removeGsapTween", animationId: gsapOp.animationId };
+  // fallow-ignore-next-line complexity
+  runShadowEditOp(session, op, "gsap", () => {
+    let newId: string | undefined;
+    session.batch(() => {
+      if (gsapOp.kind === "add") newId = session.addGsapTween(gsapOp.target, gsapOp.tween);
+      else session.dispatch(op);
+    });
+    if (gsapOp.kind === "add") {
+      const onTarget = session.getElement(gsapOp.target)?.animationIds ?? [];
+      if (!newId || !onTarget.includes(newId)) {
+        return [
+          {
+            kind: "value_mismatch",
+            hfId: gsapOp.target,
+            property: "animationIds",
+            expected: newId ?? "non-empty",
+            actual: onTarget.join(",") || null,
+          },
+        ];
+      }
+    } else if (gsapOp.kind === "remove") {
+      const stillPresent = session
+        .getElements()
+        .some((el) => el.animationIds.includes(gsapOp.animationId));
+      if (stillPresent) {
+        return [
+          {
+            kind: "value_mismatch",
+            hfId: gsapOp.animationId,
+            property: "animationIds",
+            expected: "removed",
+            actual: "present",
+          },
+        ];
+      }
+    }
+    return [];
+  });
+}
+// GSAP value-fidelity diff lives in its own module to keep this file under the
+// 600-line studio cap; re-exported here so the shadow surface stays in one place.
+export {
+  gsapFidelityMismatches,
+  resolveGsapFidelityArgs,
+  runShadowGsapFidelity,
+} from "./sdkShadowGsapFidelity";