From fbb4408cebd410f2724ee9752b5ce9e04f0c7834 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Mon, 15 Jun 2026 14:12:25 -0700 Subject: [PATCH 1/5] feat(studio): default SDK shadow dispatch on for parity telemetry Shadow mode keeps the server patch path authoritative (no user-visible change) and emits sdk_shadow_dispatch parity signal. Default it on so we collect addressing/serialize-drift telemetry from all traffic before any cutover. Disable via VITE_STUDIO_SDK_SHADOW_ENABLED=false. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../src/components/editor/manualEditingAvailability.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/studio/src/components/editor/manualEditingAvailability.ts b/packages/studio/src/components/editor/manualEditingAvailability.ts index e2d74d8ad..6a67ab97f 100644 --- a/packages/studio/src/components/editor/manualEditingAvailability.ts +++ b/packages/studio/src/components/editor/manualEditingAvailability.ts @@ -90,11 +90,13 @@ export const STUDIO_PREVIEW_SELECTION_ENABLED = STUDIO_INSPECTOR_PANELS_ENABLED; // Stage 7 Step 3b: shadow dispatch parity mode — dispatches ops to the SDK // session alongside the server patch path and logs mismatches via telemetry. -// Default false in production; enable via VITE_STUDIO_SDK_SHADOW_ENABLED=true. +// Default on: server stays authoritative (no user-visible change), so we want +// the sdk_shadow_dispatch parity signal from all traffic. Disable via +// VITE_STUDIO_SDK_SHADOW_ENABLED=false. export const STUDIO_SDK_SHADOW_ENABLED = resolveStudioBooleanEnvFlag( env, ["VITE_STUDIO_SDK_SHADOW_ENABLED"], - false, + true, ); export const STUDIO_MANUAL_EDITING_DISABLED_TITLE = "Manual editing is temporarily disabled"; From 00f4981f7e0f3067ac6c7a008eff2f366a674b66 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Mon, 15 Jun 2026 14:27:30 -0700 Subject: [PATCH 2/5] feat(studio): shadow parity for delete/timing/gsap ops + wire delete MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extends shadow visibility past the property-edit path. Adds a can()-first shadow core (pure addressing/validity pre-check, works even for GSAP which has no snapshot value) plus runShadowDelete/runShadowTiming/runShadowGsapTween. Parity coverage: delete = getElement null (full); timing = snapshot start/duration/trackIndex (full); gsap = can()+dispatch+returned-id only (animationIds is a stub, tween values are script-level — full fidelity needs serialize() round-trip diffing, out of scope). Wires the delete runner end-to-end via an onElementDeleted callback (useDomEditSession → useDomEditCommits → useElementLifecycleOps), fired after the server delete succeeds. Server stays authoritative. Timing/GSAP wiring follows (each needs threading sdkSession into useTimelineEditing / useGsapScriptCommits). Co-Authored-By: Claude Opus 4.8 (1M context) --- .../studio/src/hooks/useDomEditCommits.ts | 4 + .../studio/src/hooks/useDomEditSession.ts | 3 +- .../src/hooks/useElementLifecycleOps.ts | 5 + packages/studio/src/utils/sdkShadow.test.ts | 104 +++++++++- packages/studio/src/utils/sdkShadow.ts | 180 +++++++++++++++++- 5 files changed, 292 insertions(+), 4 deletions(-) diff --git a/packages/studio/src/hooks/useDomEditCommits.ts b/packages/studio/src/hooks/useDomEditCommits.ts index 3eacd3899..979c6dc40 100644 --- a/packages/studio/src/hooks/useDomEditCommits.ts +++ b/packages/studio/src/hooks/useDomEditCommits.ts @@ -73,6 +73,8 @@ export interface UseDomEditCommitsParams { ) => Promise; /** Stage 7 Step 3b: called after a successful server-side element patch. */ onDomEditPersisted?: (selection: DomEditSelection, operations: PatchOperation[]) => void; + /** Stage 7 Step 3b: called after a successful server-side element delete. */ + onElementDeleted?: (selection: DomEditSelection) => void; } export function useDomEditCommits({ @@ -94,6 +96,7 @@ export function useDomEditCommits({ refreshDomEditSelectionFromPreview, buildDomSelectionFromTarget, onDomEditPersisted, + onElementDeleted, }: UseDomEditCommitsParams) { const resolveImportedFontAsset = useCallback( (fontFamilyValue: string): ImportedFontAsset | null => { @@ -290,6 +293,7 @@ export function useDomEditCommits({ reloadPreview, clearDomSelection, commitPositionPatchToHtml, + onElementDeleted, }); return { diff --git a/packages/studio/src/hooks/useDomEditSession.ts b/packages/studio/src/hooks/useDomEditSession.ts index 848fc9f5f..fe46ab0ce 100644 --- a/packages/studio/src/hooks/useDomEditSession.ts +++ b/packages/studio/src/hooks/useDomEditSession.ts @@ -9,7 +9,7 @@ import { useAskAgentModal } from "./useAskAgentModal"; import { useDomSelection } from "./useDomSelection"; import { usePreviewInteraction } from "./usePreviewInteraction"; import { useDomEditCommits } from "./useDomEditCommits"; -import { runShadowDispatch } from "../utils/sdkShadow"; +import { runShadowDispatch, runShadowDelete } from "../utils/sdkShadow"; import { useGsapScriptCommits } from "./useGsapScriptCommits"; import { useGsapCacheVersion } from "./useGsapTweenCache"; import { useDomEditWiring } from "./useDomEditWiring"; @@ -235,6 +235,7 @@ export function useDomEditSession({ onDomEditPersisted: sdkSession ? (sel, ops) => runShadowDispatch(sdkSession, sel, ops) : undefined, + onElementDeleted: sdkSession ? (sel) => runShadowDelete(sdkSession, sel.hfId) : undefined, }); // ── Wiring: selection sync, GSAP cache, preview sync, selection handlers ── diff --git a/packages/studio/src/hooks/useElementLifecycleOps.ts b/packages/studio/src/hooks/useElementLifecycleOps.ts index 0429e9c74..a30c5bb03 100644 --- a/packages/studio/src/hooks/useElementLifecycleOps.ts +++ b/packages/studio/src/hooks/useElementLifecycleOps.ts @@ -31,6 +31,8 @@ interface UseElementLifecycleOpsParams { patches: PatchOperation[], options: { label: string; coalesceKey: string; skipRefresh?: boolean }, ) => Promise; + /** Stage 7 Step 3b: called after a successful server-side element delete (shadow). */ + onElementDeleted?: (selection: DomEditSelection) => void; } export function useElementLifecycleOps({ @@ -43,6 +45,7 @@ export function useElementLifecycleOps({ reloadPreview, clearDomSelection, commitPositionPatchToHtml, + onElementDeleted, }: UseElementLifecycleOpsParams) { // fallow-ignore-next-line complexity const handleDomEditElementDelete = useCallback( @@ -103,6 +106,7 @@ export function useElementLifecycleOps({ clearDomSelection(); usePlayerStore.getState().setSelectedElementId(null); reloadPreview(); + onElementDeleted?.(selection); showToast(`Deleted ${label}. Use Undo to restore it.`, "info"); } catch (error) { const message = error instanceof Error ? error.message : "Failed to delete element"; @@ -114,6 +118,7 @@ export function useElementLifecycleOps({ clearDomSelection, domEditSaveTimestampRef, editHistory.recordEdit, + onElementDeleted, projectIdRef, reloadPreview, showToast, diff --git a/packages/studio/src/utils/sdkShadow.test.ts b/packages/studio/src/utils/sdkShadow.test.ts index 637ab9ba5..efc15fd1a 100644 --- a/packages/studio/src/utils/sdkShadow.test.ts +++ b/packages/studio/src/utils/sdkShadow.test.ts @@ -1,8 +1,26 @@ -import { describe, expect, it } from "vitest"; -import { patchOpsToSdkEditOps, SdkShadowMismatch } from "./sdkShadow"; +import { describe, expect, it, vi, beforeEach } from "vitest"; +import { + patchOpsToSdkEditOps, + runShadowDelete, + runShadowTiming, + runShadowGsapTween, + SdkShadowMismatch, +} 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 }> = []; +vi.mock("./studioTelemetry", () => ({ + trackStudioEvent: (event: string, props: Record) => + 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 */ `
Hello
@@ -144,3 +162,85 @@ describe("sdkShadowDispatch (integration)", () => { }); }); }); + +const TIMING_HTML = /* html */ ` + +
clip
+`; + +const GSAP_HTML = `
+
+ +
`; + +const NO_TIMELINE_HTML = `
+
+ +
`; + +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("dispatches add against a real timeline and reports success", async () => { + const session = await openComposition(GSAP_HTML); + runShadowGsapTween(session, { + kind: "add", + target: "hf-box", + tween: { method: "to", properties: { x: 100 }, duration: 0.5 }, + }); + 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", + }); + }); +}); diff --git a/packages/studio/src/utils/sdkShadow.ts b/packages/studio/src/utils/sdkShadow.ts index c5ec855aa..1c693e960 100644 --- a/packages/studio/src/utils/sdkShadow.ts +++ b/packages/studio/src/utils/sdkShadow.ts @@ -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"; @@ -191,6 +191,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 +200,185 @@ 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), }); } + +// ─── 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 } + | { kind: "remove"; animationId: string }; + +/** + * Shadow a GSAP tween mutation. Snapshot value-parity is NOT available: the + * tween lives in the GSAP