@hyperframes/studio 0.7.58 → 0.7.60

package/src/utils/sdkEditTransaction.ts

@@ -0,0 +1,293 @@
+import type { MutableRefObject } from "react";
+import { openComposition, type Composition } from "@hyperframes/sdk";
+import type { EditHistoryKind } from "./editHistory";
+import { hashContent, markSelfWrite } from "../hooks/sdkSelfWriteRegistry";
+import { trackStudioEvent } from "./studioTelemetry";
+import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
+
+export type CutoverResult =
+  | { status: "declined"; reason: string }
+  | { status: "committed"; version: string }
+  | { status: "failed"; error: Error };
+
+export interface SdkSessionPublication {
+  candidate: Composition;
+  expectedSession: Composition;
+  targetPath: string;
+}
+
+export type SdkSessionPublicationResult =
+  | "published"
+  | "rejected-active-target"
+  | "rejected-inactive-target";
+
+export type PublishSdkSession = (publication: SdkSessionPublication) => SdkSessionPublicationResult;
+
+export interface CutoverDeps {
+  editHistory: {
+    recordEdit: (entry: {
+      label: string;
+      kind: EditHistoryKind;
+      coalesceKey?: string;
+      coalesceMs?: number;
+      files: Record<string, { before: string; after: string }>;
+    }) => Promise<void>;
+  };
+  /**
+   * Must be bound to one project. Its identity plus path scopes the shared
+   * mutation queue used by every whole-file writer in that project.
+   */
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
+  reloadPreview: () => void;
+  domEditSaveTimestampRef: MutableRefObject<number>;
+  refresh?: (after: string) => void;
+  compositionPath?: string | null;
+  readProjectFile?: (path: string) => Promise<string>;
+  /**
+   * Takes ownership only when it returns `published`. Rejection identifies
+   * whether target-sensitive preview refresh is still safe. MUST NOT throw
+   * after installation; rejection leaves ownership with the caller.
+   */
+  publishSession?: PublishSdkSession;
+  /** Test seam; production clones with openComposition. */
+  createCandidateSession?: (serialized: string, live: Composition) => Promise<Composition>;
+}
+
+export interface CutoverOptions {
+  label?: string;
+  coalesceKey?: string;
+  /** Coalesce window (ms); Infinity folds across a slow round-trip. */
+  coalesceMs?: number;
+  skipRefresh?: boolean;
+}
+
+interface CandidateEdit {
+  live: Composition;
+  candidate: Composition;
+  serializedBefore: string;
+  after: string;
+}
+
+export function declinedCutover(reason: string): CutoverResult {
+  return { status: "declined", reason };
+}
+
+export function asCutoverError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/** Only an explicit decline may enter the legacy mutation backend. */
+export function cutoverCommittedOrThrow(result: CutoverResult): boolean {
+  if (result.status === "failed") throw result.error;
+  return result.status === "committed";
+}
+
+/** A supplied authoritative reader fails closed; only its absence uses the snapshot fallback. */
+async function captureOnDiskBefore(
+  deps: CutoverDeps,
+  targetPath: string,
+  serializedFallback: string,
+): Promise<string> {
+  if (!deps.readProjectFile) return serializedFallback;
+  return deps.readProjectFile(targetPath);
+}
+
+function disposeCandidate(candidate: Composition | undefined, live: Composition): void {
+  if (candidate && candidate !== live) candidate.dispose();
+}
+
+function createCandidateSession(
+  serializedBefore: string,
+  live: Composition,
+  deps: CutoverDeps,
+): Promise<Composition> {
+  return deps.createCandidateSession
+    ? deps.createCandidateSession(serializedBefore, live)
+    : openComposition(serializedBefore, { history: false });
+}
+
+function candidatePublisherAvailable(
+  candidate: Composition,
+  live: Composition,
+  deps: CutoverDeps,
+): boolean {
+  return candidate === live || deps.publishSession !== undefined;
+}
+
+async function buildCandidateEdit(
+  live: Composition,
+  deps: CutoverDeps,
+  mutate: (candidate: Composition) => void,
+  sourceSnapshot?: string,
+): Promise<CandidateEdit | CutoverResult> {
+  let candidate: Composition | undefined;
+  try {
+    const serializedBefore = sourceSnapshot ?? live.serialize();
+    candidate = await createCandidateSession(serializedBefore, live, deps);
+    candidate.batch(() => mutate(candidate!));
+    const after = candidate.serialize();
+    if (after === serializedBefore) {
+      disposeCandidate(candidate, live);
+      return declinedCutover("no_change");
+    }
+    if (!candidatePublisherAvailable(candidate, live, deps)) {
+      disposeCandidate(candidate, live);
+      return { status: "failed", error: new Error("SDK candidate publisher is unavailable") };
+    }
+    return { live, candidate, serializedBefore, after };
+  } catch (error) {
+    disposeCandidate(candidate, live);
+    return { status: "failed", error: asCutoverError(error) };
+  }
+}
+
+function isCutoverResult(value: CandidateEdit | CutoverResult): value is CutoverResult {
+  return "status" in value;
+}
+
+async function rollbackWrite(
+  targetPath: string,
+  originalContent: string,
+  expectedCurrentContent: string,
+  deps: CutoverDeps,
+  cause: Error,
+): Promise<Error> {
+  try {
+    deps.domEditSaveTimestampRef.current = Date.now();
+    markSelfWrite(targetPath, originalContent);
+    await deps.writeProjectFile(targetPath, originalContent, expectedCurrentContent);
+    return cause;
+  } catch (rollbackError) {
+    return new AggregateError(
+      [cause, asCutoverError(rollbackError)],
+      `SDK edit failed and rollback could not restore ${targetPath}`,
+    );
+  }
+}
+
+async function writeAndRecord(
+  after: string,
+  targetPath: string,
+  originalContent: string,
+  deps: CutoverDeps,
+  options?: CutoverOptions,
+): Promise<Error | null> {
+  deps.domEditSaveTimestampRef.current = Date.now();
+  markSelfWrite(targetPath, after);
+  try {
+    await deps.writeProjectFile(targetPath, after, originalContent);
+  } catch (error) {
+    return asCutoverError(error);
+  }
+  try {
+    await deps.editHistory.recordEdit({
+      label: options?.label ?? "Edit layer",
+      kind: "manual",
+      ...(options?.coalesceKey ? { coalesceKey: options.coalesceKey } : {}),
+      ...(options?.coalesceMs != null ? { coalesceMs: options.coalesceMs } : {}),
+      files: { [targetPath]: { before: originalContent, after } },
+    });
+    return null;
+  } catch (error) {
+    return rollbackWrite(targetPath, originalContent, after, deps, asCutoverError(error));
+  }
+}
+
+function refreshCommittedEdit(after: string, deps: CutoverDeps, options?: CutoverOptions): void {
+  try {
+    if (deps.refresh) deps.refresh(after);
+    else if (!options?.skipRefresh) deps.reloadPreview();
+  } catch (error) {
+    trackStudioEvent("sdk_cutover_refresh_failed", { error: asCutoverError(error).message });
+  }
+}
+
+async function commitCandidateEdit(
+  edit: CandidateEdit,
+  targetPath: string,
+  originalContent: string,
+  deps: CutoverDeps,
+  options?: CutoverOptions,
+): Promise<CutoverResult> {
+  const writeError = await writeAndRecord(edit.after, targetPath, originalContent, deps, options);
+  if (writeError) {
+    if (edit.candidate !== edit.live) edit.candidate.dispose();
+    return { status: "failed", error: writeError };
+  }
+  let refreshTarget = true;
+  try {
+    if (edit.candidate !== edit.live) {
+      const publication = deps.publishSession!({
+        candidate: edit.candidate,
+        expectedSession: edit.live,
+        targetPath,
+      });
+      if (publication !== "published") edit.candidate.dispose();
+      if (publication === "rejected-inactive-target") refreshTarget = false;
+    }
+  } catch (error) {
+    // Persistence and history are already committed. A publisher can throw
+    // after installing the candidate, so rolling back disk or disposing the
+    // candidate here can make all three authorities disagree (or dispose the
+    // now-live session). Production publishers are non-throwing; keep the
+    // durable commit authoritative and surface this post-commit fault.
+    trackStudioEvent("sdk_cutover_publish_failed", {
+      path: targetPath,
+      error: asCutoverError(error).message,
+    });
+  }
+  if (refreshTarget) refreshCommittedEdit(edit.after, deps, options);
+  return { status: "committed", version: hashContent(edit.after) };
+}
+
+export async function persistSdkCandidateMutation(
+  live: Composition,
+  targetPath: string,
+  originalContent: string,
+  deps: CutoverDeps,
+  mutate: (candidate: Composition) => void,
+  options?: CutoverOptions,
+  sourceSnapshot?: string,
+): Promise<CutoverResult> {
+  return serializeStudioFileMutation(
+    deps.writeProjectFile,
+    targetPath,
+    async (): Promise<CutoverResult> => {
+      // Re-read only after acquiring the path queue. This makes each candidate
+      // clone the latest committed bytes, even when React has not yet re-rendered
+      // and the caller still holds the preceding live-session object.
+      const serializedFallback = sourceSnapshot ?? originalContent;
+      let onDiskBefore: string;
+      try {
+        onDiskBefore = await captureOnDiskBefore(deps, targetPath, serializedFallback);
+      } catch (error) {
+        return { status: "failed", error: asCutoverError(error) };
+      }
+      // Preserve the live-session path for adapters without a reader (notably
+      // isolated consumers/tests). Production Studio supplies a reader so
+      // queued edits always clone the latest durable source.
+      const candidateSource = deps.readProjectFile ? onDiskBefore : sourceSnapshot;
+      const candidate = await buildCandidateEdit(live, deps, mutate, candidateSource);
+      if (isCutoverResult(candidate)) return candidate;
+      return commitCandidateEdit(candidate, targetPath, onDiskBefore, deps, options);
+    },
+  );
+}
+
+/** Transactional writer for non-SDK islands and throwaway composition sessions. */
+export async function persistSdkSerialize(
+  buildAfter: (onDiskBefore: string) => string | Promise<string>,
+  targetPath: string,
+  originalContent: string,
+  deps: CutoverDeps,
+  options?: CutoverOptions,
+): Promise<void> {
+  await serializeStudioFileMutation(deps.writeProjectFile, targetPath, async () => {
+    const onDiskBefore = await captureOnDiskBefore(deps, targetPath, originalContent);
+    const after = await buildAfter(onDiskBefore);
+    if (after === onDiskBefore) return;
+    const error = await writeAndRecord(after, targetPath, onDiskBefore, deps, options);
+    if (error) throw error;
+    refreshCommittedEdit(after, deps, options);
+  });
+}

package/src/utils/sdkResolverAttempts.ts

@@ -0,0 +1,94 @@
+/**
+ * Attempt counter — the denominator for the resolver-shadow soak gate.
+ *
+ * The emit functions in sdkResolverShadow.ts only fire a PostHog event on
+ * divergence — parity is silent, by design, to avoid firing on every edit.
+ * That leaves no way to compute a rate (divergences / attempts): we can count
+ * failures but never attempts. This counter tracks attempts in memory and
+ * rolls them up into ONE low-frequency event instead of firing per-attempt,
+ * which would recreate the exact chattiness problem the divergence-only
+ * design avoids.
+ */
+
+import { trackStudioEvent, flushViaBeacon } from "./studioTelemetry";
+
+const attemptCounts: Record<string, number> = {};
+
+/**
+ * Record that the resolver-shadow tripwire ran for `opLabel`, regardless of
+ * outcome (parity or divergence). No flag check of its own — only ever called
+ * from inside the shadow emit functions, after their own
+ * STUDIO_SDK_RESOLVER_SHADOW_ENABLED guard, so it's already flag-gated.
+ */
+export function recordAttempt(opLabel: string): void {
+  attemptCounts[opLabel] = (attemptCounts[opLabel] ?? 0) + 1;
+  ensureAttemptFlushScheduled();
+}
+
+/**
+ * Return the accumulated attempt counts since the last flush (or `null` if
+ * nothing has been recorded — no point emitting an empty rollup), and reset
+ * the counter to empty.
+ */
+export function flushAttemptCounts(): Record<string, number> | null {
+  const keys = Object.keys(attemptCounts);
+  if (keys.length === 0) return null;
+  const snapshot: Record<string, number> = {};
+  for (const key of keys) {
+    snapshot[key] = attemptCounts[key];
+    delete attemptCounts[key];
+  }
+  return snapshot;
+}
+
+const ATTEMPT_FLUSH_INTERVAL_MS = 5 * 60_000;
+let attemptFlushTimer: ReturnType<typeof setInterval> | null = null;
+let attemptVisibilityHandler: (() => void) | null = null;
+
+function flushAndEmitAttempts(): void {
+  const counts = flushAttemptCounts();
+  if (counts === null) return;
+  trackStudioEvent("sdk_resolver_shadow_attempt", { counts: JSON.stringify(counts) });
+}
+
+// Lazily starts the rollup timer + visibilitychange listener on the FIRST
+// attempt in a session — mirrors studioTelemetry.ts's own lazy flushTimer
+// start, so a session that never exercises the tripwire never runs a
+// background timer.
+function ensureAttemptFlushScheduled(): void {
+  if (!attemptFlushTimer) {
+    attemptFlushTimer = setInterval(flushAndEmitAttempts, ATTEMPT_FLUSH_INTERVAL_MS);
+  }
+  if (!attemptVisibilityHandler && typeof document !== "undefined") {
+    attemptVisibilityHandler = () => {
+      if (document.visibilityState !== "hidden") return;
+      flushAndEmitAttempts();
+      // studioTelemetry.ts registers its own visibilitychange listener (on
+      // window, at module load) that drains its queue via sendBeacon. Listener
+      // execution order between that handler and this one (on document,
+      // registered lazily) is not something to rely on — whichever runs
+      // first could otherwise beacon-flush before or after this rollup lands
+      // in the queue. Forcing a beacon flush here makes delivery of this
+      // rollup event correct regardless of that order.
+      flushViaBeacon();
+    };
+    document.addEventListener("visibilitychange", attemptVisibilityHandler);
+  }
+}
+
+/**
+ * Test-only: clears the lazy timer/listener singleton state so tests can
+ * verify the "starts on first attempt" behavior in isolation, without an
+ * earlier test's real-timer interval (or visibilitychange listener) silently
+ * surviving into a later test. Does NOT touch attemptCounts — only the
+ * scheduling state. Not part of the public module contract; only imported
+ * from sdkResolverShadow.test.ts.
+ */
+export function __resetAttemptSchedulingForTests(): void {
+  if (attemptFlushTimer) clearInterval(attemptFlushTimer);
+  attemptFlushTimer = null;
+  if (attemptVisibilityHandler && typeof document !== "undefined") {
+    document.removeEventListener("visibilitychange", attemptVisibilityHandler);
+  }
+  attemptVisibilityHandler = null;
+}

package/src/utils/sdkResolverShadow.test.ts

@@ -432,6 +432,18 @@ describe("F. recordResolverParity", () => {
     expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
   });
 
+  it("skips entirely (no event, no attempt) for a cross-file op", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    flushAttemptCounts();
+    const session = await openComposition(BASE_HTML);
+    await recordResolverParity(session, "hf-cross", "setTiming", undefined, {
+      targetPath: "compositions/other.html",
+      compositionPath: "index.html",
+    });
+    expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
+    expect(flushAttemptCounts()).toBeNull();
+  });
+
   it("emits with sourceHfIdCount=1 when the hfId IS in source but missing from the session", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
     const session = await openComposition(BASE_HTML);
@@ -562,6 +574,142 @@ describe("G. recordAnimationResolverParity", () => {
     recordAnimationResolverParity(session, unmatchedId, "removeAllKeyframes");
     expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
   });
+
+  // ── Stale-session disambiguation (the 0.7.48 keyframe-op class) ─────────────
+  // The GSAP panel computes animationIds from the CURRENT on-disk script (the
+  // server read path re-reads per render), but the session's parsed id space
+  // reflects the last session reload. An edit that shifts tween positions
+  // shifts every `selector-method-position` id, so a panel op landing between
+  // the write and the session reload targets an id the session has never seen.
+  // That is a sync gap, not a resolver bug — disambiguate against disk truth.
+
+  // Same tween, position moved 0→3: every id in the NEW script differs from
+  // the ids the OLD (session) script parses to.
+  const GSAP_DISK_MOVED_HTML = /* html */ `<!DOCTYPE html>
+<html><body>
+  <div data-hf-id="hf-box" style="color: red">Hello</div>
+  <script>var tl = gsap.timeline({ paused: true }); tl.to("[data-hf-id=\\"hf-box\\"]", { x: 100, duration: 1 }, 3);</script>
+</body></html>`;
+
+  it("suppresses the emit when the animationId resolves against the on-disk script (stale session)", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(GSAP_HTML); // session parsed the OLD script
+    const disk = await openComposition(GSAP_DISK_MOVED_HTML);
+    const diskId = [...disk.getAllAnimationIds()][0] ?? "";
+    disk.dispose();
+    expect(diskId).not.toBe("");
+    expect(session.getAllAnimationIds().has(diskId)).toBe(false); // session can't see it
+    await recordAnimationResolverParity(session, diskId, "removeGsapKeyframe", () =>
+      Promise.resolve(GSAP_DISK_MOVED_HTML),
+    );
+    expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
+  });
+
+  it("emits with diskChecked when the animationId resolves in NEITHER session nor disk", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(GSAP_HTML);
+    await recordAnimationResolverParity(session, "no-such-anim", "removeGsapKeyframe", () =>
+      Promise.resolve(GSAP_DISK_MOVED_HTML),
+    );
+    const ev = lastShadow();
+    expect(ev?.mismatchCount).toBe(1);
+    expect(ev?.diskChecked).toBe(true);
+    expect(JSON.stringify(ev?.mismatches)).toContain("animation_not_found");
+  });
+
+  it("fails open with sourceReadFailed when the reader throws", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(GSAP_HTML);
+    await recordAnimationResolverParity(session, "no-such-anim", "removeGsapKeyframe", () =>
+      Promise.reject(new Error("read failed")),
+    );
+    const ev = lastShadow();
+    expect(ev?.mismatchCount).toBe(1);
+    expect(ev?.sourceReadFailed).toBe(true);
+    expect(ev?.diskChecked).toBeUndefined();
+  });
+
+  it("fails open with sourceReadFailed when the reader throws SYNCHRONOUSLY", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(GSAP_HTML);
+    await recordAnimationResolverParity(session, "no-such-anim", "removeGsapKeyframe", () => {
+      throw new Error("sync read failed");
+    });
+    const ev = lastShadow();
+    expect(ev?.mismatchCount).toBe(1);
+    expect(ev?.sourceReadFailed).toBe(true);
+  });
+
+  it("dispatches the disk read synchronously on a miss — before the caller's write can land", async () => {
+    // The tripwire is fire-and-forget and the caller's cutover persist writes
+    // this same file moments after it returns. The read request must be
+    // dispatched in the same sync prologue as the miss check, so it observes
+    // the PRE-write file (a post-write read would see a remove op's target
+    // legitimately gone and misclassify it as a genuine divergence).
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(GSAP_HTML);
+    const read = vi.fn(() => Promise.resolve(GSAP_DISK_MOVED_HTML));
+    const pending = recordAnimationResolverParity(
+      session,
+      "no-such-anim",
+      "removeGsapKeyframe",
+      read,
+    );
+    expect(read).toHaveBeenCalledTimes(1); // already dispatched, no await yet
+    await pending;
+  });
+
+  it("skips entirely (no event, no attempt) for a cross-file op", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    flushAttemptCounts();
+    const session = await openComposition(GSAP_HTML);
+    await recordAnimationResolverParity(session, "no-such-anim", "removeGsapKeyframe", undefined, {
+      targetPath: "compositions/other.html",
+      compositionPath: "index.html",
+    });
+    expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
+    expect(flushAttemptCounts()).toBeNull();
+  });
+});
+
+// ─── G2. runResolverShadow cross-file guard ───────────────────────────────────
+// PostHog 0.7.41: one session emitted 479 element_not_found because the user
+// edited elements whose sourceFile differed from the active composition — the
+// session models ONLY the active comp, so cross-file targets are structurally
+// unresolvable. The cutover gates already decline via wrongCompositionFile;
+// the tripwire must skip the same way (no event, no attempt — the op can't
+// cut over, so it belongs in neither side of the soak rate).
+describe("G2. runResolverShadow cross-file guard", () => {
+  const ops: PatchOperation[] = [{ type: "inline-style", property: "color", value: "blue" }];
+
+  it("skips entirely when targetPath differs from the session's composition", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    flushAttemptCounts();
+    const session = await openComposition(BASE_HTML);
+    runResolverShadow(session, "hf-cross", ops, undefined, {
+      targetPath: "compositions/sample-vote-count.html",
+      compositionPath: "templates/document-card.html",
+    });
+    expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
+    expect(flushAttemptCounts()).toBeNull();
+  });
+
+  it("still emits for a same-file divergence", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(BASE_HTML);
+    runResolverShadow(session, "hf-missing", ops, undefined, {
+      targetPath: "index.html",
+      compositionPath: "index.html",
+    });
+    expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(1);
+  });
+
+  it("runs normally when paths are not supplied (status quo)", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(BASE_HTML);
+    runResolverShadow(session, "hf-missing", ops);
+    expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(1);
+  });
 });
 
 // ─── H. Inlined sub-composition: bare leaf id resolves (regression) ───────────