@hyperframes/studio 0.6.98 → 0.6.100

package/dist/assets/{index-D-bS9Dxx.js → index-CKWBqyRd.js}

@@ -1 +1 @@
-import{g as P}from"./index-Ce3pBm_I.js";function j(c,d){for(var s=0;s<d.length;s++){const a=d[s];if(typeof a!="string"&&!Array.isArray(a)){for(const i in a)if(i!=="default"&&!(i in c)){const l=Object.getOwnPropertyDescriptor(a,i);l&&Object.defineProperty(c,i,l.get?l:{enumerable:!0,get:()=>a[i]})}}}return Object.freeze(Object.defineProperty(c,Symbol.toStringTag,{value:"Module"}))}var v={},w;function k(){if(w)return v;w=1,Object.defineProperty(v,"__esModule",{value:!0}),v.default=d;var c=window.OfflineAudioContext||window.webkitOfflineAudioContext;function d(e){var r=a(e);return r.start(0),[i,y,O(e.sampleRate),s].reduce(function(t,o){return o(t)},r.buffer.getChannelData(0))}function s(e){return e.sort(function(r,t){return t.count-r.count}).splice(0,5)[0].tempo}function a(e){var r=e.length,t=e.numberOfChannels,o=e.sampleRate,n=new c(t,r,o),u=n.createBufferSource();u.buffer=e;var f=n.createBiquadFilter();return f.type="lowpass",u.connect(f),f.connect(n.destination),u}function i(e){for(var r=[],t=.9,o=.3,n=15;r.length<n&&t>=o;)r=l(e,t),t-=.05;if(r.length<n)throw new Error("Could not find enough samples for a reliable detection.");return r}function l(e,r){for(var t=[],o=0,n=e.length;o<n;o+=1)e[o]>r&&(t.push(o),o+=1e4);return t}function y(e){var r=[];return e.forEach(function(t,o){for(var n=function(x){var g=e[o+x]-t,_=r.some(function(h){if(h.interval===g)return h.count+=1});_||r.push({interval:g,count:1})},u=0;u<10;u+=1)n(u)}),r}function O(e){return function(r){var t=[];return r.forEach(function(o){if(o.interval!==0){for(var n=60/(o.interval/e);n<90;)n*=2;for(;n>180;)n/=2;n=Math.round(n);var u=t.some(function(f){if(f.tempo===n)return f.count+=o.count});u||t.push({tempo:n,count:o.count})}}),t}}return v}var p,b;function q(){return b||(b=1,p=k().default),p}var m=q();const A=P(m),D=j({__proto__:null,default:A},[m]);export{D as i};
+import{g as P}from"./index-BkT9VKwz.js";function j(c,d){for(var s=0;s<d.length;s++){const a=d[s];if(typeof a!="string"&&!Array.isArray(a)){for(const i in a)if(i!=="default"&&!(i in c)){const l=Object.getOwnPropertyDescriptor(a,i);l&&Object.defineProperty(c,i,l.get?l:{enumerable:!0,get:()=>a[i]})}}}return Object.freeze(Object.defineProperty(c,Symbol.toStringTag,{value:"Module"}))}var v={},w;function k(){if(w)return v;w=1,Object.defineProperty(v,"__esModule",{value:!0}),v.default=d;var c=window.OfflineAudioContext||window.webkitOfflineAudioContext;function d(e){var r=a(e);return r.start(0),[i,y,O(e.sampleRate),s].reduce(function(t,o){return o(t)},r.buffer.getChannelData(0))}function s(e){return e.sort(function(r,t){return t.count-r.count}).splice(0,5)[0].tempo}function a(e){var r=e.length,t=e.numberOfChannels,o=e.sampleRate,n=new c(t,r,o),u=n.createBufferSource();u.buffer=e;var f=n.createBiquadFilter();return f.type="lowpass",u.connect(f),f.connect(n.destination),u}function i(e){for(var r=[],t=.9,o=.3,n=15;r.length<n&&t>=o;)r=l(e,t),t-=.05;if(r.length<n)throw new Error("Could not find enough samples for a reliable detection.");return r}function l(e,r){for(var t=[],o=0,n=e.length;o<n;o+=1)e[o]>r&&(t.push(o),o+=1e4);return t}function y(e){var r=[];return e.forEach(function(t,o){for(var n=function(x){var g=e[o+x]-t,_=r.some(function(h){if(h.interval===g)return h.count+=1});_||r.push({interval:g,count:1})},u=0;u<10;u+=1)n(u)}),r}function O(e){return function(r){var t=[];return r.forEach(function(o){if(o.interval!==0){for(var n=60/(o.interval/e);n<90;)n*=2;for(;n>180;)n/=2;n=Math.round(n);var u=t.some(function(f){if(f.tempo===n)return f.count+=o.count});u||t.push({tempo:n,count:o.count})}}),t}}return v}var p,b;function q(){return b||(b=1,p=k().default),p}var m=q();const A=P(m),D=j({__proto__:null,default:A},[m]);export{D as i};

package/dist/assets/{index-D-ET9M0b.js → index-gpSohHUn.js}

@@ -1,4 +1,4 @@
-import{n as Qi}from"./index-Ce3pBm_I.js";/*!
+import{n as Qi}from"./index-BkT9VKwz.js";/*!
  * Copyright (c) 2026-present, Vanilagy and contributors
  *
  * This Source Code Form is subject to the terms of the Mozilla Public

package/dist/index.html

@@ -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-Ce3pBm_I.js"></script>
+    <script type="module" crossorigin src="/assets/index-BkT9VKwz.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-B62bDCQv.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.6.98",
+  "version": "0.6.100",
   "description": "",
   "repository": {
     "type": "git",
@@ -33,8 +33,9 @@
     "@phosphor-icons/react": "^2.1.10",
     "bpm-detective": "^2.0.5",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.6.98",
-    "@hyperframes/player": "0.6.98"
+    "@hyperframes/core": "0.6.100",
+    "@hyperframes/sdk": "0.6.100",
+    "@hyperframes/player": "0.6.100"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -48,7 +49,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.6.98"
+    "@hyperframes/producer": "0.6.100"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -13,6 +13,8 @@ import { usePreviewPersistence } from "./hooks/usePreviewPersistence";
 import { useTimelineEditing } from "./hooks/useTimelineEditing";
 import type { BlockPreviewInfo } from "./components/sidebar/BlocksTab";
 import { useDomEditSession } from "./hooks/useDomEditSession";
+import { useSdkSession } from "./hooks/useSdkSession";
+import { useSdkSelectionSync } from "./hooks/useSdkSelectionSync";
 import { useBlockHandlers } from "./hooks/useBlockHandlers";
 import { useAppHotkeys } from "./hooks/useAppHotkeys";
 import { useClipboard } from "./hooks/useClipboard";
@@ -265,6 +267,7 @@ export function StudioApp() {
     () => leftSidebarRef.current?.getTab() ?? "compositions",
     [],
   );
+  const sdkSession = useSdkSession(projectId, activeCompPath);
   const domEditSession = useDomEditSession({
     projectId,
     activeCompPath,
@@ -299,6 +302,7 @@ export function StudioApp() {
     openSourceForSelection: fileManager.openSourceForSelection,
     selectSidebarTab: selectSidebarTabStable,
     getSidebarTab: getSidebarTabStable,
+    sdkSession,
   });
   domEditSelectionBridgeRef.current = domEditSession.domEditSelection;
   clearDomSelectionRef.current = domEditSession.clearDomSelection;
@@ -314,6 +318,12 @@ export function StudioApp() {
       domEditSession.handleGsapRemoveKeyframe(a.id, p);
     }
   };
+  useSdkSelectionSync(
+    sdkSession,
+    domEditSession.domEditSelection,
+    domEditSession.domEditGroupSelections,
+  );
+
   useCaptionDetection({
     projectId,
     activeCompPath,
@@ -419,17 +429,6 @@ export function StudioApp() {
     applyDomSelection: domEditSession.applyDomSelection,
     initialState: initialUrlStateRef.current,
   });
-  const { jobs, isRendering, deleteRender, clearCompleted, startRender } = renderQueue;
-  const stableRenderQueue = useMemo(
-    () => ({
-      jobs,
-      isRendering,
-      deleteRender,
-      clearCompleted,
-      startRender: startRender as (options: unknown) => Promise<void>,
-    }),
-    [jobs, isRendering, deleteRender, clearCompleted, startRender],
-  );
   const studioCtxValue = buildStudioContextValue({
     projectId: projectId!,
     activeCompPath,
@@ -445,7 +444,7 @@ export function StudioApp() {
     editHistory,
     handleUndo: appHotkeys.handleUndo,
     handleRedo: appHotkeys.handleRedo,
-    renderQueue: stableRenderQueue,
+    renderQueue,
     compositionDimensions,
     waitForPendingDomEditSaves: previewPersistence.waitForPendingDomEditSaves,
     handlePreviewIframeRef,
@@ -485,7 +484,7 @@ export function StudioApp() {
                   refreshCaptureFrameTime={frameCapture.refreshCaptureFrameTime}
                   inspectorButtonActive={inspectorButtonActive}
                   inspectorPanelActive={inspectorPanelActive}
-                  onExport={() => void renderQueue.startRender()}
+                  onExport={() => void renderQueue.startRender(undefined)}
                 />
                 {previewPersistence.domEditSaveQueuePaused && (
                   <SaveQueuePausedBanner

package/src/components/editor/manualEditingAvailability.ts

@@ -88,4 +88,13 @@ export const STUDIO_GSAP_DRAG_INTERCEPT_ENABLED = resolveStudioBooleanEnvFlag(
 
 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.
+export const STUDIO_SDK_SHADOW_ENABLED = resolveStudioBooleanEnvFlag(
+  env,
+  ["VITE_STUDIO_SDK_SHADOW_ENABLED"],
+  false,
+);
+
 export const STUDIO_MANUAL_EDITING_DISABLED_TITLE = "Manual editing is temporarily disabled";

package/src/components/renders/useRenderQueue.ts

@@ -1,4 +1,4 @@
-import { useState, useEffect, useCallback, useRef } from "react";
+import { useState, useEffect, useCallback, useRef, useMemo } from "react";
 import { trackStudioRenderStart } from "../../telemetry/events";
 
 export interface RenderJob {
@@ -238,11 +238,15 @@ export function useRenderQueue(projectId: string | null) {
     };
   }, [projectId]);
 
-  return {
-    jobs,
-    startRender,
-    deleteRender,
-    clearCompleted,
-    isRendering: jobs.some((j) => j.status === "rendering"),
-  };
+  const isRendering = jobs.some((j) => j.status === "rendering");
+  return useMemo(
+    () => ({
+      jobs,
+      isRendering,
+      deleteRender,
+      clearCompleted,
+      startRender: startRender as (options: unknown) => Promise<void>,
+    }),
+    [jobs, isRendering, deleteRender, clearCompleted, startRender],
+  );
 }

package/src/hooks/useDomEditCommits.ts

@@ -9,14 +9,12 @@ import { buildDomEditPatchTarget, type DomEditSelection } from "../components/ed
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
 import type { PersistDomEditOperations } from "./domEditCommitTypes";
+import type { PatchOperation } from "../utils/sourcePatcher";
 import { useDomEditPositionPatchCommit } from "./useDomEditPositionPatchCommit";
 import { useDomEditTextCommits } from "./useDomEditTextCommits";
 import { useDomGeometryCommits } from "./useDomGeometryCommits";
 import { useElementLifecycleOps } from "./useElementLifecycleOps";
 
-// Re-export so existing consumers keep their import path
-export { GSAP_CSS_FALLBACK_BLOCKED_MESSAGE } from "./useDomGeometryCommits";
-
 // ── Helpers ──
 
 function formatUnsafeFieldList(fields: Array<{ path: string }>): string {
@@ -40,8 +38,6 @@ function formatPatchRejectionMessage(body: { error?: string; fields?: string[] }
   return `Couldn't save edit: ${body.error}${suffix}`;
 }
 
-// ── Types ──
-
 interface RecordEditInput {
   label: string;
   kind: EditHistoryKind;
@@ -49,8 +45,6 @@ interface RecordEditInput {
   files: Record<string, { before: string; after: string }>;
 }
 
-export type { PersistDomEditOperations } from "./domEditCommitTypes";
-
 export interface UseDomEditCommitsParams {
   activeCompPath: string | null;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
@@ -77,10 +71,10 @@ export interface UseDomEditCommitsParams {
     target: HTMLElement,
     options?: { preferClipAncestor?: boolean },
   ) => Promise<DomEditSelection | null>;
+  /** Stage 7 Step 3b: called after a successful server-side element patch. */
+  onDomEditPersisted?: (selection: DomEditSelection, operations: PatchOperation[]) => void;
 }
 
-// ── Hook ──
-
 export function useDomEditCommits({
   activeCompPath,
   previewIframeRef,
@@ -99,6 +93,7 @@ export function useDomEditCommits({
   clearDomSelection,
   refreshDomEditSelectionFromPreview,
   buildDomSelectionFromTarget,
+  onDomEditPersisted,
 }: UseDomEditCommitsParams) {
   const resolveImportedFontAsset = useCallback(
     (fontFamilyValue: string): ImportedFontAsset | null => {
@@ -220,6 +215,7 @@ export function useDomEditCommits({
         coalesceKey: options?.coalesceKey,
         files: { [targetPath]: { before: originalContent, after: finalContent } },
       });
+      onDomEditPersisted?.(selection, operations);
 
       if (!options?.skipRefresh) {
         reloadPreview();
@@ -233,6 +229,7 @@ export function useDomEditCommits({
       domEditSaveTimestampRef,
       reloadPreview,
       showToast,
+      onDomEditPersisted,
     ],
   );
 

package/src/hooks/useDomEditSession.ts

@@ -1,3 +1,4 @@
+import type { Composition } from "@hyperframes/sdk";
 import type { TimelineElement } from "../player";
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
@@ -8,6 +9,7 @@ import { useAskAgentModal } from "./useAskAgentModal";
 import { useDomSelection } from "./useDomSelection";
 import { usePreviewInteraction } from "./usePreviewInteraction";
 import { useDomEditCommits } from "./useDomEditCommits";
+import { runShadowDispatch } from "../utils/sdkShadow";
 import { useGsapScriptCommits } from "./useGsapScriptCommits";
 import { useGsapCacheVersion } from "./useGsapTweenCache";
 import { useDomEditWiring } from "./useDomEditWiring";
@@ -58,6 +60,8 @@ export interface UseDomEditSessionParams {
   openSourceForSelection?: (sourceFile: string, target: PatchTarget) => void;
   selectSidebarTab?: (tab: SidebarTab) => void;
   getSidebarTab?: () => SidebarTab;
+  /** Stage 7 Step 3b: SDK session for shadow dispatch parity tracking. */
+  sdkSession?: Composition | null;
 }
 
 // ── Hook ──
@@ -96,6 +100,7 @@ export function useDomEditSession({
   openSourceForSelection,
   selectSidebarTab,
   getSidebarTab,
+  sdkSession,
 }: UseDomEditSessionParams) {
   void _setRefreshKey;
   void _readProjectFile;
@@ -227,6 +232,9 @@ export function useDomEditSession({
     clearDomSelection,
     refreshDomEditSelectionFromPreview,
     buildDomSelectionFromTarget,
+    onDomEditPersisted: sdkSession
+      ? (sel, ops) => runShadowDispatch(sdkSession, sel, ops)
+      : undefined,
   });
 
   // ── Wiring: selection sync, GSAP cache, preview sync, selection handlers ──

package/src/hooks/useSdkSelectionSync.ts

@@ -0,0 +1,25 @@
+import { useEffect } from "react";
+import type { Composition } from "@hyperframes/sdk";
+import type { DomEditSelection } from "../components/editor/domEditing";
+
+function toHfIds(group: DomEditSelection[], primary: DomEditSelection | null): string[] {
+  const source = group.length > 0 ? group : primary ? [primary] : [];
+  return source.flatMap((s) => (s.hfId ? [s.hfId] : []));
+}
+
+/**
+ * Stage 7 Step 2 — mirrors Studio canvas selection into the SDK session.
+ *
+ * Calls session.setSelection(hfIds) whenever domEditSelection or
+ * domEditGroupSelections changes. Pure effect; no existing hook modified.
+ */
+export function useSdkSelectionSync(
+  session: Composition | null,
+  domEditSelection: DomEditSelection | null,
+  domEditGroupSelections: DomEditSelection[],
+): void {
+  useEffect(() => {
+    if (!session) return;
+    session.setSelection(toHfIds(domEditGroupSelections, domEditSelection));
+  }, [session, domEditSelection, domEditGroupSelections]);
+}

package/src/hooks/useSdkSession.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { shouldReloadSdkSession } from "./useSdkSession";
+
+describe("shouldReloadSdkSession", () => {
+  it("reloads when the changed file is the active composition", () => {
+    expect(shouldReloadSdkSession({ path: "scenes/intro.html" }, "scenes/intro.html")).toBe(true);
+  });
+
+  it("ignores changes to other files", () => {
+    expect(shouldReloadSdkSession({ path: "styles/main.css" }, "scenes/intro.html")).toBe(false);
+  });
+
+  it("ignores changes when no composition is active", () => {
+    expect(shouldReloadSdkSession({ path: "scenes/intro.html" }, null)).toBe(false);
+  });
+
+  it("ignores payloads with no resolvable path", () => {
+    expect(shouldReloadSdkSession({}, "scenes/intro.html")).toBe(false);
+  });
+});

package/src/hooks/useSdkSession.ts

@@ -0,0 +1,98 @@
+import { useState, useEffect } 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";
+
+/**
+ * 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.
+ */
+export function shouldReloadSdkSession(payload: unknown, activeCompPath: string | null): boolean {
+  if (!activeCompPath) return false;
+  return readStudioFileChangePath(payload) === activeCompPath;
+}
+
+/**
+ * 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
+ * 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 persist queue writes back to `activeCompPath` (not the
+ * "composition.html" default).
+ *
+ * The session is idle until Step 3c routes dispatch ops through it; re-opening
+ * is therefore purely additive — no SDK self-write exists yet, so there is no
+ * persist echo. Step 3c must add self-write suppression once dispatch writes.
+ */
+export function useSdkSession(
+  projectId: string | null,
+  activeCompPath: string | null,
+): Composition | null {
+  const [session, setSession] = useState<Composition | null>(null);
+  const [reloadToken, setReloadToken] = useState(0);
+
+  // ── Re-open on external change to the active composition ──
+  useEffect(() => {
+    if (!activeCompPath) return;
+    const handler = (payload?: unknown) => {
+      if (shouldReloadSdkSession(payload, activeCompPath)) {
+        setReloadToken((t) => t + 1);
+      }
+    };
+    if (import.meta.hot) {
+      import.meta.hot.on("hf:file-change", handler);
+      return () => import.meta.hot?.off?.("hf:file-change", handler);
+    }
+    // SSE fallback for the embedded studio server.
+    const es = new EventSource("/api/events");
+    es.addEventListener("file-change", handler);
+    return () => es.close();
+  }, [activeCompPath]);
+
+  // ── Open / re-open the session ──
+  useEffect(() => {
+    if (!projectId || !activeCompPath) {
+      setSession(null);
+      return;
+    }
+
+    let cancelled = false;
+    let comp: Composition | null = null;
+
+    const adapter = createHttpAdapter({
+      projectFilesUrl: `/api/projects/${projectId}`,
+    });
+    adapter
+      .read(activeCompPath)
+      .then(async (content) => {
+        if (cancelled || typeof content !== "string") return;
+        comp = await openComposition(content, {
+          persist: adapter,
+          persistPath: activeCompPath,
+        });
+        comp.on("persist:error", (e) => {
+          console.warn("[sdk] persist:error", e.error);
+        });
+        // Cleanup may have fired while openComposition was awaited; dispose immediately.
+        if (cancelled) {
+          comp.dispose();
+          return;
+        }
+        setSession(comp);
+      })
+      .catch(() => {
+        if (!cancelled) setSession(null);
+      });
+
+    return () => {
+      cancelled = true;
+      const c = comp;
+      if (c) void c.flush().finally(() => c.dispose());
+    };
+  }, [projectId, activeCompPath, reloadToken]);
+
+  return session;
+}

package/src/utils/sdkShadow.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "vitest";
+import { patchOpsToSdkEditOps, SdkShadowMismatch } from "./sdkShadow";
+import type { PatchOperation } from "./sourcePatcher";
+import { openComposition } from "@hyperframes/sdk";
+
+const BASE_HTML = /* html */ `<!DOCTYPE html>
+<html><body>
+  <div data-hf-id="hf-box" style="color: red; width: 100px;" data-name="box">Hello</div>
+</body></html>`;
+
+describe("patchOpsToSdkEditOps", () => {
+  it("maps inline-style ops to a single setStyle EditOp", () => {
+    const ops: PatchOperation[] = [
+      { type: "inline-style", property: "color", value: "#00f" },
+      { type: "inline-style", property: "opacity", value: "0.5" },
+    ];
+    const result = patchOpsToSdkEditOps("hf-box", ops);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({
+      type: "setStyle",
+      target: "hf-box",
+      styles: { color: "#00f", opacity: "0.5" },
+    });
+  });
+
+  it("maps text-content op to setText EditOp", () => {
+    const ops: PatchOperation[] = [{ type: "text-content", property: "text", value: "World" }];
+    const result = patchOpsToSdkEditOps("hf-box", ops);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({ type: "setText", target: "hf-box", value: "World" });
+  });
+
+  it("maps attribute op to setAttribute with data- prefix", () => {
+    const ops: PatchOperation[] = [{ type: "attribute", property: "name", value: "hero" }];
+    const result = patchOpsToSdkEditOps("hf-box", ops);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({
+      type: "setAttribute",
+      target: "hf-box",
+      name: "data-name",
+      value: "hero",
+    });
+  });
+
+  it("maps html-attribute op to setAttribute without prefix", () => {
+    const ops: PatchOperation[] = [
+      { type: "html-attribute", property: "contenteditable", value: "true" },
+    ];
+    const result = patchOpsToSdkEditOps("hf-box", ops);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({
+      type: "setAttribute",
+      target: "hf-box",
+      name: "contenteditable",
+      value: "true",
+    });
+  });
+
+  it("handles null value for attribute removal", () => {
+    const ops: PatchOperation[] = [{ type: "html-attribute", property: "hidden", value: null }];
+    const result = patchOpsToSdkEditOps("hf-box", ops);
+    expect(result[0]).toEqual({
+      type: "setAttribute",
+      target: "hf-box",
+      name: "hidden",
+      value: null,
+    });
+  });
+
+  it("returns empty array for unknown op types", () => {
+    const ops = [{ type: "unknown-op", property: "x", value: "y" }] as unknown as PatchOperation[];
+    expect(patchOpsToSdkEditOps("hf-box", ops)).toHaveLength(0);
+  });
+});
+
+describe("sdkShadowDispatch (integration)", () => {
+  it("applies ops and returns no mismatches when SDK matches expected values", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const session = await openComposition(BASE_HTML);
+
+    const ops: PatchOperation[] = [{ type: "inline-style", property: "color", value: "#00f" }];
+    const result = sdkShadowDispatch(session, "hf-box", ops);
+
+    expect(result.dispatched).toBe(true);
+    expect(result.mismatches).toHaveLength(0);
+    expect(session.getElement("hf-box")?.inlineStyles.color).toBe("#00f");
+  });
+
+  it("returns dispatched:false when hfId not found in session", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const session = await openComposition(BASE_HTML);
+
+    const ops: PatchOperation[] = [{ type: "inline-style", property: "color", value: "#00f" }];
+    const result = sdkShadowDispatch(session, "hf-missing", ops);
+
+    expect(result.dispatched).toBe(false);
+    expect(result.mismatches).toHaveLength(1);
+    expect(result.mismatches[0]).toMatchObject<SdkShadowMismatch>({
+      kind: "element_not_found",
+      hfId: "hf-missing",
+    });
+  });
+
+  it("applies text op and reads back via session.getElement", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const session = await openComposition(BASE_HTML);
+
+    const ops: PatchOperation[] = [{ type: "text-content", property: "text", value: "Updated" }];
+    sdkShadowDispatch(session, "hf-box", ops);
+
+    expect(session.getElement("hf-box")?.text).toBe("Updated");
+  });
+
+  it("applies attribute op and reads back via session.getElement", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const session = await openComposition(BASE_HTML);
+
+    const ops: PatchOperation[] = [{ type: "attribute", property: "name", value: "hero" }];
+    sdkShadowDispatch(session, "hf-box", ops);
+
+    expect(session.getElement("hf-box")?.attributes["data-name"]).toBe("hero");
+  });
+
+  it("returns dispatch_error when dispatch throws — does not propagate", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const session = await openComposition(BASE_HTML);
+    // Poison dispatch so it throws on any call
+    session.dispatch = () => {
+      throw new Error("sdk internal error");
+    };
+
+    const ops: PatchOperation[] = [{ type: "inline-style", property: "color", value: "red" }];
+    let result: ReturnType<typeof sdkShadowDispatch> | undefined;
+    expect(() => {
+      result = sdkShadowDispatch(session, "hf-box", ops);
+    }).not.toThrow();
+
+    expect(result!.dispatched).toBe(false);
+    expect(result!.mismatches).toHaveLength(1);
+    expect(result!.mismatches[0]).toMatchObject<SdkShadowMismatch>({
+      kind: "dispatch_error",
+      hfId: "hf-box",
+      error: expect.stringContaining("sdk internal error"),
+    });
+  });
+});