@hyperframes/studio 0.8.46 → 0.8.48

package/src/utils/sdkCutover.ts

@@ -5,7 +5,11 @@ import * as studioAvailability from "../components/editor/manualEditingAvailabil
 import { trackStudioEvent } from "./studioTelemetry";
 import { patchOpsToSdkEditOps } from "./sdkOpMapping";
 import { recordResolverParity, recordAnimationResolverParity } from "./sdkResolverShadow";
-import { shouldDeclineTextCutoverForTarget, shouldUseSdkCutover } from "./sdkCutoverEligibility";
+import {
+  isResolverDisagreement,
+  shouldDeclineTextCutoverForTarget,
+  shouldUseSdkCutover,
+} from "./sdkCutoverEligibility";
 import {
   asCutoverError,
   declinedCutover,
@@ -78,15 +82,17 @@ export async function sdkCutoverPersist(
   options?: CutoverOptions,
 ): Promise<CutoverResult> {
   if (!shouldUseSdkCutover(sdkFamilyEnabled("dom"), !!sdkSession, selection.hfId, ops))
-    return declinedCutover("ineligible_operation");
-  if (!sdkSession) return declinedCutover("session_unavailable");
+    return declinedCutover("ineligible_operation", "dom");
+  if (!sdkSession) return declinedCutover("session_unavailable", "dom");
   const hfId = selection.hfId;
-  if (!hfId) return declinedCutover("target_unaddressable");
+  if (!hfId) return declinedCutover("target_unaddressable", "dom");
   const target = sdkSession.getElement(hfId);
-  if (!target) return declinedCutover("target_not_found");
+  if (!target)
+    return declinedCutover("target_not_found", "dom", isResolverDisagreement(sdkSession, hfId));
   if (shouldDeclineTextCutoverForTarget(target, ops))
-    return declinedCutover("unsupported_text_target");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+    return declinedCutover("unsupported_text_target", "dom");
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "dom");
   const result = await persistSdkCandidateMutation(
     sdkSession,
     targetPath,
@@ -122,10 +128,12 @@ export async function sdkTimingPersist(
   // Dark-launch gate: without this, timing cutover runs whenever an SDK session
   // exists (it always does, for shadow/selection) — flipping the flag OFF would
   // NOT disable it. Gate here so flag-off routes back to the legacy server path.
-  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (!sdkSession.getElement(hfId)) return declinedCutover("target_not_found");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled", "timing");
+  if (!sdkSession) return declinedCutover("session_unavailable", "timing");
+  if (!sdkSession.getElement(hfId))
+    return declinedCutover("target_not_found", "timing", isResolverDisagreement(sdkSession, hfId));
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "timing");
   try {
     const serializedBefore = sdkSession.serialize();
     const result = await persistSdkCandidateMutation(
@@ -166,11 +174,17 @@ export async function sdkTimingBatchPersist(
       { targetPath, compositionPath: deps.compositionPath },
     );
   }
-  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
-  if (changes.some((change) => !sdkSession.getElement(change.hfId)))
-    return declinedCutover("target_not_found");
+  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled", "timing");
+  if (!sdkSession) return declinedCutover("session_unavailable", "timing");
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "timing");
+  const unresolved = changes.find((change) => !sdkSession.getElement(change.hfId));
+  if (unresolved)
+    return declinedCutover(
+      "target_not_found",
+      "timing",
+      isResolverDisagreement(sdkSession, unresolved.hfId),
+    );
   try {
     const serializedBefore = sdkSession.serialize();
     const result = await persistSdkCandidateMutation(
@@ -244,9 +258,9 @@ export function sdkGsapTweenPersist(
   // Leading dark-launch gate so flag-off does no SDK touch (getElement) at all —
   // matches the other three chokepoints' discipline.
   if (!sdkFamilyEnabled("gsap-animation"))
-    return Promise.resolve(declinedCutover("feature_disabled"));
+    return Promise.resolve(declinedCutover("feature_disabled", "gsap-animation"));
   if (op.kind === "add" && sdkSession && !sdkSession.getElement(op.target))
-    return Promise.resolve(declinedCutover("target_not_found"));
+    return Promise.resolve(declinedCutover("target_not_found", "gsap-animation"));
   // dispatchGsapOpAndPersist declines on before===after — that catches stale
   // animationIds and unsupported shapes (e.g. from-prop on a plain tween), falling
   // back to the server path. This subsumes explicit existence guards for set/remove.
@@ -285,9 +299,10 @@ async function dispatchGsapOpAndPersist(
   }
   // Dark-launch gate (shared chokepoint for every GSAP-op cutover persist):
   // flag OFF → explicit decline → caller falls back to the legacy server path.
-  if (!sdkFamilyEnabled(family)) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+  if (!sdkFamilyEnabled(family)) return declinedCutover("feature_disabled", family);
+  if (!sdkSession) return declinedCutover("session_unavailable", family);
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", family);
   const session = sdkSession;
   // persistSdkCandidateMutation owns the shared per-project/file transaction
   // coordinator used by both SDK and legacy GSAP writes.
@@ -559,10 +574,16 @@ export async function sdkDeletePersist(
     { targetPath, compositionPath: deps.compositionPath },
   );
   // Dark-launch gate: flag OFF → legacy server delete path.
-  if (!sdkFamilyEnabled("lifecycle")) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (!sdkSession.getElement(hfId)) return declinedCutover("target_not_found");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+  if (!sdkFamilyEnabled("lifecycle")) return declinedCutover("feature_disabled", "lifecycle");
+  if (!sdkSession) return declinedCutover("session_unavailable", "lifecycle");
+  if (!sdkSession.getElement(hfId))
+    return declinedCutover(
+      "target_not_found",
+      "lifecycle",
+      isResolverDisagreement(sdkSession, hfId),
+    );
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "lifecycle");
   const result = await persistSdkCandidateMutation(
     sdkSession,
     targetPath,

package/src/utils/sdkCutoverEligibility.ts

@@ -4,8 +4,10 @@
  * sdkCutover.ts (which hit the packages/studio 600-line filesize cap) — this
  * block has no dependency on the persist/dispatch functions there.
  */
+import type { Composition } from "@hyperframes/sdk";
 import type { PatchOperation } from "./sourcePatcher";
 import { isAllowedHtmlAttribute, isSafeAttributeValue } from "./htmlAttrSafety";
+import { resolveSnapshot } from "./sdkResolverShadow";
 
 const CUTOVER_OP_TYPES = new Set<PatchOperation["type"]>([
   "inline-style",
@@ -102,6 +104,25 @@ export function shouldDeclineTextCutoverForTarget(target: unknown, ops: PatchOpe
   return tag !== null && NON_HTML_CHILD_TAGS.has(tag);
 }
 
+/**
+ * On a `target_not_found`, decide whether the miss is the known benign class
+ * (node genuinely absent from the session — nothing dispatch could have done)
+ * or a resolver disagreement: the shadow's broader resolver finds it, so
+ * dispatch could have made the edit and `getElement` refused it. The shadow
+ * event stays silent in that case, so this flag is the only signal for it.
+ *
+ * Diagnostic context only — it must never turn a clean decline into a throw, so
+ * a session shape without `getElements` reports "no disagreement" and the edit
+ * falls back exactly as it otherwise would have.
+ */
+export function isResolverDisagreement(session: Composition, hfId: string): boolean {
+  try {
+    return resolveSnapshot(session, hfId) !== null;
+  } catch {
+    return false;
+  }
+}
+
 export function shouldUseSdkCutover(
   flagEnabled: boolean,
   hasSession: boolean,

package/src/utils/sdkCutoverPolicy.test.ts

@@ -7,8 +7,17 @@ import {
 } from "./sdkCutoverPolicy";
 
 describe("Studio SDK operation-family policy", () => {
-  it("enables no family from the master switch alone", () => {
-    expect(resolveEnabledSdkFamilies({}, true).size).toBe(0);
+  it("enables every family when the master switch is on and no family list is set", () => {
+    const all = new Set(STUDIO_SDK_OPERATION_FAMILIES);
+    expect(resolveEnabledSdkFamilies({}, true)).toEqual(all);
+    expect(resolveEnabledSdkFamilies({ VITE_STUDIO_SDK_CUTOVER_FAMILIES: "" }, true)).toEqual(all);
+    expect(resolveEnabledSdkFamilies({ VITE_STUDIO_SDK_CUTOVER_FAMILIES: "  " }, true)).toEqual(
+      all,
+    );
+  });
+
+  it("enables no family when the master switch is off, regardless of the family list", () => {
+    expect(resolveEnabledSdkFamilies({}, false).size).toBe(0);
     expect(resolveEnabledSdkFamilies({ VITE_STUDIO_SDK_CUTOVER_FAMILIES: "dom" }, false).size).toBe(
       0,
     );

package/src/utils/sdkCutoverPolicy.ts

@@ -54,7 +54,8 @@ export function resolveEnabledSdkFamilies(
 ): ReadonlySet<StudioSdkOperationFamily> {
   if (!masterEnabled) return new Set();
   const raw = env["VITE_STUDIO_SDK_CUTOVER_FAMILIES"];
-  if (typeof raw !== "string" || raw.trim() === "") return new Set();
+  // Unset/blank = every family. The list exists to RESTRICT (kill switch per family).
+  if (typeof raw !== "string" || raw.trim() === "") return new Set(STUDIO_SDK_OPERATION_FAMILIES);
   const requested = raw
     .split(",")
     .map((family) => family.trim())
@@ -85,8 +86,9 @@ export function renderStudioSdkCutoverReport(): string {
   return [
     "# Studio SDK cutover report",
     "",
-    "Master flag: `VITE_STUDIO_SDK_CUTOVER_ENABLED=true`",
-    "Family flag: `VITE_STUDIO_SDK_CUTOVER_FAMILIES=dom,timing,...`",
+    "Default: SDK persist ON for every family. Kill switches:",
+    "  `VITE_STUDIO_SDK_CUTOVER_ENABLED=false` (all families → server path)",
+    "  `VITE_STUDIO_SDK_CUTOVER_FAMILIES=dom,timing` (only listed families → SDK; rest → server)",
     "",
     "A family graduates only after zero unexplained resolver/serialization divergences over its agreed corpus and soak window.",
     "",

package/src/utils/sdkEditTransaction.decline.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("./studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+import { trackStudioEvent } from "./studioTelemetry";
+import { declinedCutover } from "./sdkEditTransaction";
+
+describe("declinedCutover telemetry", () => {
+  it("emits sdk_cutover_declined with reason and family, and returns the declined result", () => {
+    const result = declinedCutover("target_not_found", "timing");
+    expect(result).toEqual({ status: "declined", reason: "target_not_found" });
+    expect(trackStudioEvent).toHaveBeenCalledWith("sdk_cutover_declined", {
+      reason: "target_not_found",
+      family: "timing",
+    });
+  });
+
+  it("emits family:null when the decline happens before a family is known", () => {
+    declinedCutover("no_change");
+    expect(trackStudioEvent).toHaveBeenCalledWith("sdk_cutover_declined", {
+      reason: "no_change",
+      family: null,
+    });
+  });
+
+  it("omits resolverDisagreement when it is not set, and carries it when it is", () => {
+    declinedCutover("target_not_found", "timing");
+    expect(trackStudioEvent).toHaveBeenLastCalledWith("sdk_cutover_declined", {
+      reason: "target_not_found",
+      family: "timing",
+    });
+
+    declinedCutover("target_not_found", "timing", true);
+    expect(trackStudioEvent).toHaveBeenLastCalledWith("sdk_cutover_declined", {
+      reason: "target_not_found",
+      family: "timing",
+      resolverDisagreement: true,
+    });
+
+    declinedCutover("target_not_found", "timing", false);
+    expect(trackStudioEvent).toHaveBeenLastCalledWith("sdk_cutover_declined", {
+      reason: "target_not_found",
+      family: "timing",
+    });
+  });
+});

package/src/utils/sdkEditTransaction.ts

@@ -3,6 +3,7 @@ import type { EditHistoryKind } from "./editHistory";
 import { hashContent, markSelfWrite } from "../hooks/sdkSelfWriteRegistry";
 import { trackStudioEvent } from "./studioTelemetry";
 import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
+import type { StudioSdkOperationFamily } from "./sdkCutoverPolicy";
 
 export type CutoverResult =
   | { status: "declined"; reason: string }
@@ -66,7 +67,27 @@ interface CandidateEdit {
   after: string;
 }
 
-export function declinedCutover(reason: string): CutoverResult {
+/**
+ * Explicit fall-back to the legacy server path. Emits `sdk_cutover_declined` so
+ * post-flip we can distinguish "SDK took the edit" from "SDK bowed out"; payload
+ * is reason + family only (no hfId / path / content).
+ *
+ * `resolverDisagreement` is the one extra field with diagnostic value beyond the
+ * reason itself: on a `target_not_found`, the shadow's `resolveSnapshot` (what
+ * dispatch resolves) found the element that `getElement` could not. The shadow
+ * event stays silent in that case, so without this flag the case is invisible —
+ * and it is an adoption loss (a dispatchable edit refused), not a missing node.
+ */
+export function declinedCutover(
+  reason: string,
+  family?: StudioSdkOperationFamily,
+  resolverDisagreement?: boolean,
+): CutoverResult {
+  trackStudioEvent("sdk_cutover_declined", {
+    reason,
+    family: family ?? null,
+    ...(resolverDisagreement ? { resolverDisagreement: true } : {}),
+  });
   return { status: "declined", reason };
 }
 

package/src/utils/sdkResolverShadow.ts

@@ -96,7 +96,16 @@ function countHfIdInSource(source: string, id: string): number {
   );
 }
 
-function resolveSnapshot(session: Composition, id: string): FlatEl | null {
+/**
+ * Resolvability the SDK DISPATCH path actually has (mirrors `resolveScoped`):
+ * exact scoped-path match, then canonical bare match, then first bare match.
+ *
+ * Exported so the cutover path can distinguish its two `target_not_found` cases:
+ * `Composition.getElement` is narrower (canonical-only for a bare id) than what
+ * `dispatch` resolves, so an element can be genuinely dispatchable yet still
+ * fail `getElement` — a resolver disagreement worth fixing, not a missing node.
+ */
+export function resolveSnapshot(session: Composition, id: string): FlatEl | null {
   const els = session.getElements();
   const exact = els.find((el) => el.scopedId === id);
   if (exact) return exact;

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/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. */