@hyperframes/studio 0.8.45 → 0.8.47

package/src/utils/sdkCutover.ts

@@ -5,7 +5,11 @@ import * as studioAvailability from "../components/editor/manualEditingAvailabil
 import { trackStudioEvent } from "./studioTelemetry";
 import { patchOpsToSdkEditOps } from "./sdkOpMapping";
 import { recordResolverParity, recordAnimationResolverParity } from "./sdkResolverShadow";
-import { shouldDeclineTextCutoverForTarget, shouldUseSdkCutover } from "./sdkCutoverEligibility";
+import {
+  isResolverDisagreement,
+  shouldDeclineTextCutoverForTarget,
+  shouldUseSdkCutover,
+} from "./sdkCutoverEligibility";
 import {
   asCutoverError,
   declinedCutover,
@@ -78,15 +82,17 @@ export async function sdkCutoverPersist(
   options?: CutoverOptions,
 ): Promise<CutoverResult> {
   if (!shouldUseSdkCutover(sdkFamilyEnabled("dom"), !!sdkSession, selection.hfId, ops))
-    return declinedCutover("ineligible_operation");
-  if (!sdkSession) return declinedCutover("session_unavailable");
+    return declinedCutover("ineligible_operation", "dom");
+  if (!sdkSession) return declinedCutover("session_unavailable", "dom");
   const hfId = selection.hfId;
-  if (!hfId) return declinedCutover("target_unaddressable");
+  if (!hfId) return declinedCutover("target_unaddressable", "dom");
   const target = sdkSession.getElement(hfId);
-  if (!target) return declinedCutover("target_not_found");
+  if (!target)
+    return declinedCutover("target_not_found", "dom", isResolverDisagreement(sdkSession, hfId));
   if (shouldDeclineTextCutoverForTarget(target, ops))
-    return declinedCutover("unsupported_text_target");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+    return declinedCutover("unsupported_text_target", "dom");
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "dom");
   const result = await persistSdkCandidateMutation(
     sdkSession,
     targetPath,
@@ -122,10 +128,12 @@ export async function sdkTimingPersist(
   // Dark-launch gate: without this, timing cutover runs whenever an SDK session
   // exists (it always does, for shadow/selection) — flipping the flag OFF would
   // NOT disable it. Gate here so flag-off routes back to the legacy server path.
-  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (!sdkSession.getElement(hfId)) return declinedCutover("target_not_found");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled", "timing");
+  if (!sdkSession) return declinedCutover("session_unavailable", "timing");
+  if (!sdkSession.getElement(hfId))
+    return declinedCutover("target_not_found", "timing", isResolverDisagreement(sdkSession, hfId));
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "timing");
   try {
     const serializedBefore = sdkSession.serialize();
     const result = await persistSdkCandidateMutation(
@@ -166,11 +174,17 @@ export async function sdkTimingBatchPersist(
       { targetPath, compositionPath: deps.compositionPath },
     );
   }
-  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
-  if (changes.some((change) => !sdkSession.getElement(change.hfId)))
-    return declinedCutover("target_not_found");
+  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled", "timing");
+  if (!sdkSession) return declinedCutover("session_unavailable", "timing");
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "timing");
+  const unresolved = changes.find((change) => !sdkSession.getElement(change.hfId));
+  if (unresolved)
+    return declinedCutover(
+      "target_not_found",
+      "timing",
+      isResolverDisagreement(sdkSession, unresolved.hfId),
+    );
   try {
     const serializedBefore = sdkSession.serialize();
     const result = await persistSdkCandidateMutation(
@@ -244,9 +258,9 @@ export function sdkGsapTweenPersist(
   // Leading dark-launch gate so flag-off does no SDK touch (getElement) at all —
   // matches the other three chokepoints' discipline.
   if (!sdkFamilyEnabled("gsap-animation"))
-    return Promise.resolve(declinedCutover("feature_disabled"));
+    return Promise.resolve(declinedCutover("feature_disabled", "gsap-animation"));
   if (op.kind === "add" && sdkSession && !sdkSession.getElement(op.target))
-    return Promise.resolve(declinedCutover("target_not_found"));
+    return Promise.resolve(declinedCutover("target_not_found", "gsap-animation"));
   // dispatchGsapOpAndPersist declines on before===after — that catches stale
   // animationIds and unsupported shapes (e.g. from-prop on a plain tween), falling
   // back to the server path. This subsumes explicit existence guards for set/remove.
@@ -285,9 +299,10 @@ async function dispatchGsapOpAndPersist(
   }
   // Dark-launch gate (shared chokepoint for every GSAP-op cutover persist):
   // flag OFF → explicit decline → caller falls back to the legacy server path.
-  if (!sdkFamilyEnabled(family)) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+  if (!sdkFamilyEnabled(family)) return declinedCutover("feature_disabled", family);
+  if (!sdkSession) return declinedCutover("session_unavailable", family);
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", family);
   const session = sdkSession;
   // persistSdkCandidateMutation owns the shared per-project/file transaction
   // coordinator used by both SDK and legacy GSAP writes.
@@ -559,10 +574,16 @@ export async function sdkDeletePersist(
     { targetPath, compositionPath: deps.compositionPath },
   );
   // Dark-launch gate: flag OFF → legacy server delete path.
-  if (!sdkFamilyEnabled("lifecycle")) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (!sdkSession.getElement(hfId)) return declinedCutover("target_not_found");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+  if (!sdkFamilyEnabled("lifecycle")) return declinedCutover("feature_disabled", "lifecycle");
+  if (!sdkSession) return declinedCutover("session_unavailable", "lifecycle");
+  if (!sdkSession.getElement(hfId))
+    return declinedCutover(
+      "target_not_found",
+      "lifecycle",
+      isResolverDisagreement(sdkSession, hfId),
+    );
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "lifecycle");
   const result = await persistSdkCandidateMutation(
     sdkSession,
     targetPath,

package/src/utils/sdkCutoverEligibility.ts

@@ -4,8 +4,10 @@
  * sdkCutover.ts (which hit the packages/studio 600-line filesize cap) — this
  * block has no dependency on the persist/dispatch functions there.
  */
+import type { Composition } from "@hyperframes/sdk";
 import type { PatchOperation } from "./sourcePatcher";
 import { isAllowedHtmlAttribute, isSafeAttributeValue } from "./htmlAttrSafety";
+import { resolveSnapshot } from "./sdkResolverShadow";
 
 const CUTOVER_OP_TYPES = new Set<PatchOperation["type"]>([
   "inline-style",
@@ -102,6 +104,25 @@ export function shouldDeclineTextCutoverForTarget(target: unknown, ops: PatchOpe
   return tag !== null && NON_HTML_CHILD_TAGS.has(tag);
 }
 
+/**
+ * On a `target_not_found`, decide whether the miss is the known benign class
+ * (node genuinely absent from the session — nothing dispatch could have done)
+ * or a resolver disagreement: the shadow's broader resolver finds it, so
+ * dispatch could have made the edit and `getElement` refused it. The shadow
+ * event stays silent in that case, so this flag is the only signal for it.
+ *
+ * Diagnostic context only — it must never turn a clean decline into a throw, so
+ * a session shape without `getElements` reports "no disagreement" and the edit
+ * falls back exactly as it otherwise would have.
+ */
+export function isResolverDisagreement(session: Composition, hfId: string): boolean {
+  try {
+    return resolveSnapshot(session, hfId) !== null;
+  } catch {
+    return false;
+  }
+}
+
 export function shouldUseSdkCutover(
   flagEnabled: boolean,
   hasSession: boolean,

package/src/utils/sdkCutoverPolicy.test.ts

@@ -7,8 +7,17 @@ import {
 } from "./sdkCutoverPolicy";
 
 describe("Studio SDK operation-family policy", () => {
-  it("enables no family from the master switch alone", () => {
-    expect(resolveEnabledSdkFamilies({}, true).size).toBe(0);
+  it("enables every family when the master switch is on and no family list is set", () => {
+    const all = new Set(STUDIO_SDK_OPERATION_FAMILIES);
+    expect(resolveEnabledSdkFamilies({}, true)).toEqual(all);
+    expect(resolveEnabledSdkFamilies({ VITE_STUDIO_SDK_CUTOVER_FAMILIES: "" }, true)).toEqual(all);
+    expect(resolveEnabledSdkFamilies({ VITE_STUDIO_SDK_CUTOVER_FAMILIES: "  " }, true)).toEqual(
+      all,
+    );
+  });
+
+  it("enables no family when the master switch is off, regardless of the family list", () => {
+    expect(resolveEnabledSdkFamilies({}, false).size).toBe(0);
     expect(resolveEnabledSdkFamilies({ VITE_STUDIO_SDK_CUTOVER_FAMILIES: "dom" }, false).size).toBe(
       0,
     );

package/src/utils/sdkCutoverPolicy.ts

@@ -54,7 +54,8 @@ export function resolveEnabledSdkFamilies(
 ): ReadonlySet<StudioSdkOperationFamily> {
   if (!masterEnabled) return new Set();
   const raw = env["VITE_STUDIO_SDK_CUTOVER_FAMILIES"];
-  if (typeof raw !== "string" || raw.trim() === "") return new Set();
+  // Unset/blank = every family. The list exists to RESTRICT (kill switch per family).
+  if (typeof raw !== "string" || raw.trim() === "") return new Set(STUDIO_SDK_OPERATION_FAMILIES);
   const requested = raw
     .split(",")
     .map((family) => family.trim())
@@ -85,8 +86,9 @@ export function renderStudioSdkCutoverReport(): string {
   return [
     "# Studio SDK cutover report",
     "",
-    "Master flag: `VITE_STUDIO_SDK_CUTOVER_ENABLED=true`",
-    "Family flag: `VITE_STUDIO_SDK_CUTOVER_FAMILIES=dom,timing,...`",
+    "Default: SDK persist ON for every family. Kill switches:",
+    "  `VITE_STUDIO_SDK_CUTOVER_ENABLED=false` (all families → server path)",
+    "  `VITE_STUDIO_SDK_CUTOVER_FAMILIES=dom,timing` (only listed families → SDK; rest → server)",
     "",
     "A family graduates only after zero unexplained resolver/serialization divergences over its agreed corpus and soak window.",
     "",

package/src/utils/sdkEditTransaction.decline.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("./studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+import { trackStudioEvent } from "./studioTelemetry";
+import { declinedCutover } from "./sdkEditTransaction";
+
+describe("declinedCutover telemetry", () => {
+  it("emits sdk_cutover_declined with reason and family, and returns the declined result", () => {
+    const result = declinedCutover("target_not_found", "timing");
+    expect(result).toEqual({ status: "declined", reason: "target_not_found" });
+    expect(trackStudioEvent).toHaveBeenCalledWith("sdk_cutover_declined", {
+      reason: "target_not_found",
+      family: "timing",
+    });
+  });
+
+  it("emits family:null when the decline happens before a family is known", () => {
+    declinedCutover("no_change");
+    expect(trackStudioEvent).toHaveBeenCalledWith("sdk_cutover_declined", {
+      reason: "no_change",
+      family: null,
+    });
+  });
+
+  it("omits resolverDisagreement when it is not set, and carries it when it is", () => {
+    declinedCutover("target_not_found", "timing");
+    expect(trackStudioEvent).toHaveBeenLastCalledWith("sdk_cutover_declined", {
+      reason: "target_not_found",
+      family: "timing",
+    });
+
+    declinedCutover("target_not_found", "timing", true);
+    expect(trackStudioEvent).toHaveBeenLastCalledWith("sdk_cutover_declined", {
+      reason: "target_not_found",
+      family: "timing",
+      resolverDisagreement: true,
+    });
+
+    declinedCutover("target_not_found", "timing", false);
+    expect(trackStudioEvent).toHaveBeenLastCalledWith("sdk_cutover_declined", {
+      reason: "target_not_found",
+      family: "timing",
+    });
+  });
+});

package/src/utils/sdkEditTransaction.ts

@@ -3,6 +3,7 @@ import type { EditHistoryKind } from "./editHistory";
 import { hashContent, markSelfWrite } from "../hooks/sdkSelfWriteRegistry";
 import { trackStudioEvent } from "./studioTelemetry";
 import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
+import type { StudioSdkOperationFamily } from "./sdkCutoverPolicy";
 
 export type CutoverResult =
   | { status: "declined"; reason: string }
@@ -66,7 +67,27 @@ interface CandidateEdit {
   after: string;
 }
 
-export function declinedCutover(reason: string): CutoverResult {
+/**
+ * Explicit fall-back to the legacy server path. Emits `sdk_cutover_declined` so
+ * post-flip we can distinguish "SDK took the edit" from "SDK bowed out"; payload
+ * is reason + family only (no hfId / path / content).
+ *
+ * `resolverDisagreement` is the one extra field with diagnostic value beyond the
+ * reason itself: on a `target_not_found`, the shadow's `resolveSnapshot` (what
+ * dispatch resolves) found the element that `getElement` could not. The shadow
+ * event stays silent in that case, so without this flag the case is invisible —
+ * and it is an adoption loss (a dispatchable edit refused), not a missing node.
+ */
+export function declinedCutover(
+  reason: string,
+  family?: StudioSdkOperationFamily,
+  resolverDisagreement?: boolean,
+): CutoverResult {
+  trackStudioEvent("sdk_cutover_declined", {
+    reason,
+    family: family ?? null,
+    ...(resolverDisagreement ? { resolverDisagreement: true } : {}),
+  });
   return { status: "declined", reason };
 }
 

package/src/utils/sdkResolverShadow.ts

@@ -96,7 +96,16 @@ function countHfIdInSource(source: string, id: string): number {
   );
 }
 
-function resolveSnapshot(session: Composition, id: string): FlatEl | null {
+/**
+ * Resolvability the SDK DISPATCH path actually has (mirrors `resolveScoped`):
+ * exact scoped-path match, then canonical bare match, then first bare match.
+ *
+ * Exported so the cutover path can distinguish its two `target_not_found` cases:
+ * `Composition.getElement` is narrower (canonical-only for a bare id) than what
+ * `dispatch` resolves, so an element can be genuinely dispatchable yet still
+ * fail `getElement` — a resolver disagreement worth fixing, not a missing node.
+ */
+export function resolveSnapshot(session: Composition, id: string): FlatEl | null {
   const els = session.getElements();
   const exact = els.find((el) => el.scopedId === id);
   if (exact) return exact;