fix(sdk): cross-realm origin sentinel, dual width/height channel, contract docs

Round-2 review (Rames/Miguel) on the engine layer:

- ORIGIN_APPLY_PATCHES: unique symbol → namespaced string
  ('@hyperframes/sdk:applyPatches'). Symbols are realm-local — they don't
  survive postMessage/structured-clone, which T3 embedded hosts may forward
  patch events across. Namespaced string keeps collision risk negligible.
- setCompositionMetadata width/height: runtime treats data-width/data-height
  as a forced override of inline style (init.ts applyCompositionSizing).
  Style is always written; the data-* attr is updated when already present
  so the edit isn't clobbered on load. Absent attrs stay absent — inverses
  stay exact. Mirrored in the patch applier; 3 new tests.
- JsonPatchOp documented as the emit-only RFC 6902 subset
  (add/remove/replace); applier header notes move/copy/test are ignored.
- SdkDocument.html documented as a build-time snapshot (serialize() is the
  live state).
- patches.ts path-grammar comment fixed: timing/{start|end|trackIndex}.

NOT changed (with reasons, see PR reply): moveElement left/top matches
Studio's own inline-style commit convention (sourcePatcher); package version
follows the repo-wide single-version policy.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: vanceingalls

packages/sdk/src/engine/apply-patches.ts

@@ -3,6 +3,9 @@
  *
  * Not a general-purpose JSON Patch implementation. Translates the well-defined path
  * grammar back into DOM mutations. Used by applyPatches() for host undo (T3 mode).
+ *
+ * Supports only the emit subset (add/remove/replace) — move/copy/test ops and
+ * unknown paths are silently ignored, matching the JsonPatchOp contract.
  */
 
 import type { JsonPatchOp } from "../types.js";
@@ -164,12 +167,26 @@ function applyOne(parsed: ParsedDocument, patch: JsonPatchOp, p: ParsedPath): vo
     case "metadata": {
       const root = findRoot(parsed.document);
       if (!root || !p.field) return;
+      // Mirror mutate.ts: style always written; the data-* forced-override
+      // attribute is updated only when the composition already carries it.
       if (p.field === "width") {
-        if (patch.op === "remove") setElementStyles(root, { width: null });
-        else setElementStyles(root, { width: `${patch.value}px` });
+        if (patch.op === "remove") {
+          setElementStyles(root, { width: null });
+          root.removeAttribute("data-width");
+        } else {
+          setElementStyles(root, { width: `${patch.value}px` });
+          if (root.hasAttribute("data-width")) root.setAttribute("data-width", String(patch.value));
+        }
       } else if (p.field === "height") {
-        if (patch.op === "remove") setElementStyles(root, { height: null });
-        else setElementStyles(root, { height: `${patch.value}px` });
+        if (patch.op === "remove") {
+          setElementStyles(root, { height: null });
+          root.removeAttribute("data-height");
+        } else {
+          setElementStyles(root, { height: `${patch.value}px` });
+          if (root.hasAttribute("data-height")) {
+            root.setAttribute("data-height", String(patch.value));
+          }
+        }
       } else if (p.field === "duration") {
         if (patch.op === "remove") root.removeAttribute("data-duration");
         else root.setAttribute("data-duration", String(patch.value));

packages/sdk/src/engine/mutate.test.ts

@@ -388,3 +388,38 @@ describe("Phase 3b ops", () => {
     ).toBe(false);
   });
 });
+
+// ─── setCompositionMetadata — data-width/data-height forced override ─────────
+
+describe("setCompositionMetadata data-* channel", () => {
+  const ATTR_HTML = `
+<div data-hf-id="hf-stage" data-hf-root data-width="1280" data-height="720" style="width: 1280px; height: 720px">
+  <h1 data-hf-id="hf-title">Hi</h1>
+</div>
+`.trim();
+
+  it("updates data-width/data-height when the composition carries them", () => {
+    const parsed = parseMutable(ATTR_HTML);
+    applyOp(parsed, { type: "setCompositionMetadata", width: 1920, height: 1080 });
+    const root = parsed.document.querySelector("[data-hf-root]");
+    expect(root?.getAttribute("data-width")).toBe("1920");
+    expect(root?.getAttribute("data-height")).toBe("1080");
+    expect(root?.getAttribute("style")).toContain("width: 1920px");
+  });
+
+  it("inverse restores both channels", () => {
+    const parsed = parseMutable(ATTR_HTML);
+    const before = serializeDocument(parsed);
+    const { inverse } = applyOp(parsed, { type: "setCompositionMetadata", width: 1920 });
+    applyPatchesToDocument(parsed, inverse);
+    expect(serializeDocument(parsed)).toBe(before);
+  });
+
+  it("does not mint data-* attributes on compositions without them", () => {
+    const parsed = fresh();
+    applyOp(parsed, { type: "setCompositionMetadata", width: 1920 });
+    const root = parsed.document.querySelector("[data-hf-root]");
+    expect(root?.hasAttribute("data-width")).toBe(false);
+    expect(root?.getAttribute("style")).toContain("width: 1920px");
+  });
+});

packages/sdk/src/engine/mutate.ts

@@ -304,11 +304,18 @@ function handleSetCompositionMetadata(
   const root = findRoot(parsed.document);
   if (!root) return result;
 
+  // The runtime treats data-width/data-height as a FORCED override of inline
+  // style when present (core/runtime/init.ts applyCompositionSizing). So:
+  // style is always written; the data-* attribute is updated only when the
+  // composition already carries it — otherwise a style-only write would be
+  // clobbered on load. Absent attributes stay absent (keeps inverses exact).
   if (op.width !== undefined) {
     const styles = getElementStyles(root);
-    const oldWidth = styles["width"] ?? null;
+    const oldAttr = root.getAttribute("data-width");
+    const oldWidth = oldAttr ?? styles["width"] ?? null;
     const newVal = `${op.width}px`;
     setElementStyles(root, { width: newVal });
+    if (oldAttr !== null) root.setAttribute("data-width", String(op.width));
     const path = metaPath("width");
     const p = scalarChange(path, oldWidth !== null ? parseFloat(oldWidth) : null, op.width);
     result.forward.push(p.forward);
@@ -317,9 +324,11 @@ function handleSetCompositionMetadata(
 
   if (op.height !== undefined) {
     const styles = getElementStyles(root);
-    const oldHeight = styles["height"] ?? null;
+    const oldAttr = root.getAttribute("data-height");
+    const oldHeight = oldAttr ?? styles["height"] ?? null;
     const newVal = `${op.height}px`;
     setElementStyles(root, { height: newVal });
+    if (oldAttr !== null) root.setAttribute("data-height", String(op.height));
     const path = metaPath("height");
     const p = scalarChange(path, oldHeight !== null ? parseFloat(oldHeight) : null, op.height);
     result.forward.push(p.forward);

packages/sdk/src/engine/patches.ts

@@ -5,7 +5,7 @@
  *   /elements/{hfId}/inlineStyles/{camelCaseProp}
  *   /elements/{hfId}/text
  *   /elements/{hfId}/attributes/{name}
- *   /elements/{hfId}/timing/{start|duration|trackIndex}
+ *   /elements/{hfId}/timing/{start|end|trackIndex}   ← end = computed absolute data-end
  *   /elements/{hfId}/hold/{start|end|fill}
  *   /elements/{hfId}                        ← whole subtree (removeElement)
  *   /variables/{variableId}

packages/sdk/src/types.ts

@@ -28,7 +28,10 @@ export interface SdkDocument {
   readonly width: number | null;
   readonly height: number | null;
   readonly compositionDuration: number | null;
-  /** ensureHfIds-stamped HTML used as the source of truth for serialization */
+  /**
+   * BUILD-TIME snapshot of the ensureHfIds-stamped HTML. Never updated after
+   * mutations — use Composition.serialize() for the current document state.
+   */
   readonly html: string;
 }
 
@@ -105,6 +108,11 @@ export interface GsapTweenSpec {
 
 // ─── Patch layer (F2: RFC 6902 frozen contract) ───────────────────────────────
 
+/**
+ * Emit-only subset of RFC 6902: the SDK never emits move/copy/test, and
+ * applyPatches() ignores ops outside this subset. Hosts feeding patches back
+ * must restrict themselves to add/remove/replace.
+ */
 export interface JsonPatchOp {
   op: "add" | "remove" | "replace";
   path: string;
@@ -131,8 +139,13 @@ export interface PatchEvent {
  * Reserved origin tag for applyPatches().
  * Host listeners MUST skip this origin to prevent undo loops:
  *   comp.on('patch', ({ origin }) => { if (origin === ORIGIN_APPLY_PATCHES) return; ... })
+ *
+ * A namespaced string (not a unique symbol) so the sentinel survives realm
+ * boundaries — postMessage, structured clone, JSON — which T3 embedded hosts
+ * may forward patch events across. The namespace prefix keeps collision risk
+ * with host-chosen origins negligible.
  */
-export const ORIGIN_APPLY_PATCHES: unique symbol = Symbol("applyPatches");
+export const ORIGIN_APPLY_PATCHES = "@hyperframes/sdk:applyPatches" as const;
 
 /** Default origin when none specified — UI-driven dispatch. */
 export const ORIGIN_LOCAL = "local" as const;