@hyperframes/studio 0.8.47 → 0.8.49

package/src/utils/sdkCutover.ts

@@ -7,8 +7,8 @@ import { patchOpsToSdkEditOps } from "./sdkOpMapping";
 import { recordResolverParity, recordAnimationResolverParity } from "./sdkResolverShadow";
 import {
   isResolverDisagreement,
+  sdkCutoverIneligibleReason,
   shouldDeclineTextCutoverForTarget,
-  shouldUseSdkCutover,
 } from "./sdkCutoverEligibility";
 import {
   asCutoverError,
@@ -81,11 +81,14 @@ export async function sdkCutoverPersist(
   deps: CutoverDeps,
   options?: CutoverOptions,
 ): Promise<CutoverResult> {
-  if (!shouldUseSdkCutover(sdkFamilyEnabled("dom"), !!sdkSession, selection.hfId, ops))
-    return declinedCutover("ineligible_operation", "dom");
+  // Name WHICH eligibility check failed: on v0.8.47 this one string covered 26 of
+  // 30 dom declines. The two below aren't properties of the batch, so they differ.
+  if (!sdkFamilyEnabled("dom")) return declinedCutover("feature_disabled", "dom");
   if (!sdkSession) return declinedCutover("session_unavailable", "dom");
   const hfId = selection.hfId;
-  if (!hfId) return declinedCutover("target_unaddressable", "dom");
+  const ineligible = sdkCutoverIneligibleReason(hfId, ops);
+  // `!hfId` is already a reason; testing it again narrows the type for the rest.
+  if (ineligible || !hfId) return declinedCutover(ineligible ?? "target_unaddressable", "dom");
   const target = sdkSession.getElement(hfId);
   if (!target)
     return declinedCutover("target_not_found", "dom", isResolverDisagreement(sdkSession, hfId));

package/src/utils/sdkCutoverEligibility.test.ts

@@ -1,6 +1,27 @@
 import { describe, expect, it } from "vitest";
 import type { PatchOperation } from "./sourcePatcher";
-import { shouldUseSdkCutover } from "./sdkCutoverEligibility";
+import { shouldUseSdkCutover, sdkCutoverIneligibleReason } from "./sdkCutoverEligibility";
+
+const styleOp = (property: string, value: string): PatchOperation => ({
+  type: "inline-style",
+  property,
+  value,
+});
+const textOp = (value: string): PatchOperation => ({
+  type: "text-content",
+  property: "text",
+  value,
+});
+const attrOp = (property: string, value: string): PatchOperation => ({
+  type: "attribute",
+  property,
+  value,
+});
+const htmlAttrOp = (property: string, value: string): PatchOperation => ({
+  type: "html-attribute",
+  property,
+  value,
+});
 
 const childStyleOp: PatchOperation = {
   type: "inline-style",
@@ -15,3 +36,77 @@ describe("shouldUseSdkCutover child-scoped operations", () => {
     expect(shouldUseSdkCutover(true, true, "hf-parent", [childStyleOp])).toBe(false);
   });
 });
+
+describe("sdkCutoverIneligibleReason", () => {
+  // `ineligible_operation` was one string covering four distinct causes, which
+  // made the post-flip decline telemetry unactionable: 26 of 30 declines on
+  // v0.8.47 landed there, with no way to separate a structural edit the SDK has
+  // no vocabulary for (expected, permanent) from a reserved-attribute or
+  // unsafe-attribute decline (narrower, and possibly fixable).
+  it("names an op type the SDK cannot express", () => {
+    expect(
+      sdkCutoverIneligibleReason("hf-abc", [
+        { type: "split", property: "x", value: "1" } as unknown as PatchOperation,
+      ]),
+    ).toBe("unsupported_op_type");
+  });
+
+  it("names a child-scoped op", () => {
+    expect(sdkCutoverIneligibleReason("hf-parent", [childStyleOp])).toBe("child_scoped_op");
+  });
+
+  it("names a reserved attribute", () => {
+    expect(sdkCutoverIneligibleReason("hf-abc", [attrOp("end", "2")])).toBe("reserved_attribute");
+    expect(sdkCutoverIneligibleReason("hf-abc", [htmlAttrOp("DATA-START", "1")])).toBe(
+      "reserved_attribute",
+    );
+  });
+
+  it("names an unsafe html attribute", () => {
+    expect(sdkCutoverIneligibleReason("hf-abc", [htmlAttrOp("onclick", "alert(1)")])).toBe(
+      "unsafe_html_attribute",
+    );
+    expect(sdkCutoverIneligibleReason("hf-abc", [htmlAttrOp("href", "javascript:alert(1)")])).toBe(
+      "unsafe_html_attribute",
+    );
+  });
+
+  it("names an empty batch and an unaddressable target", () => {
+    expect(sdkCutoverIneligibleReason("hf-abc", [])).toBe("no_ops");
+    expect(sdkCutoverIneligibleReason(null, [styleOp("color", "red")])).toBe(
+      "target_unaddressable",
+    );
+  });
+
+  it("returns null when the batch is eligible", () => {
+    expect(sdkCutoverIneligibleReason("hf-abc", [styleOp("color", "red")])).toBeNull();
+    expect(
+      sdkCutoverIneligibleReason("hf-abc", [
+        styleOp("color", "red"),
+        textOp("hello"),
+        attrOp("x", "1"),
+        htmlAttrOp("class", "foo"),
+      ]),
+    ).toBeNull();
+  });
+
+  // The reason function must not drift from the predicate it explains: a batch
+  // the gate accepts must have no reason, and one it declines must have one.
+  it("agrees with shouldUseSdkCutover on every case", () => {
+    const cases: PatchOperation[][] = [
+      [styleOp("color", "red")],
+      [textOp("hello")],
+      [attrOp("x", "1")],
+      [htmlAttrOp("class", "foo")],
+      [attrOp("end", "2")],
+      [htmlAttrOp("onclick", "alert(1)")],
+      [childStyleOp],
+      [{ type: "split", property: "x", value: "1" } as unknown as PatchOperation],
+      [],
+    ];
+    for (const ops of cases) {
+      const eligible = shouldUseSdkCutover(true, true, "hf-abc", ops);
+      expect(sdkCutoverIneligibleReason("hf-abc", ops) === null).toBe(eligible);
+    }
+  });
+});

package/src/utils/sdkCutoverEligibility.ts

@@ -123,21 +123,44 @@ export function isResolverDisagreement(session: Composition, hfId: string): bool
   }
 }
 
+/**
+ * Why a batch cannot take the SDK cutover path, or null when it can.
+ *
+ * `ineligible_operation` used to be a single decline reason covering all of
+ * these, which made the post-flip telemetry unactionable — a structural edit the
+ * SDK has no vocabulary for (expected and permanent) was indistinguishable from
+ * a reserved-attribute decline (narrow, and possibly worth fixing). The order
+ * mirrors `shouldUseSdkCutover`'s conjunction, so the first failing check names
+ * the reason.
+ */
+export type SdkCutoverIneligibleReason =
+  | "target_unaddressable"
+  | "no_ops"
+  | "unsupported_op_type"
+  | "child_scoped_op"
+  | "reserved_attribute"
+  | "unsafe_html_attribute";
+
+export function sdkCutoverIneligibleReason(
+  hfId: string | null | undefined,
+  ops: PatchOperation[],
+): SdkCutoverIneligibleReason | null {
+  if (!hfId) return "target_unaddressable";
+  if (ops.length === 0) return "no_ops";
+  if (!ops.every((o) => CUTOVER_OP_TYPES.has(o.type))) return "unsupported_op_type";
+  if (hasChildScopedOp(ops)) return "child_scoped_op";
+  if (ops.some(mapsToReservedAttr)) return "reserved_attribute";
+  if (hasUnsafeHtmlAttributeOp(ops)) return "unsafe_html_attribute";
+  return null;
+}
+
 export function shouldUseSdkCutover(
   flagEnabled: boolean,
   hasSession: boolean,
   hfId: string | null | undefined,
   ops: PatchOperation[],
 ): boolean {
-  return (
-    flagEnabled &&
-    hasSession &&
-    !!hfId &&
-    ops.length > 0 &&
-    ops.every((o) => CUTOVER_OP_TYPES.has(o.type)) &&
-    // SDK edit ops target only the element hfId; child-scoped patch ops need the server path.
-    !hasChildScopedOp(ops) &&
-    !ops.some(mapsToReservedAttr) &&
-    !hasUnsafeHtmlAttributeOp(ops)
-  );
+  // Derived from the reason function so the two can never disagree about which
+  // batches are eligible.
+  return flagEnabled && hasSession && sdkCutoverIneligibleReason(hfId, ops) === null;
 }

package/src/utils/studioHelpers.test.ts

@@ -5,6 +5,7 @@ import {
   findMatchingTimelineElementId,
   findTimelineIdByAncestor,
   resolveDroppedAssetDimensions,
+  resolveElementTrack,
   resolveTimelineIdForSelection,
   resolveTimelineSelectionSeekTime,
 } from "./studioHelpers";
@@ -42,6 +43,13 @@ describe("findMatchingTimelineElementId", () => {
     expect(findMatchingTimelineElementId({ id: "s1", sourceFile: "index.html" }, els)).toBe("s1");
   });
 
+  it("matches by hfId when the selection has no domId, so an element with no authored id can still be found", () => {
+    const els = [el({ id: "hf-1", domId: undefined, hfId: "hf-1", sourceFile: "index.html" })];
+    expect(
+      findMatchingTimelineElementId({ id: undefined, hfId: "hf-1", sourceFile: "index.html" }, els),
+    ).toBe("hf-1");
+  });
+
   it("returns a qualified id for a sub-comp child with no matching timeline element", () => {
     const els = [el({ id: "s3", domId: "s3", sourceFile: "index.html" })];
     expect(
@@ -199,3 +207,13 @@ describe("resolveDroppedAssetDimensions", () => {
     expect(load).toHaveBeenCalledOnce();
   });
 });
+
+describe("resolveElementTrack", () => {
+  it("rounds an authored track", () => {
+    expect(resolveElementTrack({ authoredTrack: 2.4, track: 0 })).toBe(2);
+  });
+
+  it("falls back to the resolved track, rounded, when nothing was authored", () => {
+    expect(resolveElementTrack({ authoredTrack: undefined, track: 3.6 })).toBe(4);
+  });
+});

package/src/utils/studioHelpers.ts

@@ -126,9 +126,15 @@ export function getHistoryShortcutLabel(action: "undo" | "redo"): string {
   return action === "undo" ? `${modifier}+Z` : `${modifier}+Shift+Z`;
 }
 
-type ElementMatchSelection = Pick<
+export type ElementMatchSelection = Pick<
   DomEditSelection,
-  "id" | "selector" | "selectorIndex" | "sourceFile" | "compositionSrc" | "isCompositionHost"
+  | "id"
+  | "hfId"
+  | "selector"
+  | "selectorIndex"
+  | "sourceFile"
+  | "compositionSrc"
+  | "isCompositionHost"
 >;
 
 function matchesByDomId(
@@ -142,6 +148,17 @@ function matchesByDomId(
   );
 }
 
+function matchesByHfId(
+  selection: ElementMatchSelection,
+  element: TimelineElement,
+  selectionSourceFile: string,
+): boolean {
+  if (!selection.hfId) return false;
+  return (
+    element.hfId === selection.hfId && (element.sourceFile || "index.html") === selectionSourceFile
+  );
+}
+
 function matchesByCompositionHost(
   selection: ElementMatchSelection,
   element: TimelineElement,
@@ -172,14 +189,22 @@ export function findMatchingTimelineElementId(
   // scan let `.find()` stop at an EARLIER, unrelated host that merely shares
   // the compositionSrc, before the scan ever reached the correct id/selector
   // match further down the list — collapsing every repeated host to the
-  // first one. Try id, then selector, across the WHOLE list first; only fall
-  // back to the coarser compositionSrc-only match when neither identifies a
-  // specific element.
+  // first one. Try id, then hfId, then selector, across the WHOLE list
+  // first; only fall back to the coarser compositionSrc-only match when
+  // none of them identifies a specific element.
   const byId = selection.id
     ? elements.find((el) => matchesByDomId(selection, el, selectionSourceFile))
     : undefined;
   if (byId) return byId.key ?? byId.id;
 
+  // hfId is the stable content-hash id every element gets regardless of
+  // whether it has a real DOM id — the only correlator for an element like
+  // an ungroup child that has neither an authored id nor a selector.
+  const byHfId = selection.hfId
+    ? elements.find((el) => matchesByHfId(selection, el, selectionSourceFile))
+    : undefined;
+  if (byHfId) return byHfId.key ?? byHfId.id;
+
   const bySelector = selection.selector
     ? elements.find((el) => matchesBySelector(selection, el))
     : undefined;
@@ -198,6 +223,17 @@ export function findMatchingTimelineElementId(
   return null;
 }
 
+// The element's track: authored if given, else the runtime's already-resolved
+// fallback — always rounded to an integer index either way. Shared by the
+// group/ungroup and razor-split flows so they can't drift out of sync again.
+export function resolveElementTrack(
+  element: Pick<TimelineElement, "authoredTrack" | "track">,
+): number {
+  return Math.round(
+    Number.isFinite(element.authoredTrack) ? (element.authoredTrack as number) : element.track,
+  );
+}
+
 /**
  * A selected DOM node may be a static descendant of a clip (e.g. the `.num` text
  * inside a `#stat1` card) — not a timeline element itself. Walk up to the nearest

package/src/utils/studioUiPreferences.test.ts

@@ -73,6 +73,20 @@ describe("timelineSnapEnabled preference", () => {
   });
 });
 
+describe("rippleEditEnabled preference", () => {
+  it("round-trips through storage", () => {
+    const storage = createStorage();
+    writeStudioUiPreferences({ rippleEditEnabled: false }, storage);
+    expect(readStudioUiPreferences(storage).rippleEditEnabled).toBe(false);
+  });
+
+  it("ignores non-boolean values", () => {
+    const storage = createStorage();
+    storage.setItem("hf-studio-ui-preferences", JSON.stringify({ rippleEditEnabled: "yes" }));
+    expect(readStudioUiPreferences(storage).rippleEditEnabled).toBeUndefined();
+  });
+});
+
 describe("thumbnailMode preference", () => {
   it("round-trips the adaptive mode", () => {
     const storage = createStorage();

package/src/utils/studioUiPreferences.ts

@@ -24,6 +24,9 @@ export interface StudioUiPreferences {
   snapToGrid?: boolean;
   /** Timeline magnet: snap clip drags/trims/drops to playhead, clip edges, and beats. */
   timelineSnapEnabled?: boolean;
+  /** Keeps the main track gapless: deleting a clip closes the gap. Distinct
+   *  from `timelineSnapEnabled` ("Magnet", drag/trim snapping). */
+  rippleEditEnabled?: boolean;
   /** Transport + ruler readout mode: timecode or frame number. */
   timeDisplayMode?: TimelineTimeDisplayMode;
   /**
@@ -136,6 +139,9 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
     if (typeof parsed.timelineSnapEnabled === "boolean") {
       preferences.timelineSnapEnabled = parsed.timelineSnapEnabled;
     }
+    if (typeof parsed.rippleEditEnabled === "boolean") {
+      preferences.rippleEditEnabled = parsed.rippleEditEnabled;
+    }
     if (parsed.timeDisplayMode === "time" || parsed.timeDisplayMode === "frame") {
       preferences.timeDisplayMode = parsed.timeDisplayMode;
     }

package/src/utils/studioUrlState.ts

@@ -31,16 +31,24 @@ export interface StudioUrlState {
 const VALID_TABS: RightPanelTab[] = ["layers", "design", "renders", "slideshow", "variables"];
 
 /**
- * The composition a schema-level panel (Variables / Slideshow) targets on the
- * master view, where there is no explicit `activeCompPath`. Prefer the
- * `index.html` convention, but fall back to the first `.html` in the file tree
+ * The composition auto-open and a schema-level panel (Variables / Slideshow)
+ * target on the master view, where there is no explicit `activeCompPath`.
+ * Prefer the `index.html` convention, but fall back to the first entry
  * (composition-browser order) so projects whose entry file is `card.html`,
  * `hero.html`, etc. don't silently mis-target a non-existent `index.html`.
- * Returns null when the project carries no composition file at all.
+ * Takes the server's filtered composition list, never the raw file tree —
+ * a non-composition `.html` (a vendored preset, one with no
+ * `data-composition-id`) must never become the target. Returns null when the
+ * project carries no composition file at all.
  */
-export function resolveMasterCompositionPath(fileTree: string[]): string | null {
-  if (fileTree.includes("index.html")) return "index.html";
-  return fileTree.find((p) => p.endsWith(".html")) ?? null;
+export function resolveMasterCompositionPath(compositions: string[]): string | null {
+  if (compositions.includes("index.html")) return "index.html";
+  return compositions.find((p) => p.endsWith(".html")) ?? null;
+}
+
+/** A URL with no `activeCompPath` needs no hydration step — there's nothing to apply. */
+export function isHydratedFromUrlState(urlState: StudioUrlState): boolean {
+  return urlState.activeCompPath == null;
 }
 
 export function normalizeStudioUrlPanelTab(tab: RightPanelTab | null): RightPanelTab | null {

package/src/utils/timelineCompositionInsert.ts

@@ -3,6 +3,7 @@ import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
 import type { RecordEditInput } from "./studioFileHistory";
 import { buildProjectApiPath } from "./projectRouting";
 import { studioWriteHeaders } from "./studioFileVersion";
+import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
 
 interface TimelineCompositionInsertionResult {
   path: string;
@@ -76,7 +77,7 @@ export async function commitTimelineCompositionInsertion(input: {
       await input.writeFile(input.targetPath, result.before, result.after);
       throw error;
     }
-    input.selectHost(`${input.targetPath}#${result.hostId}`);
+    input.selectHost(deriveTimelineStoreKeyForDomId(result.hostId, input.targetPath));
     try {
       input.resync?.();
     } catch (error) {

package/src/utils/timelineInspector.ts

@@ -34,6 +34,16 @@ export function isAudioTimelineElement(
   return Boolean(element.src && AUDIO_SOURCE_EXT_RE.test(element.src));
 }
 
+/** The two tags the property panel lets you put a volume automation lane on.
+ * Single owner: `groupAutomationLanes`, `automationLaneCountOf` and
+ * `TimelineAutomationLaneSlot`'s clip filter all have to agree on this set. */
+export function isAudioOrVideoTimelineElement(
+  element: Pick<TimelineElement, "tag" | "src"> | null | undefined,
+): boolean {
+  if (!element) return false;
+  return isAudioTimelineElement(element) || element.tag.trim().toLowerCase() === "video";
+}
+
 /** True for the music track: an audio element with data-timeline-role="music",
  *  or — when no role is set — an id matching the music regex. Voiceover/other
  *  audio (explicit non-music role) is excluded. */