fix(sdk): coalesce history by patch paths; replay override-set on open

Adversarial-review findings F1 + F2:

- history: coalescing now requires identical patch paths in addition to
  op types + origin + window. Previously two rapid setStyle calls on
  DIFFERENT elements merged into one entry carrying the second forward +
  first inverse — undo then reverted the wrong element and stranded the
  latest edit. Slider drags on one property still coalesce.
- T3 init: openComposition({ overrides }) now replays the stored
  override-set onto the freshly-parsed base before exposing the session
  (new keyToPath inverse mapping + applyOverrideSet). Previously the
  overrides were copied into the map but never applied — reopening an
  embedded composition showed and serialized the base template.
- examples: GSAP calls now feature-detect with can() (Phase 3b ops throw
  UnsupportedOpError as of the engine-layer fix); UnsupportedOpError
  re-exported from the package entry.
- 8 new session tests: coalesce same-path / cross-element / cross-prop,
  override round-trip (style/text/attr/timing/removal/restore-base).

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

Author: vanceingalls

packages/sdk/examples/headless-agent.ts

@@ -111,15 +111,26 @@ export async function addStaggeredEntrance(html: string, staggerDelay = 0.15): P
 
   const textEls = comp.find({ tag: "div" });
 
+  // Phase 3b feature-detect: addGsapTween throws UnsupportedOpError until the
+  // parser-backed engine lands — skip animation rather than crash the job.
+  const probeTween = {
+    method: "from",
+    position: 0,
+    duration: 0.5,
+    ease: "power3.out",
+    fromProperties: { opacity: 0, y: 30 },
+  } as const;
+  const first = textEls[0];
+  if (
+    !first ||
+    !comp.can({ type: "addGsapTween", target: first, id: "preflight", tween: probeTween })
+  ) {
+    return comp.serialize();
+  }
+
   comp.batch(() => {
     textEls.forEach((id, i) => {
-      comp.addGsapTween(id, {
-        method: "from",
-        position: i * staggerDelay,
-        duration: 0.5,
-        ease: "power3.out",
-        fromProperties: { opacity: 0, y: 30 },
-      });
+      comp.addGsapTween(id, { ...probeTween, position: i * staggerDelay });
     });
   });
 

packages/sdk/examples/react-embed.ts

@@ -87,17 +87,23 @@ export function onClipDrag(comp: Composition, id: string, start: number, duratio
 
 // ── GSAP animation panel ──────────────────────────────────────────────────────
 
-export function addBounceIn(comp: Composition, targetId: string): string {
-  return comp.addGsapTween(targetId, {
+// Phase 3b: GSAP ops throw UnsupportedOpError until the parser-backed engine
+// lands — feature-detect with can() and disable the panel control if false.
+
+export function addBounceIn(comp: Composition, targetId: string): string | null {
+  const tween = {
     method: "from",
     position: 0,
     duration: 0.5,
     ease: "bounce.out",
     fromProperties: { y: 40, opacity: 0 },
-  });
+  } as const;
+  if (!comp.can({ type: "addGsapTween", target: targetId, id: "preflight", tween })) return null;
+  return comp.addGsapTween(targetId, tween);
 }
 
 export function updateEase(comp: Composition, animationId: string, ease: string): void {
+  if (!comp.can({ type: "setGsapTween", animationId, properties: { ease } })) return;
   comp.setGsapTween(animationId, { ease });
 }
 

packages/sdk/examples/vanilla-editor.ts

@@ -102,29 +102,36 @@ export function applyOpFromJson(comp: Composition, opJson: unknown): void {
 
 // ── GSAP operations ───────────────────────────────────────────────────────────
 
-export function addFadeIn(comp: Composition, targetId: string, delay = 0): string {
-  return comp.addGsapTween(targetId, {
+// NOTE (Phase 3b): GSAP ops require the parser-backed engine and throw
+// UnsupportedOpError until it lands. Feature-detect with can() first.
+
+export function addFadeIn(comp: Composition, targetId: string, delay = 0): string | null {
+  const tween: GsapTweenSpec = {
     method: "from",
     position: delay,
     duration: 0.4,
     ease: "power2.out",
     fromProperties: { opacity: 0 },
-  });
+  };
+  if (!comp.can({ type: "addGsapTween", target: targetId, id: "preflight", tween })) return null;
+  return comp.addGsapTween(targetId, tween);
 }
 
 export function addBounce(
   comp: Composition,
   targetId: string,
   overrides?: Partial<GsapTweenSpec>,
-): string {
-  return comp.addGsapTween(targetId, {
+): string | null {
+  const tween: GsapTweenSpec = {
     method: "from",
     position: 0,
     duration: 0.6,
     ease: "bounce.out",
     fromProperties: { y: 60, opacity: 0 },
     ...overrides,
-  });
+  };
+  if (!comp.can({ type: "addGsapTween", target: targetId, id: "preflight", tween })) return null;
+  return comp.addGsapTween(targetId, tween);
 }
 
 // Keyframe editing (addGsapKeyframe / removeGsapKeyframe — v1, promoted 2026-06-09):

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

@@ -8,9 +8,10 @@
  * unknown paths are silently ignored, matching the JsonPatchOp contract.
  */
 
-import type { JsonPatchOp } from "../types.js";
+import type { JsonPatchOp, OverrideSet } from "../types.js";
 import type { ParsedDocument } from "./model.js";
 import { findById, findRoot, setElementStyles, setOwnText } from "./model.js";
+import { keyToPath } from "./patches.js";
 
 // ─── Path parser ────────────────────────────────────────────────────────────
 
@@ -56,6 +57,25 @@ function parsePath(path: string): ParsedPath | null {
 
 // ─── Patch application ───────────────────────────────────────────────────────
 
+/**
+ * Replay a stored override-set onto a freshly-parsed base document (T3 init).
+ * Property keys with null mean "restore base value" — a no-op on a fresh base.
+ * Bare element keys with null are removal markers — the element is removed.
+ */
+export function applyOverrideSet(parsed: ParsedDocument, overrides: OverrideSet): void {
+  const patches: JsonPatchOp[] = [];
+  for (const [key, value] of Object.entries(overrides)) {
+    const path = keyToPath(key);
+    if (!path) continue;
+    if (value === null) {
+      if (!key.includes(".")) patches.push({ op: "remove", path });
+      continue;
+    }
+    patches.push({ op: "replace", path, value });
+  }
+  applyPatchesToDocument(parsed, patches);
+}
+
 export function applyPatchesToDocument(
   parsed: ParsedDocument,
   patches: readonly JsonPatchOp[],

packages/sdk/src/engine/mutate.ts

@@ -53,9 +53,10 @@ const PHASE3B_OPS = new Set([
   "removeLabel",
 ]);
 
-// Re-exported from the package entry in the next stacked PR (#1325).
-// fallow-ignore-next-line unused-export
 export class UnsupportedOpError extends Error {
+  // Stable error code — part of the public API contract (F7); hosts switch on
+  // err.code rather than the message.
+  // fallow-ignore-next-line unused-class-member
   readonly code = "E_UNSUPPORTED_OP";
   constructor(opType: string) {
     super(

packages/sdk/src/engine/patches.ts

@@ -103,6 +103,38 @@ export function pathToKey(path: string): string | null {
   return null;
 }
 
+/**
+ * Inverse of pathToKey — maps an override-set key back to its RFC 6902 path.
+ * Used to replay a stored override-set onto a fresh base document (T3 init).
+ */
+export function keyToPath(key: string): string | null {
+  const style = /^([^.]+)\.style\.(.+)$/.exec(key);
+  if (style?.[1] && style[2]) return stylePath(style[1], style[2]);
+
+  const text = /^([^.]+)\.text$/.exec(key);
+  if (text?.[1]) return textPath(text[1]);
+
+  const attr = /^([^.]+)\.attr\.(.+)$/.exec(key);
+  if (attr?.[1] && attr[2]) return attrPath(attr[1], attr[2]);
+
+  const timing = /^([^.]+)\.timing\.(start|end|trackIndex)$/.exec(key);
+  if (timing?.[1]) return timingPath(timing[1], timing[2] as "start" | "end" | "trackIndex");
+
+  const hold = /^([^.]+)\.hold\.(start|end|fill)$/.exec(key);
+  if (hold?.[1]) return holdPath(hold[1], hold[2] as "start" | "end" | "fill");
+
+  const variable = /^var\.(.+)$/.exec(key);
+  if (variable?.[1]) return variablePath(variable[1]);
+
+  const meta = /^meta\.(width|height|duration)$/.exec(key);
+  if (meta) return metaPath(meta[1] as "width" | "height" | "duration");
+
+  // Bare element id — removal marker key.
+  if (!key.includes(".")) return elementPath(key);
+
+  return null;
+}
+
 // ─── Patch event builder ──────────────────────────────────────────────────────
 
 export function buildPatchEvent(

packages/sdk/src/history.ts

@@ -55,9 +55,21 @@ export function createHistory(session: Composition, opts: HistoryOptions = {}):
     return trackedOrigins.includes(origin);
   }
 
+  function pathsKey(patches: readonly JsonPatchOp[]): string {
+    return patches
+      .map((p) => p.path)
+      .sort()
+      .join("\n");
+  }
+
   function shouldCoalesce(entry: HistoryEntry, incoming: PatchEvent): boolean {
     if (entry.opTypes.join(",") !== incoming.opTypes.join(",")) return false;
     if (entry.origin !== incoming.origin) return false;
+    // Coalesce only when the SAME paths are touched (e.g. slider drag on one
+    // property). Without this, rapid edits to different elements would merge
+    // into one entry holding the second forward + first inverse — undo would
+    // then revert the wrong element.
+    if (pathsKey(entry.patches) !== pathsKey(incoming.patches)) return false;
     const now = Date.now();
     return now - entry.timestamp <= coalesceMs;
   }

packages/sdk/src/index.ts

@@ -18,6 +18,8 @@ export type {
 
 export { ORIGIN_APPLY_PATCHES, ORIGIN_LOCAL } from "./types.js";
 
+export { UnsupportedOpError } from "./engine/mutate.js";
+
 export { buildDocument, buildRoots, flatElements } from "./document.js";
 
 export { openComposition } from "./session.js";

packages/sdk/src/session.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Session-level behavior: history coalescing invariants and T3 override replay.
+ */
+
+import { describe, it, expect } from "vitest";
+import { openComposition } from "./session.js";
+
+const BASE_HTML = `
+<div data-hf-id="hf-stage" data-hf-root style="width: 1280px; height: 720px" data-duration="5">
+  <h1 data-hf-id="hf-title" data-start="0" data-end="3" style="color: #fff; font-size: 64px">Hello World</h1>
+  <p data-hf-id="hf-sub" style="opacity: 0.5">subtitle</p>
+  <img data-hf-id="hf-logo" src="/logo.png" alt="Logo" />
+</div>
+`.trim();
+
+// ─── History coalescing ───────────────────────────────────────────────────────
+
+describe("history coalescing", () => {
+  it("rapid edits to the SAME property coalesce into one undo entry", async () => {
+    const comp = await openComposition(BASE_HTML);
+    comp.setStyle("hf-title", { color: "#111" });
+    comp.setStyle("hf-title", { color: "#222" });
+    comp.setStyle("hf-title", { color: "#333" });
+
+    comp.undo();
+    const el = comp.getElement("hf-title");
+    expect(el?.inlineStyles["color"]).toBe("#fff"); // back to original in ONE step
+  });
+
+  it("rapid edits to DIFFERENT elements do NOT coalesce — undo reverts only the last edit", async () => {
+    const comp = await openComposition(BASE_HTML);
+    comp.setStyle("hf-title", { color: "#111" });
+    comp.setStyle("hf-sub", { opacity: "1" });
+
+    comp.undo();
+    expect(comp.getElement("hf-sub")?.inlineStyles["opacity"]).toBe("0.5"); // last edit reverted
+    expect(comp.getElement("hf-title")?.inlineStyles["color"]).toBe("#111"); // first edit intact
+
+    comp.undo();
+    expect(comp.getElement("hf-title")?.inlineStyles["color"]).toBe("#fff");
+  });
+
+  it("rapid edits to different properties of the same element do not coalesce", async () => {
+    const comp = await openComposition(BASE_HTML);
+    comp.setStyle("hf-title", { color: "#111" });
+    comp.setStyle("hf-title", { fontSize: "96px" });
+
+    comp.undo();
+    expect(comp.getElement("hf-title")?.inlineStyles["fontSize"]).toBe("64px");
+    expect(comp.getElement("hf-title")?.inlineStyles["color"]).toBe("#111");
+  });
+});
+
+// ─── T3 override replay ───────────────────────────────────────────────────────
+
+describe("override-set replay on open", () => {
+  it("applies style, text, and attribute overrides to the base document", async () => {
+    const comp = await openComposition(BASE_HTML, {
+      overrides: {
+        "hf-title.style.color": "#e63946",
+        "hf-title.text": "Edited headline",
+        "hf-logo.attr.src": "/new-logo.png",
+      },
+    });
+
+    const title = comp.getElement("hf-title");
+    expect(title?.inlineStyles["color"]).toBe("#e63946");
+    expect(title?.text).toBe("Edited headline");
+    expect(comp.getElement("hf-logo")?.attributes["src"]).toBe("/new-logo.png");
+
+    const html = comp.serialize();
+    expect(html).toContain("Edited headline");
+    expect(html).toContain("/new-logo.png");
+    expect(html).toContain("#e63946");
+  });
+
+  it("applies timing overrides (computed absolute end)", async () => {
+    const comp = await openComposition(BASE_HTML, {
+      overrides: { "hf-title.timing.end": 4.5 },
+    });
+    expect(comp.serialize()).toContain('data-end="4.5"');
+  });
+
+  it("removes elements marked with the null removal marker", async () => {
+    const comp = await openComposition(BASE_HTML, {
+      overrides: { "hf-sub": null },
+    });
+    expect(comp.getElement("hf-sub")).toBeNull();
+    expect(comp.serialize()).not.toContain("subtitle");
+  });
+
+  it("treats property-level null as restore-base (no-op on fresh base)", async () => {
+    const comp = await openComposition(BASE_HTML, {
+      overrides: { "hf-title.style.color": null },
+    });
+    expect(comp.getElement("hf-title")?.inlineStyles["color"]).toBe("#fff");
+  });
+
+  it("getOverrides returns the set the session was opened with", async () => {
+    const overrides = { "hf-title.style.color": "#e63946" };
+    const comp = await openComposition(BASE_HTML, { overrides });
+    expect(comp.getOverrides()).toEqual(overrides);
+  });
+});

packages/sdk/src/session.ts

@@ -29,7 +29,7 @@ import { parseMutable } from "./engine/model.js";
 import type { ParsedDocument } from "./engine/model.js";
 import { applyOp, validateOp } from "./engine/mutate.js";
 import { serializeDocument } from "./engine/serialize.js";
-import { applyPatchesToDocument } from "./engine/apply-patches.js";
+import { applyPatchesToDocument, applyOverrideSet } from "./engine/apply-patches.js";
 import { buildPatchEvent, pathToKey } from "./engine/patches.js";
 import { createHistory } from "./history.js";
 import type { HistoryModule } from "./history.js";
@@ -389,6 +389,11 @@ export async function openComposition(
   // Single parse: parseMutable stamps hf-ids + builds the live linkedom DOM;
   // the query API derives element snapshots from it lazily.
   const parsed = parseMutable(html);
+
+  // T3 embedded: replay the stored override-set onto the base in one pass,
+  // so the session exposes the user's exact edited state — not the template.
+  if (opts?.overrides) applyOverrideSet(parsed, opts.overrides);
+
   const session = new CompositionImpl(parsed, opts ?? {});
 
   const isEmbedded = opts?.overrides !== undefined;