npm - @hyperframes/studio - Versions diffs - 0.6.111 → 0.6.113 - Mend

@hyperframes/studio 0.6.111 → 0.6.113

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 (14) hide show

package/dist/assets/index-B8Qzwcpc.js +265 -0
package/dist/assets/{index-x0c2-zQN.js → index-C0tFko2e.js} +1 -1
package/dist/assets/{index-_IV-vm9l.js → index-DSLrl2tB.js} +24 -24
package/dist/index.html +1 -1
package/package.json +5 -5
package/src/hooks/useDomEditCommits.ts +4 -0
package/src/hooks/useDomEditSession.ts +9 -1
package/src/hooks/useElementLifecycleOps.ts +9 -1
package/src/hooks/useGsapAnimationOps.ts +96 -0
package/src/hooks/useSdkSession.ts +29 -16
package/src/utils/sdkCutover.ts +80 -0
package/src/utils/sdkResolverShadow.test.ts +44 -1
package/src/utils/sdkResolverShadow.ts +28 -3
package/dist/assets/index-B7S86vK1.js +0 -370

package/dist/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>HyperFrames Studio</title>
-    <script type="module" crossorigin src="/assets/index-B7S86vK1.js"></script>
+    <script type="module" crossorigin src="/assets/index-B8Qzwcpc.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DP8pPIk2.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.6.111",
+  "version": "0.6.113",
   "description": "",
   "repository": {
     "type": "git",
@@ -36,9 +36,9 @@
     "dompurify": "^3.2.4",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.6.111",
-    "@hyperframes/sdk": "0.6.111",
-    "@hyperframes/player": "0.6.111"
+    "@hyperframes/sdk": "0.6.113",
+    "@hyperframes/player": "0.6.113",
+    "@hyperframes/core": "0.6.113"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -52,7 +52,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.6.111"
+    "@hyperframes/producer": "0.6.113"
   },
   "peerDependencies": {
     "react": "19",

package/src/hooks/useDomEditCommits.ts CHANGED Viewed

@@ -82,6 +82,8 @@ export interface UseDomEditCommitsParams {
   ) => Promise<boolean>;
   /** Stage 7 §3.1: called before the server-side delete path; returns true if SDK handled it. */
   onTrySdkDelete?: (hfId: string, originalContent: string, targetPath: string) => Promise<boolean>;
+  /** Resolver-shadow tripwire for z-index reorder targets (telemetry-only, decoupled from cutover). */
+  onReorderShadow?: (targets: string[]) => void;
 }
 export function useDomEditCommits({
@@ -105,6 +107,7 @@ export function useDomEditCommits({
   forceReloadSdkSession,
   onTrySdkPersist,
   onTrySdkDelete,
+  onReorderShadow,
 }: UseDomEditCommitsParams) {
   const resolveImportedFontAsset = useCallback(
     (fontFamilyValue: string): ImportedFontAsset | null => {
@@ -324,6 +327,7 @@ export function useDomEditCommits({
     reloadPreview,
     clearDomSelection,
     onTrySdkDelete,
+    onReorderShadow,
     forceReloadSdkSession,
     commitPositionPatchToHtml,
   });

package/src/hooks/useDomEditSession.ts CHANGED Viewed

@@ -6,7 +6,7 @@ import type { PatchTarget } from "../utils/sourcePatcher";
 import type { SidebarTab } from "../components/sidebar/LeftSidebar";
 import type { Composition } from "@hyperframes/sdk";
 import { sdkCutoverPersist, sdkDeletePersist } from "../utils/sdkCutover";
-import { runResolverShadow } from "../utils/sdkResolverShadow";
+import { runResolverShadow, recordResolverParity } from "../utils/sdkResolverShadow";
 import { useAskAgentModal } from "./useAskAgentModal";
 import { useDomSelection } from "./useDomSelection";
 import { usePreviewInteraction } from "./usePreviewInteraction";
@@ -270,6 +270,14 @@ export function useDomEditSession({
             compositionPath: activeCompPath,
           })
       : undefined,
+    // Resolver shadow for the z-index reorder edit: it takes the server path (no
+    // SDK persist), but the tripwire is decoupled from cutover — record whether
+    // the SDK resolves each reordered element (the reorderElements op's targets).
+    onReorderShadow: sdkSession
+      ? (targets: string[]) => {
+          for (const target of targets) recordResolverParity(sdkSession, target, "reorderElements");
+        }
+      : undefined,
   });
   // ── Wiring: selection sync, GSAP cache, preview sync, selection handlers ──

package/src/hooks/useElementLifecycleOps.ts CHANGED Viewed

@@ -28,6 +28,8 @@ interface UseElementLifecycleOpsParams {
   clearDomSelection: () => void;
   /** Route delete through SDK when session resolves the hf-id; returns true if handled. */
   onTrySdkDelete?: (hfId: string, originalContent: string, targetPath: string) => Promise<boolean>;
+  /** Resolver-shadow tripwire for the reordered targets (telemetry-only, decoupled from cutover). */
+  onReorderShadow?: (targets: string[]) => void;
   /** Resync the SDK session after a server-fallback delete. */
   forceReloadSdkSession?: () => void;
   commitPositionPatchToHtml: (
@@ -49,6 +51,7 @@ export function useElementLifecycleOps({
   reloadPreview,
   clearDomSelection,
   onTrySdkDelete,
+  onReorderShadow,
   forceReloadSdkSession,
   commitPositionPatchToHtml,
   onElementDeleted,
@@ -168,6 +171,11 @@ export function useElementLifecycleOps({
       }>,
     ) => {
       if (entries.length === 0) return;
+      // Resolver shadow (telemetry-only, decoupled from cutover): record whether
+      // the SDK resolves each reordered element — the reorderElements op's targets.
+      onReorderShadow?.(
+        entries.map((e) => readHfId(e.element)).filter((id): id is string => id != null),
+      );
       const coalesceKey = `z-reorder:${entries.map((e) => e.id ?? e.selector ?? e.element.getAttribute("data-hf-id") ?? "el").join(":")}`;
       for (let i = 0; i < entries.length; i++) {
         const entry = entries[i];
@@ -202,7 +210,7 @@ export function useElementLifecycleOps({
         ).catch(() => undefined);
       }
     },
-    [commitPositionPatchToHtml],
+    [commitPositionPatchToHtml, onReorderShadow],
   );
   return {

package/src/hooks/useGsapAnimationOps.ts CHANGED Viewed

@@ -5,6 +5,8 @@ import { roundTo3 } from "../utils/rounding";
 import {
   sdkGsapTweenPersist,
   sdkGsapDeleteAllForSelectorPersist,
+  sdkAddWithKeyframesPersist,
+  sdkReplaceWithKeyframesPersist,
   type CutoverDeps,
 } from "../utils/sdkCutover";
 import {
@@ -181,10 +183,104 @@ export function useGsapAnimationOps({
     [activeCompPath, commitMutation, projectIdRef, showToast, sdkSession, sdkDeps],
   );
+  type KeyframeEntry = {
+    percentage: number;
+    properties: Record<string, number | string>;
+    ease?: string;
+    auto?: boolean;
+  };
+  const addWithKeyframes = useCallback(
+    async (
+      selection: DomEditSelection,
+      targetSelector: string,
+      position: number,
+      duration: number,
+      keyframes: KeyframeEntry[],
+      ease?: string,
+      label = "Add animation with keyframes",
+    ) => {
+      if (sdkSession && sdkDeps) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkAddWithKeyframesPersist(
+          targetPath,
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ease,
+          sdkSession,
+          sdkDeps,
+          { label },
+        );
+        if (handled) return;
+      }
+      void commitMutation(
+        selection,
+        {
+          type: "add-with-keyframes",
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ...(ease ? { ease } : {}),
+        },
+        { label, softReload: true },
+      );
+    },
+    [commitMutation, activeCompPath, sdkSession, sdkDeps],
+  );
+  const replaceWithKeyframes = useCallback(
+    async (
+      selection: DomEditSelection,
+      animationId: string,
+      targetSelector: string,
+      position: number,
+      duration: number,
+      keyframes: KeyframeEntry[],
+      ease?: string,
+      label = "Replace animation with keyframes",
+    ) => {
+      if (sdkSession && sdkDeps) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkReplaceWithKeyframesPersist(
+          targetPath,
+          animationId,
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ease,
+          sdkSession,
+          sdkDeps,
+          { label },
+        );
+        if (handled) return;
+      }
+      void commitMutation(
+        selection,
+        {
+          type: "replace-with-keyframes",
+          animationId,
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ...(ease ? { ease } : {}),
+        },
+        { label, softReload: true },
+      );
+    },
+    [commitMutation, activeCompPath, sdkSession, sdkDeps],
+  );
   return {
     updateGsapMeta,
     deleteGsapAnimation,
     deleteAllForSelector,
     addGsapAnimation,
+    addWithKeyframes,
+    replaceWithKeyframes,
   };
 }

package/src/hooks/useSdkSession.ts CHANGED Viewed

@@ -1,11 +1,32 @@
 import { useState, useEffect, useCallback } from "react";
 import type { MutableRefObject } from "react";
 import { openComposition } from "@hyperframes/sdk";
-import { createHttpAdapter } from "@hyperframes/sdk/adapters/http";
 import type { Composition } from "@hyperframes/sdk";
 import { readStudioFileChangePath } from "../components/editor/manualEdits";
 import { isSelfWriteEcho } from "./sdkSelfWriteRegistry";
+/**
+ * Read a project file's content, or undefined on a non-2xx (optional read).
+ * Replaces the removed SDK http adapter's `read()` — the only thing Studio used
+ * it for (Studio is the sole writer, so the adapter's write path was dead).
+ */
+async function readProjectFileOptional(
+  projectId: string,
+  path: string,
+): Promise<string | undefined> {
+  // Reject traversal / NUL before building the request URL — `path` is a
+  // user-influenced composition path (mirrors the guard in timelineEditingHelpers,
+  // and closes the CodeQL client-side-request-forgery flag). encodeURIComponent
+  // already confines both values to single segments of this same-origin URL.
+  if (path.includes("\0") || path.includes("..")) return undefined;
+  const res = await fetch(
+    `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}?optional=1`,
+  );
+  if (!res.ok) return undefined;
+  const data = (await res.json()) as { content?: string };
+  return typeof data.content === "string" ? data.content : undefined;
+}
 /**
  * True when an external file-change payload targets the active composition and
  * the SDK session must be re-opened to pick up the new content.
@@ -18,8 +39,8 @@ export function shouldReloadSdkSession(payload: unknown, activeCompPath: string
 /**
  * Stage 7 Step 3a — SDK session wired to the active composition.
  *
- * Creates an SDK Composition backed by createHttpAdapter on every
- * (projectId, activeCompPath) change, disposes the old one on cleanup, and
+ * Creates an SDK Composition (reading the file via the project files API) on
+ * every (projectId, activeCompPath) change, disposes the old one on cleanup, and
  * re-opens it when the active composition file changes on disk (code editor,
  * agent, or server-side patch) so the in-memory linkedom document never goes
  * stale. The session has NO persist queue — Studio is the sole file writer; see
@@ -81,10 +102,7 @@ export function useSdkSession(
   useEffect(() => {
     if (!activeCompPath) return;
     const compPath = activeCompPath;
-    const readAdapter =
-      projectId != null
-        ? createHttpAdapter({ projectFilesUrl: `/api/projects/${projectId}` })
-        : null;
+    const readProjectId = projectId ?? null;
     const handler = (payload?: unknown) => {
       if (!shouldReloadSdkSession(payload, compPath)) return;
       const withinWindow =
@@ -96,13 +114,12 @@ export function useSdkSession(
       const payloadContent = readFileChangeContent(payload);
       // Prefer payload content; otherwise re-read so the decision is by IDENTITY
       // (an undo's reverted bytes won't match a registered self-write → reload).
-      if (payloadContent != null || !readAdapter) {
+      if (payloadContent != null || readProjectId == null) {
         decide(payloadContent);
         return;
       }
-      readAdapter
-        .read(compPath)
-        .then((c) => decide(typeof c === "string" ? c : null))
+      readProjectFileOptional(readProjectId, compPath)
+        .then((c) => decide(c ?? null))
         .catch(() => decide(null));
     };
     if (import.meta.hot) {
@@ -126,11 +143,7 @@ export function useSdkSession(
     let cancelled = false;
     const compRef = { current: null as Composition | null };
-    const adapter = createHttpAdapter({
-      projectFilesUrl: `/api/projects/${projectId}`,
-    });
-    adapter
-      .read(activeCompPath)
+    readProjectFileOptional(projectId, activeCompPath)
       .then(async (content) => {
         if (cancelled || typeof content !== "string") return;
         // No persist queue: Studio's writeProjectFile (via sdkCutover's

package/src/utils/sdkCutover.ts CHANGED Viewed

@@ -435,6 +435,86 @@ export function sdkGsapConvertToKeyframesPersist(
   );
 }
+type KeyframeSpec = {
+  percentage: number;
+  properties: Record<string, number | string>;
+  ease?: string;
+  auto?: boolean;
+};
+type KeyframesPayload = {
+  targetSelector: string;
+  position: number;
+  duration: number;
+  keyframes: KeyframeSpec[];
+  ease?: string;
+};
+/** Shared inner dispatch for addWithKeyframes / replaceWithKeyframes ops. */
+function dispatchWithKeyframes(
+  s: Composition,
+  payload: KeyframesPayload,
+  animationId?: string,
+): void {
+  if (animationId !== undefined) {
+    s.dispatch({ type: "replaceWithKeyframes", animationId, ...payload });
+  } else {
+    s.dispatch({ type: "addWithKeyframes", ...payload });
+  }
+}
+export function sdkAddWithKeyframesPersist(
+  targetPath: string,
+  targetSelector: string,
+  position: number,
+  duration: number,
+  keyframes: KeyframeSpec[],
+  ease: string | undefined,
+  sdkSession: Composition | null | undefined,
+  deps: CutoverDeps,
+  options?: CutoverOptions,
+): Promise<boolean> {
+  const payload: KeyframesPayload = {
+    targetSelector,
+    position,
+    duration,
+    keyframes,
+    ...(ease ? { ease } : {}),
+  };
+  return dispatchGsapOpAndPersist(targetPath, sdkSession, deps, options, (s) =>
+    dispatchWithKeyframes(s, payload),
+  );
+}
+export function sdkReplaceWithKeyframesPersist(
+  targetPath: string,
+  animationId: string,
+  targetSelector: string,
+  position: number,
+  duration: number,
+  keyframes: KeyframeSpec[],
+  ease: string | undefined,
+  sdkSession: Composition | null | undefined,
+  deps: CutoverDeps,
+  options?: CutoverOptions,
+): Promise<boolean> {
+  const payload: KeyframesPayload = {
+    targetSelector,
+    position,
+    duration,
+    keyframes,
+    ...(ease ? { ease } : {}),
+  };
+  return dispatchGsapOpAndPersist(
+    targetPath,
+    sdkSession,
+    deps,
+    options,
+    (s) => dispatchWithKeyframes(s, payload, animationId),
+    { animationId, opLabel: "replaceWithKeyframes" },
+  );
+}
 export async function sdkDeletePersist(
   hfId: string,
   originalContent: string,

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

@@ -189,7 +189,7 @@ describe("C. Resolver-parity detection", () => {
   it("C8: element_not_found fires when SDK resolver returns null (v0.6.110 class)", () => {
     // Simulate the regression: SDK session cannot resolve the hfId the server
     // would address (e.g. scoped-id mismatch, resolver bug).
-    const session = { getElement: () => null } as unknown as Parameters<
+    const session = { getElement: () => null, getElements: () => [] } as unknown as Parameters<
       typeof sdkResolverShadowCheck
     >[0];
     const mismatches = sdkResolverShadowCheck(
@@ -364,3 +364,46 @@ describe("G. recordAnimationResolverParity", () => {
     expect(trackedEvents).toHaveLength(0);
   });
 });
+// ─── H. Inlined sub-composition: bare leaf id resolves (regression) ───────────
+// PostHog showed ~445 false `element_not_found` events, all on a bare leaf id
+// (hf-0ytc / #subscribe-btn) inside an inlined sub-composition. The studio reads
+// the bare data-hf-id off the DOM and the cutover dispatch resolves it via
+// resolveScoped (which locates the leaf inside the host subtree). But the shadow
+// resolved via Composition.getElement, which is canonical-only for a bare id and
+// returns null for a scoped element — so it flagged a divergence the real
+// dispatch path would not hit. The shadow now mirrors dispatch via resolveSnapshot.
+describe("H. inlined sub-composition leaf", () => {
+  // host carries data-composition-file → new scope; leaf's scopedId is
+  // "hf-host/hf-leaf" but its raw data-hf-id (what the studio reads) is bare.
+  const INLINED_HTML = /* html */ `<!DOCTYPE html>
+<html><body>
+  <div data-hf-id="hf-root" data-hf-root>
+    <div data-hf-id="hf-host" data-composition-file="sub.html">
+      <div data-hf-id="hf-leaf" style="color: red">Subscribe</div>
+    </div>
+  </div>
+</body></html>`;
+  it("getElement(bareLeaf) is null (canonical-only) — the trap the shadow used to hit", async () => {
+    const session = await openComposition(INLINED_HTML);
+    expect(session.getElement("hf-leaf")).toBeNull();
+    expect(session.getElement("hf-host/hf-leaf")).not.toBeNull();
+  });
+  it("recordResolverParity emits NOTHING for a bare leaf inside a sub-comp", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(INLINED_HTML);
+    recordResolverParity(session, "hf-leaf", "setTiming");
+    expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
+  });
+  it("sdkResolverShadowCheck does not flag element_not_found for a bare leaf in a sub-comp", async () => {
+    const session = await openComposition(INLINED_HTML);
+    const mismatches = sdkResolverShadowCheck(session, "hf-leaf", [
+      { type: "inline-style", property: "color", value: "blue" },
+    ]);
+    expect(mismatches.some((m) => m.kind === "element_not_found")).toBe(false);
+  });
+});

package/src/utils/sdkResolverShadow.ts CHANGED Viewed

@@ -65,6 +65,31 @@ function normalizeText(v: string | null | undefined): string | null {
 type FlatEl = NonNullable<ReturnType<Composition["getElement"]>>;
 type AttrMap = Record<string, string | null>;
+/**
+ * Resolve an hf-id to its snapshot the SAME way the SDK dispatch path does
+ * (engine/model.ts resolveScoped), NOT via Composition.getElement.
+ *
+ * getElement is canonical-only for a bare id by design — it deliberately will
+ * not resolve a bare id to a non-canonical (sub-composition) element, so that
+ * removeElement(bareId) and getElement(bareId) agree on the same instance
+ * (session.subcomp.test "ambiguous bare id" suite). But the cutover persist
+ * path dispatches the studio's bare data-hf-id, and dispatch resolves it via
+ * resolveScoped, which locates the leaf anywhere (canonical preferred, else
+ * first match). So getElement under-resolves a bare leaf that lives inside an
+ * inlined sub-composition (scopedId "host/leaf") — exactly the false
+ * `element_not_found` this tripwire was emitting for inlined compositions.
+ *
+ * Mirror resolveScoped here: exact scoped-path match, then canonical bare
+ * match, then first bare match — the resolvability dispatch actually has.
+ */
+function resolveSnapshot(session: Composition, id: string): FlatEl | null {
+  const els = session.getElements();
+  const exact = els.find((el) => el.scopedId === id);
+  if (exact) return exact;
+  const matches = els.filter((el) => el.id === id);
+  return matches.find((el) => el.scopedId === el.id) ?? matches[0] ?? null;
+}
 function checkStyleOp(
   op: PatchOperation,
   el: FlatEl,
@@ -140,7 +165,7 @@ export function sdkResolverShadowCheck(
   hfId: string,
   ops: PatchOperation[],
 ): SdkResolverMismatch[] {
-  if (!session.getElement(hfId)) {
+  if (!resolveSnapshot(session, hfId)) {
     return [{ kind: "element_not_found", hfId }];
   }
@@ -172,7 +197,7 @@ export function sdkResolverShadowCheck(
       return [{ kind: "dispatch_error", hfId, error: String(err) }];
     }
-    const el = session.getElement(hfId);
+    const el = resolveSnapshot(session, hfId);
     if (!el) return [{ kind: "element_not_found", hfId }];
     return shadowable
@@ -253,7 +278,7 @@ export function recordResolverParity(
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!session || !hfId) return;
   try {
-    if (session.getElement(hfId)) return; // resolves — parity, nothing to record
+    if (resolveSnapshot(session, hfId)) return; // resolves — parity, nothing to record
     trackStudioEvent("sdk_resolver_shadow", {
       hfId,
       opLabel,