@hyperframes/studio 0.7.55 → 0.7.57

package/src/player/lib/runtimeProtocol.ts

@@ -0,0 +1,65 @@
+import {
+  inspectRuntimeProtocol,
+  runtimeProtocolMetadata,
+  type RuntimeProtocolInspection,
+} from "@hyperframes/core/runtime/protocol";
+
+export type RuntimeControlMessage = {
+  source: "hf-parent";
+  type: "control";
+  action: string;
+} & ReturnType<typeof runtimeProtocolMetadata> &
+  Record<string, unknown>;
+
+export function createRuntimeControlMessage(
+  action: string,
+  payload: Record<string, unknown> = {},
+  fps = 30,
+): RuntimeControlMessage {
+  return {
+    ...payload,
+    source: "hf-parent",
+    type: "control",
+    action,
+    ...runtimeProtocolMetadata(fps),
+  };
+}
+
+export function postRuntimeControlMessage(
+  target: Pick<Window, "postMessage"> | null | undefined,
+  action: string,
+  payload: Record<string, unknown> = {},
+  fps = 30,
+): void {
+  target?.postMessage(createRuntimeControlMessage(action, payload, fps), "*");
+}
+
+export function inspectStudioRuntimeMessage(value: unknown): RuntimeProtocolInspection {
+  return inspectRuntimeProtocol(value, 30);
+}
+
+function dispatchRuntimeProtocolError(inspection: RuntimeProtocolInspection): void {
+  if (inspection.status !== "unsupported") return;
+  window.dispatchEvent(
+    new CustomEvent("runtimeprotocolerror", {
+      detail: {
+        code: inspection.code,
+        receivedVersion: inspection.receivedVersion,
+      },
+    }),
+  );
+}
+
+export function acceptStudioRuntimeMessage(
+  value: unknown,
+): Exclude<RuntimeProtocolInspection, { status: "unsupported" }> | null {
+  const inspection = inspectStudioRuntimeMessage(value);
+  if (inspection.status !== "unsupported") return inspection;
+  dispatchRuntimeProtocolError(inspection);
+  return null;
+}
+
+export function acceptedRuntimeMessageFps(value: unknown): number {
+  const inspection = inspectStudioRuntimeMessage(value);
+  return inspection.status === "supported" ? inspection.fps : 30;
+}

package/src/player/lib/time.test.ts

@@ -3,26 +3,26 @@ import { formatFrameTime, frameToSeconds, secondsToFrame, stepFrameTime, formatT
 
 describe("formatTime", () => {
   it("formats zero seconds", () => {
-    expect(formatTime(0)).toBe("0:00");
+    expect(formatTime(0)).toBe("00:00");
   });
 
   // fallow-ignore-next-line code-duplication
   it("formats seconds less than a minute", () => {
-    expect(formatTime(5)).toBe("0:05");
-    expect(formatTime(30)).toBe("0:30");
-    expect(formatTime(59)).toBe("0:59");
+    expect(formatTime(5)).toBe("00:05");
+    expect(formatTime(30)).toBe("00:30");
+    expect(formatTime(59)).toBe("00:59");
   });
 
   it("formats exact minutes", () => {
-    expect(formatTime(60)).toBe("1:00");
-    expect(formatTime(120)).toBe("2:00");
+    expect(formatTime(60)).toBe("01:00");
+    expect(formatTime(120)).toBe("02:00");
     expect(formatTime(600)).toBe("10:00");
   });
 
   it("formats minutes and seconds", () => {
-    expect(formatTime(65)).toBe("1:05");
-    expect(formatTime(90)).toBe("1:30");
-    expect(formatTime(125)).toBe("2:05");
+    expect(formatTime(65)).toBe("01:05");
+    expect(formatTime(90)).toBe("01:30");
+    expect(formatTime(125)).toBe("02:05");
   });
 
   it("formats large values (over an hour)", () => {
@@ -32,28 +32,28 @@ describe("formatTime", () => {
   });
 
   it("floors fractional seconds", () => {
-    expect(formatTime(0.9)).toBe("0:00");
-    expect(formatTime(1.5)).toBe("0:01");
-    expect(formatTime(59.99)).toBe("0:59");
-    expect(formatTime(60.5)).toBe("1:00");
+    expect(formatTime(0.9)).toBe("00:00");
+    expect(formatTime(1.5)).toBe("00:01");
+    expect(formatTime(59.99)).toBe("00:59");
+    expect(formatTime(60.5)).toBe("01:00");
   });
 
-  it("pads single-digit seconds with leading zero", () => {
-    expect(formatTime(1)).toBe("0:01");
-    expect(formatTime(61)).toBe("1:01");
+  it("pads single-digit minutes and seconds with leading zeros", () => {
+    expect(formatTime(1)).toBe("00:01");
+    expect(formatTime(61)).toBe("01:01");
     expect(formatTime(609)).toBe("10:09");
   });
 
   it("guards against negative values", () => {
-    expect(formatTime(-1)).toBe("0:00");
+    expect(formatTime(-1)).toBe("00:00");
   });
 
   it("guards against NaN", () => {
-    expect(formatTime(NaN)).toBe("0:00");
+    expect(formatTime(NaN)).toBe("00:00");
   });
 
   it("guards against Infinity", () => {
-    expect(formatTime(Infinity)).toBe("0:00");
+    expect(formatTime(Infinity)).toBe("00:00");
   });
 });
 

package/src/player/lib/time.ts

@@ -1,10 +1,14 @@
 export const STUDIO_PREVIEW_FPS = 30;
 
 export function formatTime(time: number): string {
-  if (!Number.isFinite(time) || time < 0) return "0:00";
+  if (!Number.isFinite(time) || time < 0) return "00:00";
   const mins = Math.floor(time / 60);
   const secs = Math.floor(time % 60);
-  return `${mins}:${secs.toString().padStart(2, "0")}`;
+  // Zero-pad minutes as well as seconds so every readout is a stable-width
+  // MM:SS (e.g. "00:44", not "0:44"). Minutes past 99 keep their extra digits
+  // ("120:00"); an hours-style H:MM:SS grouping is applied by callers that need
+  // it (see formatTimelineTickLabel), never here.
+  return `${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
 }
 
 export function secondsToFrame(time: number, fps = STUDIO_PREVIEW_FPS): number {

package/src/player/lib/timelineDOM.test.ts

@@ -4,8 +4,13 @@ import {
   createTimelineElementFromManifestClip,
   parseTimelineFromDOM,
   createImplicitTimelineLayersFromDOM,
-  buildStandaloneRootTimelineElement,
+  mergeTimelineElementsPreservingDowngrades,
 } from "./timelineDOM";
+import type { TimelineElement } from "../store/playerStore";
+
+function el(id: string, extra: Partial<TimelineElement> = {}): TimelineElement {
+  return { id, tag: "img", start: 0, duration: 5, track: 0, ...extra };
+}
 
 function makeDoc(html: string): Document {
   const d = document.implementation.createHTMLDocument();
@@ -13,29 +18,6 @@ function makeDoc(html: string): Document {
   return d;
 }
 
-function makeLiveDoc(html: string): Document {
-  document.head.innerHTML = "";
-  document.body.innerHTML = html;
-  return document;
-}
-
-function mockComputedZIndex(doc: Document, zIndexById: ReadonlyMap<string, string>): void {
-  const win = doc.defaultView;
-  if (!win) throw new Error("Expected document window");
-  const original = win.getComputedStyle.bind(win);
-  Object.defineProperty(win, "getComputedStyle", {
-    configurable: true,
-    value: (element: Element, pseudoElt?: string | null) => {
-      const style = original(element, pseudoElt);
-      const zIndex = zIndexById.get(element.id);
-      if (zIndex != null) {
-        Object.defineProperty(style, "zIndex", { configurable: true, value: zIndex });
-      }
-      return style;
-    },
-  });
-}
-
 describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
   it("harvests hfId from a data-start element that has data-hf-id", () => {
     const doc = makeDoc(`
@@ -126,58 +108,6 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
 
     expect(element.hidden).toBe(true);
   });
-
-  it("captures the effective z-index from the live element, not the runtime inline-only value", () => {
-    // The runtime reports inline-only z-index (0 for CSS-rule authored z-index),
-    // which must NOT override the live element's effective z-index — otherwise
-    // the timeline collapses every CSS-styled clip to a z=0 tie and mis-orders.
-    const doc = makeDoc(`
-      <div data-composition-id="root">
-        <div id="hero" class="clip" data-start="0" data-duration="5" style="z-index: 30"></div>
-      </div>
-    `);
-    const hostEl = doc.getElementById("hero");
-
-    const element = createTimelineElementFromManifestClip({
-      clip: {
-        id: "hero",
-        label: "Hero",
-        kind: "element",
-        tagName: "div",
-        start: 0,
-        duration: 5,
-        track: 0,
-        zIndex: 0,
-        compositionId: null,
-        parentCompositionId: null,
-        compositionSrc: null,
-        assetUrl: null,
-      },
-      fallbackIndex: 0,
-      doc,
-      hostEl,
-    });
-
-    expect(element.zIndex).toBe(30);
-    expect(element.hasExplicitZIndex).toBe(true);
-  });
-
-  it("marks parsed inline, CSS-rule, and auto z-index authorship accurately", () => {
-    const doc = makeLiveDoc(`
-      <div data-composition-id="root">
-        <div id="inline" class="clip" data-start="0" data-duration="2" style="z-index: 3"></div>
-        <div id="rule" class="clip" data-start="0" data-duration="2"></div>
-        <div id="auto" class="clip" data-start="0" data-duration="2"></div>
-      </div>
-    `);
-    mockComputedZIndex(doc, new Map([["rule", "12"]]));
-
-    const elements = parseTimelineFromDOM(doc, 10);
-
-    expect(elements.find((el) => el.id === "inline")?.hasExplicitZIndex).toBe(true);
-    expect(elements.find((el) => el.id === "rule")?.hasExplicitZIndex).toBe(true);
-    expect(elements.find((el) => el.id === "auto")?.hasExplicitZIndex).toBe(false);
-  });
 });
 
 describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
@@ -211,31 +141,28 @@ describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
 
     expect(layers).toEqual([]);
   });
+});
 
-  it("marks implicit layer CSS z-index authorship from computed style", () => {
-    const doc = makeLiveDoc(`
-      <div data-composition-id="root">
-        <div id="layer" class="clip"></div>
-      </div>
-    `);
-    mockComputedZIndex(doc, new Map([["layer", "8"]]));
-
-    const layers = createImplicitTimelineLayersFromDOM(doc, 10);
-
-    expect(layers[0]?.zIndex).toBe(8);
-    expect(layers[0]?.hasExplicitZIndex).toBe(true);
+describe("mergeTimelineElementsPreservingDowngrades — genuine removal vs transient downgrade", () => {
+  it("drops a removed TOP-LEVEL element (undo of a split) instead of ghosting it", () => {
+    const current = [el("a"), el("a-split")]; // post-split store: original + clone
+    const next = [el("a")]; // fresh scan of the reverted file: clone gone
+    const merged = mergeTimelineElementsPreservingDowngrades(current, next, 30, 30);
+    expect(merged.map((e) => e.id)).toEqual(["a"]);
   });
-});
 
-describe("buildStandaloneRootTimelineElement", () => {
-  it("marks the standalone root as auto z-index", () => {
-    const root = buildStandaloneRootTimelineElement({
-      compositionId: "root",
-      tagName: "div",
-      rootDuration: 10,
-      iframeSrc: "/preview/comp/index.html",
-    });
+  it("still preserves an enriched sub-composition child a bare re-scan drops", () => {
+    const current = [el("a"), el("sub-child", { compositionSrc: "sub.html" })];
+    const next = [el("a")]; // bare DOM scan misses the enriched sub-comp child
+    const merged = mergeTimelineElementsPreservingDowngrades(current, next, 30, 30);
+    expect(merged.map((e) => e.id).sort()).toEqual(["a", "sub-child"]);
+  });
 
-    expect(root?.hasExplicitZIndex).toBe(false);
+  it("trusts the fresh scan fully when it is not shorter", () => {
+    const current = [el("a"), el("b", { compositionSrc: "sub.html" })];
+    const next = [el("a"), el("c")];
+    expect(
+      mergeTimelineElementsPreservingDowngrades(current, next, 30, 30).map((e) => e.id),
+    ).toEqual(["a", "c"]);
   });
 });

package/src/player/lib/timelineDOM.ts

@@ -10,7 +10,6 @@
 
 import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "./playbackTypes";
-import { getElementZIndex, hasExplicitZIndex } from "./layerOrdering";
 import {
   resolveMediaElement,
   applyMediaMetadataFromElement,
@@ -24,6 +23,7 @@ import {
   buildTimelineElementIdentity,
   getTimelineElementIdentity,
   isTimelineIgnoredElement,
+  readTimelineElementZIndex,
 } from "./timelineElementHelpers";
 
 // Re-export helpers that were previously public from this module so that
@@ -66,49 +66,6 @@ function resolveClipTag(clip: ClipManifestClip): string {
   return clip.tagName || clip.kind || "div";
 }
 
-function resolveDomCompositionContext(
-  element: Element,
-  root: Element | null,
-): {
-  parentCompositionId: string | null;
-  compositionAncestors: string[];
-  stackingContextId: string | null;
-} {
-  const ancestors: string[] = [];
-  let parentCompositionId: string | null = null;
-  let cursor = element.parentElement;
-  while (cursor) {
-    const compositionId = cursor.getAttribute("data-composition-id");
-    if (compositionId) {
-      ancestors.push(compositionId);
-      if (!parentCompositionId && cursor !== root) {
-        parentCompositionId = compositionId;
-      }
-    }
-    cursor = cursor.parentElement;
-  }
-  const compositionAncestors = ancestors.reverse();
-  return {
-    parentCompositionId,
-    compositionAncestors,
-    stackingContextId: parentCompositionId ?? compositionAncestors[0] ?? null,
-  };
-}
-
-function isHTMLElement(element: Element | null): element is HTMLElement {
-  if (!element) return false;
-  const HtmlElementCtor = element.ownerDocument.defaultView?.HTMLElement ?? globalThis.HTMLElement;
-  return typeof HtmlElementCtor !== "undefined" && element instanceof HtmlElementCtor;
-}
-
-function getTimelineElementZIndex(element: Element | null): number | undefined {
-  return isHTMLElement(element) ? getElementZIndex(element) : undefined;
-}
-
-function getTimelineElementHasExplicitZIndex(element: Element | null): boolean {
-  return isHTMLElement(element) ? hasExplicitZIndex(element) : false;
-}
-
 // fallow-ignore-next-line complexity
 export function createTimelineElementFromManifestClip(params: {
   clip: ClipManifestClip;
@@ -130,14 +87,6 @@ export function createTimelineElementFromManifestClip(params: {
   let sourceFile: string | undefined;
 
   let hfId: string | undefined;
-  const domContext = hostEl
-    ? resolveDomCompositionContext(hostEl, doc?.querySelector("[data-composition-id]") ?? null)
-    : null;
-  const compositionAncestors = clip.compositionAncestors ?? domContext?.compositionAncestors;
-  const parentCompositionId = clip.parentCompositionId ?? domContext?.parentCompositionId;
-  const stackingContextId =
-    clip.stackingContextId ?? parentCompositionId ?? compositionAncestors?.[0] ?? null;
-
   if (hostEl) {
     domId = hostEl.id || undefined;
     hfId = hostEl.getAttribute("data-hf-id") || undefined;
@@ -164,15 +113,15 @@ export function createTimelineElementFromManifestClip(params: {
     start: clip.start,
     duration: clip.duration,
     track: clip.track,
-    // Prefer the effective (computed) z-index read from the live element — the
-    // same read the reorder commit uses — so CSS-rule z-index (not just inline)
-    // is captured. clip.zIndex from the runtime is inline-only (0 for CSS rules),
-    // so it can only serve as a fallback when the element isn't live.
-    zIndex: getTimelineElementZIndex(hostEl) ?? clip.zIndex ?? 0,
-    hasExplicitZIndex: getTimelineElementHasExplicitZIndex(hostEl),
-    stackingContextId,
-    parentCompositionId,
-    compositionAncestors,
+    // clip.track IS the authored data-track-index verbatim (the runtime honors
+    // it; see parseAuthoredTrack in core/runtime/timeline.ts). Record it at this
+    // translation boundary so later display-lane remaps (normalizeToZones,
+    // expanded-child rows) can persist in AUTHORED space instead of
+    // reconstructing it from lane occupants.
+    authoredTrack: clip.track,
+    // Runtime-computed stacking context — authoritative; helpers read it, never
+    // re-derive it.
+    stackingContextId: clip.stackingContextId ?? null,
     domId,
     hfId,
     selector,
@@ -185,6 +134,7 @@ export function createTimelineElementFromManifestClip(params: {
     if (hostEl.hasAttribute("data-hidden")) entry.hidden = true;
     const timelineRole = hostEl.getAttribute("data-timeline-role");
     if (timelineRole) entry.timelineRole = timelineRole;
+    entry.zIndex = readTimelineElementZIndex(hostEl);
   }
   if (clip.assetUrl) entry.src = clip.assetUrl;
   if (clip.kind === "composition" && clip.compositionId) {
@@ -207,8 +157,6 @@ export function createTimelineElementFromManifestClip(params: {
       }
     }
     if (hostEl) {
-      entry.zIndex = getTimelineElementZIndex(hostEl) ?? entry.zIndex;
-      entry.hasExplicitZIndex = getTimelineElementHasExplicitZIndex(hostEl);
       entry.domId = hostEl.id || undefined;
       entry.hfId = hostEl.getAttribute("data-hf-id") || undefined;
       entry.selector = getTimelineElementSelector(hostEl);
@@ -269,10 +217,10 @@ export function createImplicitTimelineLayersFromDOM(
     });
     if (existingKeys.has(identity.key) || existingKeys.has(identity.id)) continue;
 
-    const compositionContext = resolveDomCompositionContext(child, rootComp);
     layers.push({
       domId: child.id || undefined,
       hfId: child.getAttribute("data-hf-id") || undefined,
+      zIndex: readTimelineElementZIndex(child),
       duration: rootDuration,
       id: identity.id,
       key: identity.key,
@@ -281,11 +229,6 @@ export function createImplicitTimelineLayersFromDOM(
       selectorIndex,
       sourceFile,
       start: 0,
-      zIndex: getTimelineElementZIndex(child),
-      hasExplicitZIndex: getTimelineElementHasExplicitZIndex(child),
-      stackingContextId: compositionContext.stackingContextId,
-      parentCompositionId: compositionContext.parentCompositionId,
-      compositionAncestors: compositionContext.compositionAncestors,
       tag: child.tagName.toLowerCase(),
       timingSource: "implicit",
       track: maxTrack + 1 + layers.length,
@@ -347,7 +290,6 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       selectorIndex,
       sourceFile,
     });
-    const compositionContext = resolveDomCompositionContext(el, rootComp);
     const entry: TimelineElement = {
       id: identity.id,
       label,
@@ -356,17 +298,13 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       start,
       duration: dur,
       track: isNaN(track) ? 0 : track,
-      zIndex: getTimelineElementZIndex(el),
-      hasExplicitZIndex: getTimelineElementHasExplicitZIndex(el),
-      stackingContextId: compositionContext.stackingContextId,
-      parentCompositionId: compositionContext.parentCompositionId,
-      compositionAncestors: compositionContext.compositionAncestors,
       domId: el.id || undefined,
       hfId: el.getAttribute("data-hf-id") || undefined,
       selector,
       selectorIndex,
       sourceFile,
       timingSource: "authored",
+      zIndex: readTimelineElementZIndex(el),
     };
 
     const mediaEl = resolveMediaElement(el);
@@ -437,7 +375,14 @@ export function mergeTimelineElementsPreservingDowngrades(
 
   const nextIdentities = new Set(nextElements.map(getTimelineElementIdentity));
   const preserved = currentElements.filter(
-    (element) => !nextIdentities.has(getTimelineElementIdentity(element)),
+    (element) =>
+      !nextIdentities.has(getTimelineElementIdentity(element)) &&
+      // Only preserve enriched sub-composition children (compositionSrc set),
+      // which a bare DOM re-scan legitimately drops and enrichMissingCompositions
+      // re-adds. A TOP-LEVEL element missing from the fresh scan was genuinely
+      // removed (undo of a split, a delete), so let it go — otherwise undoing a
+      // split leaves a ghost clip in the timeline even though the file is reverted.
+      element.compositionSrc != null,
   );
   if (preserved.length === 0) return nextElements;
   return [...nextElements, ...preserved];
@@ -481,11 +426,6 @@ export function buildStandaloneRootTimelineElement(params: {
     start: 0,
     duration: params.rootDuration,
     track: 0,
-    zIndex: 0,
-    hasExplicitZIndex: false,
-    stackingContextId: params.compositionId,
-    parentCompositionId: null,
-    compositionAncestors: [params.compositionId],
     compositionSrc,
     selector: params.selector,
     selectorIndex: params.selectorIndex,

package/src/player/lib/timelineElementHelpers.ts

@@ -15,6 +15,31 @@ import { isFinitePositive } from "./playbackAdapter";
 // Duration attribute helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Read a host element's effective CSS stacking order for the timeline's reverse
+ * z→lane mapping. Prefers the inline `style.zIndex` (what the canvas context
+ * menu and LayersPanel z-edits write via handleDomZIndexReorderCommit), falls
+ * back to computed style; "auto" / empty / unparseable ⇒ 0. Works with a
+ * detached parse Document (no defaultView) as well as a live iframe. Mirrors
+ * canvasContextMenuZOrder.parseZIndex semantics so the two directions agree.
+ */
+export function readTimelineElementZIndex(el: Element): number {
+  const html = el as HTMLElement;
+  const parseZ = (value: string | null | undefined): number | null => {
+    if (value == null || value === "" || value === "auto") return null;
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) ? n : null;
+  };
+  const fromInline = parseZ(html.style?.zIndex);
+  if (fromInline != null) return fromInline;
+  const view = el.ownerDocument?.defaultView;
+  if (view?.getComputedStyle) {
+    const fromComputed = parseZ(view.getComputedStyle(html).zIndex);
+    if (fromComputed != null) return fromComputed;
+  }
+  return 0;
+}
+
 function readDurationAttribute(el: Element | null | undefined): number {
   if (!el) return 0;
   const duration =
@@ -36,14 +61,20 @@ export function isTimelineIgnoredElement(el: Element): boolean {
   );
 }
 
-export function readTimelineDurationFromDocument(doc: Document | null | undefined): number {
+/**
+ * Furthest clip end (start + RAW `data-duration`) over every non-root clip in the
+ * document. Reads the authored attribute, NOT any runtime-computed value — so it
+ * is immune to the runtime's clamp that truncates a clip's live duration to the
+ * composition length. This is the source of truth for content-driven duration:
+ * computing it from the store instead would feed the truncated value back in and
+ * make the composition length ratchet down (research HANDOFF-3 §6.1 feedback loop).
+ */
+export function furthestClipEndFromDocument(doc: Document | null | undefined): number {
   if (!doc) return 0;
-  const rootDuration = readDurationAttribute(doc.querySelector("[data-composition-id]"));
-  if (rootDuration > 0) return rootDuration;
-
+  const root = doc.querySelector("[data-composition-id]");
   let maxEnd = 0;
   for (const node of Array.from(doc.querySelectorAll("[data-start]"))) {
-    if (isTimelineIgnoredElement(node)) continue;
+    if (node === root || isTimelineIgnoredElement(node)) continue;
     const start = Number.parseFloat(node.getAttribute("data-start") ?? "");
     const duration = readDurationAttribute(node);
     if (!Number.isFinite(start) || start < 0 || duration <= 0) continue;
@@ -52,6 +83,24 @@ export function readTimelineDurationFromDocument(doc: Document | null | undefine
   return maxEnd;
 }
 
+export function readTimelineDurationFromDocument(doc: Document | null | undefined): number {
+  if (!doc) return 0;
+  const rootDuration = readDurationAttribute(doc.querySelector("[data-composition-id]"));
+  if (rootDuration > 0) return rootDuration;
+  return furthestClipEndFromDocument(doc);
+}
+
+/**
+ * Furthest clip end parsed straight from a composition SOURCE STRING (the HTML
+ * being saved). Uses raw `data-duration`, so it is the correct input for syncing
+ * the root duration after an edit — reading the store instead would use the
+ * runtime-truncated durations and shrink the composition (the feedback loop).
+ */
+export function furthestClipEndFromSource(source: string): number {
+  if (!source) return 0;
+  return furthestClipEndFromDocument(new DOMParser().parseFromString(source, "text/html"));
+}
+
 // ---------------------------------------------------------------------------
 // DOM element type guards
 // ---------------------------------------------------------------------------
@@ -249,6 +298,25 @@ export function getTimelineElementIdentity(element: { key?: string | null; id: s
   return element.key ?? element.id;
 }
 
+/**
+ * Timeline store key for a z-reorder entry built OUTSIDE the timeline
+ * expansion (canvas context menu / LayersPanel), so the reorder commit can
+ * update the store's zIndex synchronously. Matches buildTimelineElementKey's
+ * stable branches (`sourceFile#domId`, else the selector-based key). Undefined
+ * when the element has neither a DOM id nor a selector — the timeline's
+ * fallback branch needs its own fallbackIndex, which these callers don't have,
+ * so such an entry simply skips the synchronous store update.
+ */
+export function deriveTimelineStoreKey(params: {
+  domId?: string;
+  selector?: string;
+  selectorIndex?: number;
+  sourceFile?: string;
+}): string | undefined {
+  if (!params.domId && !params.selector) return undefined;
+  return buildTimelineElementKey({ id: "", fallbackIndex: 0, ...params });
+}
+
 // ---------------------------------------------------------------------------
 // DOM node querying
 // ---------------------------------------------------------------------------

package/src/player/lib/timelineIframeHelpers.ts

@@ -18,7 +18,9 @@ import {
   getTimelineElementSelectorIndex,
   getTimelineElementDisplayLabel,
   buildTimelineElementIdentity,
+  readTimelineElementZIndex,
 } from "./timelineElementHelpers";
+import { postRuntimeControlMessage } from "./runtimeProtocol";
 
 // ---------------------------------------------------------------------------
 // Viewport / DOM normalisation
@@ -102,10 +104,7 @@ function postPreviewControl(
   action: string,
   payload: Record<string, unknown>,
 ): void {
-  iframe.contentWindow?.postMessage(
-    { source: "hf-parent", type: "control", action, ...payload },
-    "*",
-  );
+  postRuntimeControlMessage(iframe.contentWindow, action, payload);
 }
 
 export function shouldMutePreviewAudio(audioMuted: boolean, playbackRate: number): boolean {
@@ -377,6 +376,7 @@ export function buildMissingCompositionElements(
       selector,
       selectorIndex,
       sourceFile,
+      zIndex: readTimelineElementZIndex(el),
     };
     if (compSrc) {
       entry.compositionSrc = compSrc;