@hyperframes/studio 0.6.100 → 0.6.101

package/src/player/store/playerStore.ts

@@ -1,6 +1,7 @@
 import { create } from "zustand";
 import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
 import type { BeatEditState } from "../../utils/beatEditing";
+import type { ClipManifestClip } from "../lib/playbackTypes";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 
 /** Minimal keyframe cache types — mirrors GsapKeyframesData without pulling in Node-only gsap-parser. */
@@ -50,6 +51,13 @@ export interface TimelineElement {
   timelineLocked?: boolean;
   /** Value of data-timeline-role attribute — used to identify music vs. voiceover. */
   timelineRole?: string;
+  /**
+   * Set by useExpandedTimelineElements on an inline-expanded sub-composition
+   * child: the absolute master-timeline start of the sub-comp host the child
+   * lives in. Presence marks the element as expanded; edits subtract it to get
+   * the child's local (sourceFile-relative) time. Works at any nesting depth.
+   */
+  expandedParentStart?: number;
 }
 
 export type ZoomMode = "fit" | "manual";
@@ -138,21 +146,22 @@ interface PlayerState {
   /** Undo/redo stacks for beat edits (in-memory, session-only). */
   beatUndo: BeatHistoryEntry[];
   beatRedo: BeatHistoryEntry[];
-  /** Apply a beat edit and record it for undo. */
   commitBeatEdits: (next: BeatEditState | null, label: string) => void;
-  /** Undo/redo the most recent beat edit; returns its label or null if none. */
   undoBeatEdits: () => string | null;
   redoBeatEdits: () => string | null;
-  /** Clear beat edit history (e.g. when the music track changes). */
   resetBeatHistory: () => void;
-  /** Callback that persists current beats to disk; registered by the analysis hook. */
   beatPersist: (() => void) | null;
   setBeatPersist: (fn: (() => void) | null) => void;
+
+  clipManifest: ClipManifestClip[] | null;
+  setClipManifest: (clips: ClipManifestClip[] | null) => void;
+  clipParentMap: Map<string, string>;
+  setClipParentMap: (map: Map<string, string>) => void;
 }
 
 interface BeatHistoryEntry {
-  restore: BeatEditState | null; // state to restore when this entry is applied
-  at: number; // original edit timestamp (for global undo ordering)
+  restore: BeatEditState | null;
+  at: number;
   label: string;
 }
 
@@ -271,6 +280,11 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
     return entry.label;
   },
 
+  clipManifest: null,
+  setClipManifest: (clips) => set({ clipManifest: clips }),
+  clipParentMap: new Map(),
+  setClipParentMap: (map) => set({ clipParentMap: map }),
+
   setIsPlaying: (playing) => {
     if (get().isPlaying === playing) return;
     set({ isPlaying: playing });
@@ -338,12 +352,12 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
       selectedKeyframes: new Set(),
       selectedElementIds: new Set(),
       keyframeCache: new Map(),
-      // Beat state is project-specific — clear it so a project switch can't
-      // apply the previous project's beats/undo/persist to the new one.
       beatAnalysis: null,
       beatEdits: null,
       beatUndo: [],
       beatRedo: [],
       beatPersist: null,
+      clipManifest: null,
+      clipParentMap: new Map(),
     }),
 }));

package/src/telemetry/events.test.ts

@@ -7,7 +7,12 @@ vi.mock("./client", () => ({
   trackEvent: (...args: unknown[]) => trackEvent(...args),
 }));
 
-const { trackStudioSessionStart, trackStudioRenderStart } = await import("./events");
+const {
+  trackStudioSessionStart,
+  trackStudioRenderStart,
+  trackStudioRazorSplit,
+  trackStudioExpandedClipEdit,
+} = await import("./events");
 
 describe("studio telemetry events", () => {
   beforeEach(() => {
@@ -54,4 +59,14 @@ describe("studio telemetry events", () => {
       composition: undefined,
     });
   });
+
+  it("trackStudioRazorSplit emits 'studio_razor_split' with mode and count", () => {
+    trackStudioRazorSplit({ mode: "all", count: 3 });
+    expect(trackEvent).toHaveBeenCalledWith("studio_razor_split", { mode: "all", count: 3 });
+  });
+
+  it("trackStudioExpandedClipEdit emits 'studio_expanded_clip_edit' with action", () => {
+    trackStudioExpandedClipEdit({ action: "resize" });
+    expect(trackEvent).toHaveBeenCalledWith("studio_expanded_clip_edit", { action: "resize" });
+  });
 });

package/src/telemetry/events.ts

@@ -48,6 +48,21 @@ function getBrowserDoctorSummary(): string {
   }
 }
 
+export function trackStudioRazorSplit(props: { mode: "single" | "all"; count: number }): void {
+  trackEvent("studio_razor_split", {
+    mode: props.mode,
+    count: props.count,
+  });
+}
+
+// Adoption signal for the inline timeline-expansion surface: edits applied to a
+// sub-composition child clip while its parent scene is expanded.
+export function trackStudioExpandedClipEdit(props: {
+  action: "move" | "resize" | "delete" | "split";
+}): void {
+  trackEvent("studio_expanded_clip_edit", { action: props.action });
+}
+
 export function trackStudioFeedback(props: { rating: number; comment?: string }): void {
   trackEvent("survey sent", {
     $survey_id: "studio_experience",

package/src/utils/blockCategories.ts

@@ -1,11 +1,10 @@
 import {
   type BlockCategory,
-  type BlockCategoryMeta,
   BLOCK_CATEGORIES,
   resolveBlockCategory,
 } from "@hyperframes/core/registry";
 
-export type { BlockCategory, BlockCategoryMeta };
+export type { BlockCategory };
 export { BLOCK_CATEGORIES, resolveBlockCategory };
 
 const COLOR_MAP: Record<BlockCategory, { bg: string; text: string; dot: string }> = {
@@ -17,6 +16,7 @@ const COLOR_MAP: Record<BlockCategory, { bg: string; text: string; dot: string }
   captions: { bg: "bg-cyan-500/15", text: "text-cyan-400", dot: "bg-cyan-400" },
   effects: { bg: "bg-rose-500/15", text: "text-rose-400", dot: "bg-rose-400" },
   "text-effects": { bg: "bg-violet-500/15", text: "text-violet-400", dot: "bg-violet-400" },
+  "code-animation": { bg: "bg-emerald-500/15", text: "text-emerald-400", dot: "bg-emerald-400" },
 };
 
 export function getCategoryColors(category: BlockCategory) {

package/src/utils/sdkShadow.test.ts

@@ -1,8 +1,26 @@
-import { describe, expect, it } from "vitest";
-import { patchOpsToSdkEditOps, SdkShadowMismatch } from "./sdkShadow";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import {
+  patchOpsToSdkEditOps,
+  runShadowDelete,
+  runShadowTiming,
+  runShadowGsapTween,
+  SdkShadowMismatch,
+} from "./sdkShadow";
 import type { PatchOperation } from "./sourcePatcher";
 import { openComposition } from "@hyperframes/sdk";
 
+// Capture sdk_shadow_dispatch telemetry for the non-PatchOperation runners.
+const trackedEvents: Array<{ event: string; props: Record<string, unknown> }> = [];
+vi.mock("./studioTelemetry", () => ({
+  trackStudioEvent: (event: string, props: Record<string, unknown>) =>
+    trackedEvents.push({ event, props }),
+}));
+beforeEach(() => {
+  trackedEvents.length = 0;
+});
+const lastShadow = () =>
+  trackedEvents.filter((e) => e.event === "sdk_shadow_dispatch").at(-1)?.props;
+
 const BASE_HTML = /* html */ `<!DOCTYPE html>
 <html><body>
   <div data-hf-id="hf-box" style="color: red; width: 100px;" data-name="box">Hello</div>
@@ -144,3 +162,85 @@ describe("sdkShadowDispatch (integration)", () => {
     });
   });
 });
+
+const TIMING_HTML = /* html */ `<!DOCTYPE html>
+<html><body>
+  <div data-hf-id="hf-clip" data-start="0" data-duration="1" data-track="0">clip</div>
+</body></html>`;
+
+const GSAP_HTML = `<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px">
+  <div data-hf-id="hf-box" style="opacity:0"></div>
+  <script>var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { opacity: 1, duration: 0.5 }, 0.2);
+window.__timelines["t"] = tl;</script>
+</div>`;
+
+const NO_TIMELINE_HTML = `<div data-hf-id="hf-stage" data-hf-root>
+  <div data-hf-id="hf-box"></div>
+  <script>gsap.defaults({ ease: "power1.out" });
+window.__timelines = {};</script>
+</div>`;
+
+describe("runShadowDelete", () => {
+  it("removes the element from the SDK session and reports parity", async () => {
+    const session = await openComposition(BASE_HTML);
+    runShadowDelete(session, "hf-box");
+    expect(session.getElement("hf-box")).toBeNull();
+    expect(lastShadow()).toMatchObject({ op: "delete", dispatched: true, mismatchCount: 0 });
+  });
+
+  it("reports no_hf_id when selection has no hf-id", async () => {
+    const session = await openComposition(BASE_HTML);
+    runShadowDelete(session, null);
+    expect(lastShadow()).toMatchObject({ op: "delete", dispatched: false, reason: "no_hf_id" });
+  });
+
+  it("reports cannot_dispatch when the element is not addressable", async () => {
+    const session = await openComposition(BASE_HTML);
+    runShadowDelete(session, "hf-missing");
+    expect(lastShadow()).toMatchObject({
+      op: "delete",
+      dispatched: false,
+      reason: "cannot_dispatch",
+    });
+  });
+});
+
+describe("runShadowTiming", () => {
+  it("applies timing and reports parity against the snapshot", async () => {
+    const session = await openComposition(TIMING_HTML);
+    runShadowTiming(session, "hf-clip", { start: 2, duration: 3, trackIndex: 1 });
+    const el = session.getElement("hf-clip");
+    expect(el?.start).toBe(2);
+    expect(el?.duration).toBe(3);
+    expect(el?.trackIndex).toBe(1);
+    expect(lastShadow()).toMatchObject({ op: "timing", dispatched: true, mismatchCount: 0 });
+  });
+});
+
+describe("runShadowGsapTween", () => {
+  it("dispatches add against a real timeline and reports success", async () => {
+    const session = await openComposition(GSAP_HTML);
+    runShadowGsapTween(session, {
+      kind: "add",
+      target: "hf-box",
+      tween: { method: "to", properties: { x: 100 }, duration: 0.5 },
+    });
+    expect(lastShadow()).toMatchObject({ op: "gsap", dispatched: true, mismatchCount: 0 });
+  });
+
+  it("reports cannot_dispatch (E_NO_GSAP_TIMELINE) when the script has no timeline", async () => {
+    const session = await openComposition(NO_TIMELINE_HTML);
+    runShadowGsapTween(session, {
+      kind: "add",
+      target: "hf-box",
+      tween: { method: "to", properties: { x: 100 } },
+    });
+    expect(lastShadow()).toMatchObject({
+      op: "gsap",
+      dispatched: false,
+      reason: "cannot_dispatch",
+      code: "E_NO_GSAP_TIMELINE",
+    });
+  });
+});

package/src/utils/sdkShadow.ts

@@ -9,7 +9,7 @@
  */
 
 import type { Composition } from "@hyperframes/sdk";
-import type { EditOp } from "@hyperframes/sdk";
+import type { EditOp, GsapTweenSpec } from "@hyperframes/sdk";
 import { STUDIO_SDK_SHADOW_ENABLED } from "../components/editor/manualEditingAvailability";
 import { trackStudioEvent } from "./studioTelemetry";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
@@ -182,6 +182,26 @@ export function sdkShadowDispatch(
  * Despite the telemetry focus, this function does mutate the SDK session — it
  * is not read-only. No-op when STUDIO_SDK_SHADOW_ENABLED is false.
  */
+// Property-path mismatches carry user content (inline-style values, edited
+// text) in expected/actual. Scrub before telemetry: fully redact text-content
+// values, length-cap the rest. The in-memory parity result keeps raw values.
+function redactValueForTelemetry(
+  property: string | undefined,
+  value: string | null | undefined,
+): string | null | undefined {
+  if (value == null) return value;
+  if (property === "text") return `[redacted len=${value.length}]`;
+  return value.length > 64 ? `${value.slice(0, 64)}…` : value;
+}
+
+function redactMismatchesForTelemetry(mismatches: SdkShadowMismatch[]): SdkShadowMismatch[] {
+  return mismatches.map((m) => ({
+    ...m,
+    expected: redactValueForTelemetry(m.property, m.expected),
+    actual: redactValueForTelemetry(m.property, m.actual),
+  }));
+}
+
 export function runShadowDispatch(
   session: Composition,
   selection: DomEditSelection,
@@ -191,6 +211,7 @@ export function runShadowDispatch(
   const hfId = selection.hfId;
   if (!hfId) {
     trackStudioEvent("sdk_shadow_dispatch", {
+      op: "property",
       dispatched: false,
       reason: "no_hf_id",
       mismatchCount: 0,
@@ -199,8 +220,185 @@ export function runShadowDispatch(
   }
   const result = sdkShadowDispatch(session, hfId, ops);
   trackStudioEvent("sdk_shadow_dispatch", {
+    op: "property",
     dispatched: result.dispatched,
     mismatchCount: result.mismatches.length,
-    mismatches: JSON.stringify(result.mismatches),
+    mismatches: JSON.stringify(redactMismatchesForTelemetry(result.mismatches)),
+  });
+}
+
+// ─── Shadow for non-PatchOperation ops (delete / timing / GSAP) ───────────────
+//
+// These ops never flow through persistDomEditOperations, so the property-path
+// shadow above never sees them. Each runner keeps the server authoritative and
+// only observes the SDK: can() pre-checks addressing/validity (pure, no
+// mutation — works even for GSAP, which has no element-snapshot value), then a
+// dispatch into the live session with a snapshot-based parity check.
+//
+// Parity coverage by op:
+//   delete  → getElement(id) === null               (full)
+//   timing  → snapshot.start/duration/trackIndex     (full)
+//   gsap    → tween id present/absent in animationIds (existence only — the
+//             tween's property values are script-level, not in the snapshot)
+
+/**
+ * can()-gated shadow dispatch. Emits sdk_shadow_dispatch tagged with `opLabel`.
+ * Mutates the SDK session (not read-only); server stays authoritative.
+ * No-op when STUDIO_SDK_SHADOW_ENABLED is false.
+ */
+function runShadowEditOp(
+  session: Composition,
+  op: EditOp,
+  opLabel: string,
+  dispatchAndCheck: () => SdkShadowMismatch[],
+): void {
+  const verdict = session.can(op);
+  if (!verdict.ok) {
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: opLabel,
+      dispatched: false,
+      reason: "cannot_dispatch",
+      code: verdict.code,
+      mismatchCount: 0,
+    });
+    return;
+  }
+  let mismatches: SdkShadowMismatch[];
+  try {
+    mismatches = dispatchAndCheck();
+  } catch (err) {
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: opLabel,
+      dispatched: false,
+      reason: "dispatch_error",
+      error: String(err),
+      mismatchCount: 0,
+    });
+    return;
+  }
+  trackStudioEvent("sdk_shadow_dispatch", {
+    op: opLabel,
+    dispatched: true,
+    mismatchCount: mismatches.length,
+    mismatches: JSON.stringify(mismatches),
+  });
+}
+
+/** Shadow an element delete. Parity: the element is gone from the SDK session. */
+export function runShadowDelete(session: Composition, hfId: string | null | undefined): void {
+  if (!STUDIO_SDK_SHADOW_ENABLED) return;
+  if (!hfId) {
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: "delete",
+      dispatched: false,
+      reason: "no_hf_id",
+      mismatchCount: 0,
+    });
+    return;
+  }
+  const op: EditOp = { type: "removeElement", target: hfId };
+  runShadowEditOp(session, op, "delete", () => {
+    session.batch(() => session.dispatch(op));
+    return session.getElement(hfId)
+      ? [
+          {
+            kind: "value_mismatch",
+            hfId,
+            property: "exists",
+            expected: "removed",
+            actual: "present",
+          },
+        ]
+      : [];
+  });
+}
+
+export interface ShadowTiming {
+  start?: number;
+  duration?: number;
+  trackIndex?: number;
+}
+
+/** Shadow a timing edit. Parity: snapshot start/duration/trackIndex match. */
+export function runShadowTiming(
+  session: Composition,
+  hfId: string | null | undefined,
+  timing: ShadowTiming,
+): void {
+  if (!STUDIO_SDK_SHADOW_ENABLED) return;
+  if (!hfId) {
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: "timing",
+      dispatched: false,
+      reason: "no_hf_id",
+      mismatchCount: 0,
+    });
+    return;
+  }
+  const op: EditOp = { type: "setTiming", target: hfId, ...timing };
+  runShadowEditOp(session, op, "timing", () => {
+    session.batch(() => session.dispatch(op));
+    const el = session.getElement(hfId);
+    const mismatches: SdkShadowMismatch[] = [];
+    const fields: Array<[keyof ShadowTiming, number | null | undefined]> = [
+      ["start", el?.start],
+      ["duration", el?.duration],
+      ["trackIndex", el?.trackIndex],
+    ];
+    for (const [key, actual] of fields) {
+      const expected = timing[key];
+      if (expected !== undefined && actual !== expected) {
+        mismatches.push({
+          kind: "value_mismatch",
+          hfId,
+          property: key,
+          expected: String(expected),
+          actual: actual == null ? null : String(actual),
+        });
+      }
+    }
+    return mismatches;
+  });
+}
+
+export type ShadowGsapOp =
+  | { kind: "add"; target: string; tween: GsapTweenSpec }
+  | { kind: "set"; animationId: string; properties: Partial<GsapTweenSpec> }
+  | { kind: "remove"; animationId: string };
+
+/**
+ * Shadow a GSAP tween mutation. Snapshot value-parity is NOT available: the
+ * tween lives in the GSAP <script>, and ElementSnapshot.animationIds is a stub
+ * (always [] — see sdk document.ts). So the signal here is can() addressing /
+ * validity + dispatch-didn't-throw, plus (for add) that the SDK returned a
+ * non-empty tween id. Full fidelity needs serialize()-script round-trip diffing,
+ * out of scope for shadow. // ponytail: upgrade when animationIds is populated.
+ */
+export function runShadowGsapTween(session: Composition, gsapOp: ShadowGsapOp): void {
+  if (!STUDIO_SDK_SHADOW_ENABLED) return;
+  const op: EditOp =
+    gsapOp.kind === "add"
+      ? { type: "addGsapTween", target: gsapOp.target, tween: gsapOp.tween }
+      : gsapOp.kind === "set"
+        ? { type: "setGsapTween", animationId: gsapOp.animationId, properties: gsapOp.properties }
+        : { type: "removeGsapTween", animationId: gsapOp.animationId };
+  runShadowEditOp(session, op, "gsap", () => {
+    let newId: string | undefined;
+    session.batch(() => {
+      if (gsapOp.kind === "add") newId = session.addGsapTween(gsapOp.target, gsapOp.tween);
+      else session.dispatch(op);
+    });
+    if (gsapOp.kind === "add" && !newId) {
+      return [
+        {
+          kind: "value_mismatch",
+          hfId: gsapOp.target,
+          property: "tweenId",
+          expected: "non-empty",
+          actual: null,
+        },
+      ];
+    }
+    return [];
   });
 }

package/src/utils/studioHelpers.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { resolveTimelineSelectionSeekTime } from "./studioHelpers";
+import { findMatchingTimelineElementId, resolveTimelineSelectionSeekTime } from "./studioHelpers";
 
 describe("resolveTimelineSelectionSeekTime", () => {
   it("keeps the current time when it is already inside the clip range", () => {
@@ -18,3 +18,27 @@ describe("resolveTimelineSelectionSeekTime", () => {
     expect(resolveTimelineSelectionSeekTime(Number.NaN, { start: 2, duration: 5 })).toBe(2);
   });
 });
+
+describe("findMatchingTimelineElementId", () => {
+  const el = (over: Record<string, unknown>) =>
+    ({ id: "x", start: 0, duration: 1, track: 0, tag: "div", ...over }) as never;
+
+  it("matches a top-level element by domId + sourceFile", () => {
+    const els = [el({ id: "s1", domId: "s1", sourceFile: "index.html" })];
+    expect(findMatchingTimelineElementId({ id: "s1", sourceFile: "index.html" }, els)).toBe("s1");
+  });
+
+  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(
+      findMatchingTimelineElementId(
+        { id: "stat-3", sourceFile: "compositions/stats-panel.html" },
+        els,
+      ),
+    ).toBe("compositions/stats-panel.html#stat-3");
+  });
+
+  it("returns null for an unmatched element in index.html", () => {
+    expect(findMatchingTimelineElementId({ id: "ghost", sourceFile: "index.html" }, [])).toBe(null);
+  });
+});

package/src/utils/studioHelpers.ts

@@ -116,38 +116,64 @@ export function getHistoryShortcutLabel(action: "undo" | "redo"): string {
   return action === "undo" ? `${modifier}+Z` : `${modifier}+Shift+Z`;
 }
 
+type ElementMatchSelection = Pick<
+  DomEditSelection,
+  "id" | "selector" | "selectorIndex" | "sourceFile" | "compositionSrc" | "isCompositionHost"
+>;
+
+function matchesByDomId(
+  selection: ElementMatchSelection,
+  element: TimelineElement,
+  selectionSourceFile: string,
+): boolean {
+  if (!selection.id) return false;
+  return (
+    element.domId === selection.id && (element.sourceFile || "index.html") === selectionSourceFile
+  );
+}
+
+function matchesByCompositionHost(
+  selection: ElementMatchSelection,
+  element: TimelineElement,
+): boolean {
+  if (!selection.isCompositionHost || !selection.compositionSrc) return false;
+  return element.compositionSrc === selection.compositionSrc;
+}
+
+function matchesBySelector(selection: ElementMatchSelection, element: TimelineElement): boolean {
+  if (!selection.selector) return false;
+  return (
+    element.selector === selection.selector &&
+    (element.selectorIndex ?? 0) === (selection.selectorIndex ?? 0) &&
+    (element.sourceFile ?? "index.html") === selection.sourceFile
+  );
+}
+
+function elementMatchesSelection(
+  selection: ElementMatchSelection,
+  element: TimelineElement,
+  selectionSourceFile: string,
+): boolean {
+  return (
+    matchesByDomId(selection, element, selectionSourceFile) ||
+    matchesByCompositionHost(selection, element) ||
+    matchesBySelector(selection, element)
+  );
+}
+
 export function findMatchingTimelineElementId(
-  selection: Pick<
-    DomEditSelection,
-    "id" | "selector" | "selectorIndex" | "sourceFile" | "compositionSrc" | "isCompositionHost"
-  >,
+  selection: ElementMatchSelection,
   elements: TimelineElement[],
 ): string | null {
   const selectionSourceFile = selection.sourceFile || "index.html";
-  for (const element of elements) {
-    const elementSourceFile = element.sourceFile || "index.html";
-    if (
-      selection.id &&
-      element.domId === selection.id &&
-      elementSourceFile === selectionSourceFile
-    ) {
-      return element.key ?? element.id;
-    }
-    if (
-      selection.isCompositionHost &&
-      selection.compositionSrc &&
-      element.compositionSrc === selection.compositionSrc
-    ) {
-      return element.key ?? element.id;
-    }
-    if (
-      selection.selector &&
-      element.selector === selection.selector &&
-      (element.selectorIndex ?? 0) === (selection.selectorIndex ?? 0) &&
-      (element.sourceFile ?? "index.html") === selection.sourceFile
-    ) {
-      return element.key ?? element.id;
-    }
+  const match = elements.find((el) => elementMatchesSelection(selection, el, selectionSourceFile));
+  if (match) return match.key ?? match.id;
+
+  // Child inside a sub-composition: return a qualified ID so the expansion
+  // hook can resolve the child via clipParentMap even though no timeline
+  // element exists for it yet (the expansion creates it on the fly).
+  if (selection.id && selectionSourceFile !== "index.html") {
+    return `${selectionSourceFile}#${selection.id}`;
   }
 
   return null;