fix(sdk,studio,lint): keep link groups inside inline compositions

A link group now stays inside the nearest data-composition-id or
data-composition-file ancestor. The SDK used to recognise only file hosts,
and Studio compared only sourceFile, so an inline child composition that
reused a link id was edited together with the root group. core/media-link
linkScopeOf is the shared rule for the SDK and Studio. Lint cannot import
core, so it uses the same two attributes directly. Studio rows record their
compositionScope, and link and merge refuse pairs that cross it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: vanceingalls

packages/core/src/mediaLink.ts

@@ -53,6 +53,11 @@ export function linkTimingMismatches(members: readonly AttributeReader[]): strin
   ).map(([, field]) => field);
 }
 
+/** The composition a link group stays inside: the nearest inline composition or file host. */
+export function linkScopeOf(el: Element): Element | null {
+  return el.parentElement?.closest("[data-composition-id], [data-composition-file]") ?? null;
+}
+
 export function mintLinkId(taken: Iterable<string>): string {
   const used = new Set(taken);
   let n = 1;

packages/lint/src/rules/linkedClips.test.ts

@@ -70,4 +70,14 @@ describe("linked clip rules", () => {
       [],
     );
   });
+
+  it("treats an inlined file host as its own composition too", async () => {
+    const hosted = `<div id="host" data-composition-file="child.html" data-start="0">
+      <video ${VIDEO.replace('id="talk"', 'id="h-talk"').replace('data-start="2"', 'data-start="5"')}></video>
+    </div>`;
+    const findings = await linkFindings(
+      `<video ${VIDEO}></video><audio ${AUDIO}></audio>${hosted}`,
+    );
+    expect(findings.map((f) => [f.code, f.elementId])).toEqual([["linked_clip_orphan", "h-talk"]]);
+  });
 });

packages/lint/src/rules/linkedClips.ts

@@ -39,7 +39,11 @@ function compositionScopeOf(tag: OpenTag, compositions: readonly OpenTag[]): num
 }
 
 function groupByLink(tags: readonly OpenTag[]): Map<string, { link: string; members: OpenTag[] }> {
-  const compositions = tags.filter((tag) => readAttr(tag.raw, "data-composition-id") !== null);
+  const compositions = tags.filter((tag) =>
+    ["data-composition-id", "data-composition-file"].some(
+      (name) => readAttr(tag.raw, name) !== null,
+    ),
+  );
   const groups = new Map<string, { link: string; members: OpenTag[] }>();
   for (const tag of tags) {
     const link = readAttr(tag.raw, "data-link");

packages/sdk/src/engine/linkedTiming.ts

@@ -1,6 +1,6 @@
-import { MEDIA_LINK_ATTR } from "@hyperframes/core/media-link";
+import { MEDIA_LINK_ATTR, linkScopeOf } from "@hyperframes/core/media-link";
 import type { HfId } from "../types.js";
-import { escapeHfId, isNewHostBoundary, querySelectorAllDeep, resolveScoped } from "./model.js";
+import { escapeHfId, querySelectorAllDeep, resolveScoped } from "./model.js";
 
 interface LinkMember {
   id: HfId;
@@ -12,22 +12,15 @@ function scopePrefix(id: HfId): string {
   return cut < 0 ? "" : id.slice(0, cut + 1);
 }
 
-function hostScopeOf(el: Element): Element | null {
-  for (let cur = el.parentElement; cur; cur = cur.parentElement) {
-    if (isNewHostBoundary(cur)) return cur;
-  }
-  return null;
-}
-
 /** Every element sharing `id`'s link, addressed in `id`'s scope, `id` included. */
 function linkGroup(document: Document, id: HfId): LinkMember[] {
   const el = resolveScoped(document, id);
   const link = el?.getAttribute(MEDIA_LINK_ATTR);
   if (!el || !link) return [];
-  const scope = hostScopeOf(el);
+  const scope = linkScopeOf(el);
   const prefix = scopePrefix(id);
   return querySelectorAllDeep(scope ?? document, `[${MEDIA_LINK_ATTR}="${escapeHfId(link)}"]`)
-    .filter((member) => hostScopeOf(member) === scope)
+    .filter((member) => linkScopeOf(member) === scope)
     .map((member) => member.getAttribute("data-hf-id"))
     .filter((hfId): hfId is string => Boolean(hfId))
     .map((hfId) => ({ id: `${prefix}${hfId}`, link }));

packages/sdk/src/session.linked.test.ts

@@ -56,13 +56,16 @@ describe("setTiming on linked clips", () => {
     expect(attr(html, "hf-talk-audio", "data-start")).toBe("4");
   });
 
-  it("keeps a link group inside its own composition when a child reuses the id", async () => {
+  it.each([
+    'data-composition-id="child" data-composition-file="child.html"',
+    'data-composition-file="child.html"',
+  ])("keeps a link group inside its own composition (host %s)", async (host) => {
     const comp = await openComposition(
       `
 <div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">
   <video data-hf-id="hf-v" src="talk.mp4" muted data-link="lk-1" data-start="0" data-duration="4" data-track-index="0"></video>
   <audio data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="0" data-duration="4" data-track-index="1"></audio>
-  <div data-hf-id="hf-host" data-composition-id="child" data-composition-file="child.html" data-start="0" data-duration="10" data-track-index="2">
+  <div data-hf-id="hf-host" ${host} data-start="0" data-duration="10" data-track-index="2">
     <video data-hf-id="hf-cv" src="b.mp4" muted data-link="lk-1" data-start="0" data-duration="4" data-track-index="0"></video>
     <audio data-hf-id="hf-ca" src="b.mp4" data-link="lk-1" data-start="0" data-duration="4" data-track-index="1"></audio>
   </div>
@@ -79,4 +82,32 @@ describe("setTiming on linked clips", () => {
     expect(attr(html, "hf-v", "data-start")).toBe("2");
     expect(attr(html, "hf-a", "data-start")).toBe("2");
   });
+
+  it("keeps a link group inside an inline composition that reuses the id", async () => {
+    const comp = await openComposition(
+      `
+<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">
+  <video data-hf-id="hf-v" src="talk.mp4" muted data-link="lk-1" data-start="0" data-duration="4" data-track-index="0"></video>
+  <audio data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="0" data-duration="4" data-track-index="1"></audio>
+  <div data-hf-id="hf-child" data-composition-id="child" data-start="0" data-duration="10" data-track-index="2">
+    <video data-hf-id="hf-cv" src="b.mp4" muted data-link="lk-1" data-start="5" data-duration="4" data-track-index="0"></video>
+    <audio data-hf-id="hf-ca" src="b.mp4" data-link="lk-1" data-start="5" data-duration="4" data-track-index="1"></audio>
+  </div>
+</div>`.trim(),
+    );
+    comp.setTiming("hf-v", { start: 2 });
+    let html = comp.serialize();
+    expect(attr(html, "hf-a", "data-start")).toBe("2");
+    expect(attr(html, "hf-cv", "data-start")).toBe("5");
+    expect(attr(html, "hf-ca", "data-start")).toBe("5");
+    comp.setTiming("hf-cv", { start: 6 });
+    html = comp.serialize();
+    expect(attr(html, "hf-ca", "data-start")).toBe("6");
+    expect(attr(html, "hf-v", "data-start")).toBe("2");
+    comp.setTiming("hf-ca", { start: 7 }, { linked: false });
+    html = comp.serialize();
+    expect(attr(html, "hf-cv", "data-link")).toBeNull();
+    expect(attr(html, "hf-v", "data-link")).toBe("lk-1");
+    expect(attr(html, "hf-a", "data-link")).toBe("lk-1");
+  });
 });

packages/studio/src/components/editor/mediaLinkEdits.test.ts

@@ -249,10 +249,13 @@ describe("predicates compare the whole asset path", () => {
     expect(canLinkPair([el("v", "video", one), el("a", "audio", two)])).toBe(false);
   });
 
-  it("resolves each src against its own source file", () => {
+  it("resolves each src against its own source file, and links only inside one", () => {
     const v = el("v", "video", { src: "../assets/talk.mp4", sourceFile: "scenes/a.html" });
     const a = el("a", "audio", { src: "./assets/talk.mp4", sourceFile: "index.html" });
-    expect(canLinkPair([v, a])).toBe(true);
+    expect(canLinkPair([v, a])).toBe(false);
+    expect(
+      canLinkPair([v, { ...a, src: "../assets/./talk.mp4", sourceFile: "scenes/a.html" }]),
+    ).toBe(true);
   });
 
   it("does not take a same-id link from another source file as the merge partner", () => {
@@ -261,6 +264,13 @@ describe("predicates compare the whole asset path", () => {
     expect(findMergePair(v, [v, a])).toBeNull();
   });
 
+  it("does not link or merge a pair split across inline compositions", () => {
+    const v = el("v", "video", { muted: true, compositionScope: "main" });
+    const a = el("a", "audio", { compositionScope: "child" });
+    expect(canLinkPair([v, a])).toBe(false);
+    expect(findMergePair(v, [v, a])).toBeNull();
+  });
+
   it("does not merge a hidden audio back into a visible video", () => {
     const v = el("v", "video", { muted: true });
     expect(findMergePair(v, [v, el("a", "audio", { hidden: true })])).toBeNull();

packages/studio/src/components/editor/mediaLinkEdits.ts

@@ -1,6 +1,6 @@
 import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
 import { MEDIA_LINK_ATTR, mintLinkId } from "@hyperframes/core/media-link";
-import type { TimelineElement } from "../../player/store/timelineElement";
+import { sameCompositionScope, type TimelineElement } from "../../player/store/timelineElement";
 import { mediaAssetIdentity, sharesLinkGroup } from "../../player/components/audioClipLink";
 import {
   applyPatchByTarget,
@@ -180,7 +180,7 @@ type TimedElement = Pick<
   TimelineElement,
   "id" | "key" | "tag" | "src" | "start" | "duration" | "playbackStart" | "playbackRate" | "link"
 > &
-  Pick<TimelineElement, "muted" | "hasAudio" | "hidden" | "sourceFile">;
+  Pick<TimelineElement, "muted" | "hasAudio" | "hidden" | "sourceFile" | "compositionScope">;
 
 const tagOf = (el: Pick<TimelineElement, "tag">) => el.tag.trim().toLowerCase();
 const keyOf = (el: Pick<TimelineElement, "id" | "key">) => el.key ?? el.id;
@@ -195,9 +195,9 @@ function hasIdenticalTiming(a: TimedElement, b: TimedElement): boolean {
   );
 }
 
-const sameFile = (a: TimedElement, b: TimedElement) => {
+const sameAssetInScope = (a: TimedElement, b: TimedElement) => {
   const asset = mediaAssetIdentity(a);
-  return asset !== null && asset === mediaAssetIdentity(b);
+  return asset !== null && asset === mediaAssetIdentity(b) && sameCompositionScope(a, b);
 };
 
 /** A video whose sound is on the video itself: what Detach audio acts on. */
@@ -217,7 +217,8 @@ export function findMergePair<T extends TimedElement>(
   if (!isVideo && tagOf(element) !== "audio") return null;
   const partnerTag = isVideo ? "audio" : "video";
   const candidates = elements.filter(
-    (el) => keyOf(el) !== keyOf(element) && tagOf(el) === partnerTag && sameFile(el, element),
+    (el) =>
+      keyOf(el) !== keyOf(element) && tagOf(el) === partnerTag && sameAssetInScope(el, element),
   );
   const partner =
     candidates.find((el) => sharesLinkGroup(el, element)) ??
@@ -237,7 +238,7 @@ export function canLinkPair(selected: readonly TimedElement[]): boolean {
   const tags = new Set([tagOf(a), tagOf(b)]);
   if (!tags.has("video") || !tags.has("audio")) return false;
   if (sharesLinkGroup(a, b)) return false;
-  return sameFile(a, b) && hasIdenticalTiming(a, b);
+  return sameAssetInScope(a, b) && hasIdenticalTiming(a, b);
 }
 
 type TrackedElement = Pick<TimelineElement, "tag" | "track" | "start" | "duration"> & {

packages/studio/src/player/components/audioClipLink.test.ts

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, expect, it } from "vitest";
 import {
   audioPillFlags,
@@ -6,6 +7,7 @@ import {
   linkedMembersOf,
   mediaAssetIdentity,
 } from "./audioClipLink";
+import { createTimelineElementFromManifestClip, parseTimelineFromDOM } from "../lib/timelineDOM";
 
 const video = { id: "talk", link: "lk-1" };
 const audio = { id: "talk-audio", link: "lk-1" };
@@ -65,7 +67,7 @@ describe("expandToLinkedMembers", () => {
   });
 });
 
-describe("link groups stay inside their source file", () => {
+describe("link groups stay inside their composition", () => {
   const root = [
     { id: "v", link: "lk-1", sourceFile: undefined },
     { id: "a", link: "lk-1", sourceFile: undefined },
@@ -82,6 +84,48 @@ describe("link groups stay inside their source file", () => {
       new Set(["child.html#cv", "child.html#ca"]),
     );
   });
+
+  const media = (id: string, tag: string, start: number) =>
+    `<${tag} id="${id}" class="clip" src="${id}.mp4" data-link="lk-1" data-start="${start}" data-duration="4"></${tag}>`;
+  const inlineDoc = () => {
+    const doc = document.implementation.createHTMLDocument();
+    doc.body.innerHTML = `<div data-composition-id="main" data-duration="20">
+      ${media("v", "video", 0)}${media("a", "audio", 0)}
+      <div id="child" data-composition-id="child" data-start="0" data-duration="10">
+        ${media("cv", "video", 5)}${media("ca", "audio", 5)}
+      </div>
+    </div>`;
+    return doc;
+  };
+
+  it("does not pull an inline composition's same-id link into the root group", () => {
+    const rows = parseTimelineFromDOM(inlineDoc(), 20).filter((row) => row.link);
+    const byId = (id: string) => rows.find((row) => row.domId === id) ?? video;
+    expect(linkedMembersOf(byId("v"), rows).map((row) => row.domId)).toEqual(["v", "a"]);
+    expect(linkedMembersOf(byId("cv"), rows).map((row) => row.domId)).toEqual(["cv", "ca"]);
+  });
+
+  it("keeps the inline composition apart on rows built from the runtime manifest", () => {
+    const doc = inlineDoc();
+    const rows = ["v", "a", "cv", "ca"].map((id, fallbackIndex) =>
+      createTimelineElementFromManifestClip({
+        clip: {
+          ...{ id, label: id, start: 0, duration: 4, track: 0, kind: "video", tagName: "video" },
+          ...{
+            compositionId: null,
+            parentCompositionId: null,
+            compositionSrc: null,
+            assetUrl: null,
+          },
+        },
+        fallbackIndex,
+        doc,
+        hostEl: doc.getElementById(id),
+      }),
+    );
+    const [rootVideo] = rows;
+    expect(linkedMembersOf(rootVideo ?? video, rows).map((row) => row.domId)).toEqual(["v", "a"]);
+  });
 });
 
 describe("linkedMembersOf", () => {

packages/studio/src/player/components/audioClipLink.ts

@@ -1,6 +1,7 @@
-import type { TimelineElement } from "../store/timelineElement";
+import { sameCompositionScope, type TimelineElement } from "../store/timelineElement";
 
-type LinkedElement = Pick<TimelineElement, "id" | "key" | "link" | "sourceFile">;
+type LinkScoped = Pick<TimelineElement, "sourceFile" | "compositionScope">;
+type LinkedElement = Pick<TimelineElement, "id" | "key" | "link"> & LinkScoped;
 
 const keyOf = (element: Pick<TimelineElement, "id" | "key">) => element.key ?? element.id;
 
@@ -24,10 +25,10 @@ function isLinked(element: Pick<TimelineElement, "link">): boolean {
 }
 
 export function sharesLinkGroup(
-  a: Pick<TimelineElement, "link" | "sourceFile">,
-  b: Pick<TimelineElement, "link" | "sourceFile">,
+  a: Pick<TimelineElement, "link"> & LinkScoped,
+  b: Pick<TimelineElement, "link"> & LinkScoped,
 ): boolean {
-  return isLinked(a) && a.link === b.link && (a.sourceFile ?? "") === (b.sourceFile ?? "");
+  return isLinked(a) && a.link === b.link && sameCompositionScope(a, b);
 }
 
 export function audioPillFlags(

packages/studio/src/player/lib/timelineDOM.ts

@@ -12,6 +12,7 @@ import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip, IframeWindow, TimelineLike } from "./playbackTypes";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import { readClipTiming } from "@hyperframes/core/composition-contract";
+import { linkScopeOf } from "@hyperframes/core/media-link";
 import { createRuntimeStartTimeResolver } from "@hyperframes/core/runtime/start-resolver";
 import { groupInfoFor } from "./timelineGroupInfo";
 import { transitionLabelsForDocument } from "./timelineTransitionMetadata";
@@ -152,6 +153,8 @@ export function createTimelineElementFromManifestClip(params: {
     if (timelineRole) entry.timelineRole = timelineRole;
     const link = hostEl.getAttribute("data-link");
     if (link) entry.link = link;
+    const compositionScope = linkScopeOf(hostEl)?.getAttribute("data-composition-id");
+    if (compositionScope) entry.compositionScope = compositionScope;
     const audioGroup = hostEl.getAttribute("data-audio-group");
     if (audioGroup) {
       entry.audioGroup = audioGroup;
@@ -341,6 +344,8 @@ export function parseTimelineFromDOM(
     if (timelineRole) entry.timelineRole = timelineRole;
     const domLink = el.getAttribute("data-link");
     if (domLink) entry.link = domLink;
+    const domCompositionScope = linkScopeOf(el)?.getAttribute("data-composition-id");
+    if (domCompositionScope) entry.compositionScope = domCompositionScope;
 
     const domAudioGroup = el.getAttribute("data-audio-group");
     if (domAudioGroup) {