@hyperframes/sdk 0.8.193 → 0.8.194

package/dist/engine/apply-patches.d.ts

@@ -16,6 +16,9 @@ import type { ParsedDocument } from "./model.js";
  * property is a no-op in applyOne, so this is safe against fresh-base misses.)
  */
 export declare function applyOverrideSet(parsed: ParsedDocument, overrides: OverrideSet): void;
+export declare function isElementSnapshotOverride(key: string, value: OverrideSet[string]): value is Record<string, unknown> & {
+    siblingIndex: number;
+};
 interface ApplyOptions {
     /** Keep a copy of each removed element an inline script looks up (stored deletes replayed onto a base). */
     keepScriptTargets?: boolean;

package/dist/engine/apply-patches.js

@@ -122,6 +122,29 @@ export function applyOverrideSet(parsed, overrides) {
         }
     }
     applyPatchesToDocument(parsed, patches, { keepScriptTargets: true });
+    restoreOverridePositions(parsed, overrides);
+}
+export function isElementSnapshotOverride(key, value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    return /^\/elements\/[^/]+$/.test(keyToPath(key) ?? "") && typeof value.siblingIndex === "number";
+}
+function restoreOverridePositions(parsed, overrides) {
+    const positions = [];
+    for (const [key, value] of Object.entries(overrides)) {
+        if (!isElementSnapshotOverride(key, value) || typeof value.childNodeIndex !== "number")
+            continue;
+        const el = findById(parsed.document, key);
+        if (!el?.parentElement)
+            continue;
+        positions.push({ el, parent: el.parentElement, childNodeIndex: value.childNodeIndex });
+    }
+    // Detach every restored sibling so inserting one cannot shift another's saved position.
+    for (const { el } of positions)
+        el.remove();
+    for (const { el, parent, childNodeIndex } of positions.sort((a, b) => a.childNodeIndex - b.childNodeIndex)) {
+        parent.insertBefore(el, parent.childNodes[childNodeIndex] ?? null);
+    }
 }
 /** Keep a deleted node a script looks up: serialize writes it back hidden, so the script finds it. */
 function keepDelete(parsed, el) {
@@ -235,7 +258,7 @@ function applyOne(parsed, patch, p, options) {
                     keepDelete(parsed, el);
                 el?.remove();
             }
-            else if (patch.op === "add" && patch.value) {
+            else if ((patch.op === "add" || patch.op === "replace") && patch.value) {
                 const v = patch.value;
                 const parent = v.parentId
                     ? findById(parsed.document, v.parentId)
@@ -248,6 +271,8 @@ function applyOne(parsed, patch, p, options) {
                 const node = tmp.firstElementChild;
                 if (!node)
                     return;
+                if (patch.op === "replace")
+                    findById(parsed.document, p.id)?.remove();
                 const children = Array.from(parent.children);
                 const ref = children[v.siblingIndex] ?? null;
                 parent.insertBefore(node, ref);

package/dist/session.js

@@ -12,14 +12,14 @@ import { buildRoots, flatElements, parsedAnimationIds } from "./document.js";
 import { syncFixFor, syncOffsetOf } from "./engine/syncTiming.js";
 import { parseMutable } from "./engine/model.js";
 import { applyOp, validateOp } from "./engine/mutate.js";
-import { getGsapScripts, resolveScoped, declarationCarriers } from "./engine/model.js";
+import { getGsapScripts, resolveScoped, declarationCarriers, getSiblingIndex, } from "./engine/model.js";
 import { extractGsapLabels } from "@hyperframes/core/gsap-parser-acorn";
 import { stripEmbeddedRuntimeScripts } from "@hyperframes/core/compiler/html-document";
 import { readClipTiming } from "@hyperframes/core/composition-contract";
 import { readDeclaredDefaults, validateVariables, scanVariableUsage, } from "@hyperframes/core/variables";
 import { readVariableDeclarations } from "./engine/variableModel.js";
 import { serializeDocument } from "./engine/serialize.js";
-import { applyPatchesToDocument, applyOverrideSet } from "./engine/apply-patches.js";
+import { applyPatchesToDocument, applyOverrideSet, isElementSnapshotOverride, } from "./engine/apply-patches.js";
 import { buildPatchEvent, pathToKey } from "./engine/patches.js";
 import { createHistory } from "./history.js";
 import { createPersistQueue } from "./persist-queue.js";
@@ -276,9 +276,9 @@ class CompositionImpl {
             allLabels = scripts.flatMap((script) => extractGsapLabels(script));
             this._gsapLabelCache = scripts.length ? { scripts: [...scripts], labels: allLabels } : null;
         }
-        // refId remains a bare global id, matching runtime resolution. The shared
-        // contract owns parsing, canonical duration preference, clamping, and
-        // legacy data-end compatibility; this adapter only supplies document lookup.
+        // refId resolves as a bare hf-id (top level first), unlike the runtime's
+        // composition-scoped `id` lookup. The shared contract owns parsing, canonical
+        // duration preference, clamping, and legacy data-end; this adapter only supplies lookup.
         const timingCache = new Map();
         const visiting = new Set();
         const resolveTiming = (el) => {
@@ -488,6 +488,7 @@ class CompositionImpl {
         for (const p of forward) {
             const key = pathToKey(p.path);
             if (key !== null) {
+                delete this.overrides[key];
                 this.overrides[key] =
                     p.op === "remove"
                         ? null
@@ -649,7 +650,20 @@ class CompositionImpl {
     }
     // ── T3 embedded-mode extras ──────────────────────────────────────────────────
     getOverrides() {
-        return { ...this.overrides };
+        const overrides = { ...this.overrides };
+        for (const [key, value] of Object.entries(overrides)) {
+            if (!isElementSnapshotOverride(key, value))
+                continue;
+            const el = resolveScoped(this.parsed.document, key);
+            if (el?.parentElement) {
+                overrides[key] = {
+                    ...value,
+                    siblingIndex: getSiblingIndex(el),
+                    childNodeIndex: Array.from(el.parentElement.childNodes).indexOf(el),
+                };
+            }
+        }
+        return overrides;
     }
     // fallow-ignore-next-line complexity
     applyPatches(patches, opts) {
@@ -665,6 +679,7 @@ class CompositionImpl {
         for (const p of patches) {
             const key = pathToKey(p.path);
             if (key !== null) {
+                delete this.overrides[key];
                 this.overrides[key] =
                     p.op === "remove"
                         ? null
@@ -716,8 +731,6 @@ export async function openComposition(html, opts) {
     // the authored base values are readable. getVariableValue({ base: true })
     // serves them for the rest of the session (undo-to-base restores).
     const baseVariableDefaults = declaredDefaults(parsed);
-    // 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 ?? {}, baseVariableDefaults);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/sdk",
-  "version": "0.8.193",
+  "version": "0.8.194",
   "description": "Headless, framework-neutral HyperFrames composition editing engine",
   "repository": {
     "type": "git",
@@ -44,8 +44,8 @@
   },
   "dependencies": {
     "linkedom": "^0.18.12",
-    "@hyperframes/parsers": "0.8.193",
-    "@hyperframes/core": "0.8.193"
+    "@hyperframes/core": "0.8.194",
+    "@hyperframes/parsers": "0.8.194"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",